Chat integrations/REST API
Batch chat message endpoint
Concepts
- You can send chat messages to your AI agents over the REST API.
- Complex chat messages requests can take a long time, and the message endpoint could time-out because of this.
- The batch chat message returns a batchJobId, which you can then poll the get batch message endpoint with to check when the results are ready.
The batch chat message endpoint
Go to the agent's project page to get your:
- User profile id
- Project environment id
Go the the agent's details page to get the:
- Agent id
Send a POST request to https://server-name/api/v1/chat/batch-message with
the following JSON in the body:
| Name | Type | Required | Description |
|---|---|---|---|
| userProfileId | string | yes | The internal user profile id. |
| externalUserId | string | no | The user's id in your system. |
| chatSessionId | string | no (*1) | The internal chat session id. |
| externalChatSessionId | string | no (*1) | The chat session id in your system. |
| projectEnvId | string | yes | The project's environment id. |
| agentId | string | yes | The agent's id. |
| filters | json | no | Specified to filter entity data in the prompt. |
| messages | string | yes | Stringified JSON of an array of messages to send. |
*1: You only need to specify either a chatSessionId or externalChatSessionId. For a new chat session, only the externalChatSessionId needs to be specified if it will be used at all.
A chatSessionId is returned and can be used to reference the session in future message calls.
The filters parameter JSON is defined as:
| Name | Type | Required | Description |
|---|---|---|---|
| includeEntities | string | no | Include entities: all (defaut) or filtered (only entities in the filtered list). |
| entityFilters | json[] | yes | An array of JSON specifying how to filter each entity. |
The entityFilter JSON is defined as:
| Name | Type | Required | Description |
|---|---|---|---|
| entityId | string | yes | The id of the entity (from the entity's page). |
| select | string[] | no | An array of fields to select in camelCase. |
| where | JSON | no | A JSON map of fields (in camelCase) to values. |
This endpoint will return a batchJobId. You can then poll the
get batch message endpoint with the batchJobId,
which will return the chat message results once ready.