AI Agents Chat API

IMPORTANT: It is necessary to have the AI Agent connected to a custom CRM in order to use the Chat API and not to a Messaging Integration. An error will be thrown if a custom CRM is not found.

Use the Chat API to interact with a bot by sending conversation events.

All requests should be made to your API base URL: https://api.ultimate.ai

JSON format

Conversation events are represented as JSON objects with the following properties:

Name	Type	Required	Description
platformConversationId	string	Yes	Unique ID for the conversation, generated by your custom CRM application.
eventType	string	Yes	Type of event. Possible values: "startSession", "message", "endSession", "metadata". See Event types
text	string	No	Message text from the visitor. Not used with "startSession" or "endSession". For button or carousel selection, send the button value as text unless it is a link button.
metaData	object	No	Metadata associated with the user or conversation session. This can be used for personalization or content.
metaData.key	string	Yes	Name of the session parameter
metaData.value	string	Yes	String value for the session parameter
metaData.sanitize	boolean	No	Set to true for personally identifiable information (PII) data.
cardIndex	number	No	Index of the selected card from a carousel. Not used with startSession or endSession. Card indexes begin at 0

Event types

• startSession: Starts a new conversation. If a welcome message is configured, it is sent in response. If omitted, the session starts on the first message.
• message: Sends a message from the visitor to the bot.
• endSession: Explicitly ends the conversation. If not called, the session automatically closes after a configurable timeout.
• metadata: Adds additional metadata to the conversation session.

Converse with a Bot

• POST /converse/chat

Sends an event to initiate or continue a conversation with a bot. The API acknowledges your message with a 200 OK and processes it asynchronously. Any response from the bot is delivered via your configured webhook.

Example body

{
  "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
  "eventType": "I want to request a refund",
  "text": "string",
  "metaData": {
    "key": "user_id",
    "value": "1234",
    "sanitize": true
  },
  "cardIndex": 0
}

Parameters

Name	Type	In	Required	Description
Authorization	string	header	Yes	API key for the bot. Generate this from the Custom CRM integration page in the Ultimate.ai dashboard. For more information, see Authentication
botid	string	header	Yes	The id of the bot sending or receiving the event

Example response(s)

200

The request has been acknowledge and will be processed. The actual response will come through webhooks.

400

Bad request. The request body is invalid or missing required fields.

401

Unauthorized. Missing or invalid API key or bot ID.

403

Forbidden. AI Agent not using custom CRM.

404

Not found. The specified endpoint does not exist.