Create an intent

Create an intent when you want to give Zeus contact or intent attributes and select the agent channel that should evaluate the request. For an API chat, this endpoint is optional: sending the first message can initialize a thread with empty attributes instead.

Back to the API overview

POST https://api.openfi.tech/v1/intents
Content-Type: application/json
x-api-key: YOUR_API_KEY

A successful call may create an initial outgoing message, depending on the selected agent's flow and the current conversation state.

Request body

Field	Type	Required	Description
`source`	string	Yes	A non-empty label for where the intent originated, such as website-chat or quote-form.
`predefinedAgentChannelId`	UUID	Yes	The account-owned Zeus agent channel that should evaluate the intent.
`contact`	object	Yes	The associated contact.
`contact.attributes`	object	Yes	Contact attributes configured for the account. Use an empty object when none are needed.
`contact.communicationChannels`	array	Yes	One or more ways to identify or reach the contact. The array cannot be empty.
`contact.communicationChannels[].type`	string	Yes	The configured channel type: api, whatsapp, twilio-sms, widget, or test.
`contact.communicationChannels[].id`	string	Yes	The contact's non-empty identifier on that channel. For an API channel, use your stable end-user or chat-session ID.
`attributes`	object	Yes	Intent attributes configured for the account. Use an empty object when none are needed.

Account-specific attributes

The accepted keys in contact.attributes and the top-level attributes object come from your Zeus account configuration. Each configured field is optional, but both objects must be present.

Values must match the configured type: string, number, boolean, or one of the configured enum options. String attributes contain between 1 and 255 characters. Account-specific validation rules may also apply. Unknown keys or invalid values return 400 Bad Request.

Configure an attribute in Zeus before including it in a request.

Choose an agent channel

predefinedAgentChannelId is the ID of a configured agent channel, not an agent ID or phone number. It must belong to the account associated with the API key, and its channel type must match at least one item in contact.communicationChannels.

For a server-to-server chat, select an api agent channel and include an api contact communication channel. Put your stable external identifier in its id request field, then use that same value as the contactChannelExternalId on the message endpoints. This request field is not a Zeus internal channel ID.

Contact the Zeus team if you do not know the configured agent channel ID.

Example request

Load the API key into ZEUS_API_KEY from your secret manager or a secure shell prompt.

A successful request may cause Zeus to contact the recipient. Test with a configured test user, source, matching channel, and only attributes configured for your account.

curl --request POST 'https://api.openfi.tech/v1/intents' \
  --header 'Content-Type: application/json' \
  --header "x-api-key: ${ZEUS_API_KEY}" \
  --data '{
    "source": "website-chat",
    "predefinedAgentChannelId": "YOUR_API_AGENT_CHANNEL_ID",
    "contact": {
      "attributes": {},
      "communicationChannels": [
        {
          "type": "api",
          "id": "customer-user-123"
        }
      ]
    },
    "attributes": {}
  }'

Response

A successful request returns 201 Created:

{
  "intentId": "56ce9e6d-6b39-4702-8444-9574fa74a167"
}

The ID identifies the intent accepted for this request. It may be a newly created intent or an applicable existing intent. This response does not confirm that an outgoing message was created or delivered. Use webhooks to receive conversation updates.

Errors and retries

Status	Meaning
`400 Bad Request`	The body is invalid, contains an unknown attribute, references an unavailable agent channel, or has no contact channel matching the selected agent channel type.
`401 Unauthorized`	The x-api-key header is missing or invalid.
`409 Conflict`	The applicable conversation is currently managed by a human.
`429 Too Many Requests`	The account exceeded 5,000 intent requests in one hour. Follow Retry-After before retrying.
`500 Internal Server Error`	The request outcome may be unknown. Do not assume that no intent or message was created.

This endpoint does not accept an idempotency key. Avoid automatically repeating a request after an ambiguous timeout or 500 response unless your integration can tolerate the current intent-selection behavior.