Overview
The Chat Session API provides methods to create and manage chat sessions through WebSocket communication. This document describes the available endpoints and the structure of the messages that can be sent and received through these endpoints.
Base endpoint
WebSocket endpoint:
wss://{host}/ws/session
Replace {host}
with the appropriate hostname to connect to the WebSocket server.
Message types
The Chat Session API uses JSON messages that are grouped into the following categories:
In a separate section, you will also find Rich Content that provides description of buttons, lists, grid, and so on.
Requests
Below you will see the incoming messages accepted by the API, and their detailed description.
ChatSessionStartRequest
This API request initiates a new chat session. Upon successful creation, the server responds with a ChatSessionStartResponse.
Click to see the details
Payload example
JSON
{
"api_key": "string",
"input_fields": {
"field1": "value1"
"field2": "value2"
},
"client_message_id": "string",
"type": "start_session_req",
"utterance": "string"
}
Parameter | Type | Required | Description |
---|
api_key
| String | Yes | The API key used for authentication. |
input_fields
| Object | No | Key-value input data to be sent to DiaManT at the start of the dialog. Additional properties are allowed. |
client_message_id
| String | No | A client-provided UUID for tracking the message. This should be unique for each request sent. It will be returned by related events. |
type
| String | Yes | The type of the request. It must be set to start_session_req for session initiation. |
utterance
| String | No | The user's utterance. If provided, it will be sent to DiaManT at the start of the dialog. |
DialogStartRequest
This API request is used to initiate a new dialog within the context of an already established chat session. Essentially, you should use this request if a dialog that began with a ChatSessionStartRequest has ended, but the client needs to create a new dialog within the same chat session.
Click to see the details
Payload example
JSON
{
"api_key": "string",
"session_id": "string",
"input_fields": {
"field1": "value1"
"field2": "value2"
},
"client_message_id": "string",
"type": "start_dialog_req",
"utterance": "string"
}
Parameter | Type | Required | Description |
---|
api_key
| String | Yes | The API key used for authentication. |
session_id
| String | Yes | The chat session ID. |
input_fields
| Object | No | Key-value input data to be sent to DiaManT at the start of the dialog. Additional properties are allowed. |
client_message_id
| String | No | A client-provided UUID for tracking the message. This will be returned by related events. |
type
| String | Yes | The type of the request. It must be set to start_dialog_req for dialog initiation. |
utterance
| String | No | The user's utterance. If provided, it will be sent to DiaManT at the start of the dialog. |
DialogMessageRequest
This API request is used to send a user's message within an active dialog session. This request ensures that the user's input is correctly routed either to an agent if the dialog is transferred, or to DiaManT for automated processing.
Click to see the details
Payload example
JSON
{
"api_key": "string",
"session_id": "string",
"input_fields": {
"field1": "value1"
"field2": "value2"
},
"client_message_id": "string",
"semantics": {
"field1": "value1"
"field2": "value2"
},
"type": "dialog_req",
"utterance": "string"
}
Parameter | Type | Required | Description |
---|
api_key
| String | Yes | The API key used for authentication. |
session_id
| String | Yes | The chat session ID. |
input_fields
| Object | No | Key-value input data to be sent to DiaManT. Additional properties are allowed. |
client_message_id
| String | No | A client-provided UUID for tracking the message. This will be returned by related events. |
semantics
| Object | No | Rich content related Key-Value input data. Additional properties are allowed. |
type
| String | Yes | The type of the request. It must be set to dialog_req . |
utterance
| String | Yes | The user's utterance. |
ChatSessionResumeRequest
This API request is used to resume an existing chat session. Upon initiation of this request, the connector will send back each DialogMessageEvent and StateEvent as separate WebSocket messages. Essentially, this request is useful in the event of a network disconnection. Once reconnected, the client should send this request to resume the chat session.
Click to see the details
Payload example
JSON
{
"from_sequence_id": 0,
"api_key": "string",
"session_id": "string",
"client_message_id": "string",
"type": "session_resume_req"
}
Parameter | Type | Required | Description |
---|
from_sequence_id
| Integer | No | If provided, the connector will return messages starting from this sequence ID and higher. It helps in resuming from a specific point in the message sequence. |
api_key
| String | Yes | The API key used for authentication. |
session_id
| String | Yes | The unique ID of the chat session that is being resumed. This ID is originally generated when the session is first created. |
client_message_id
| String | No | A client-provided UUID for tracking the message. This will be returned by related events. |
type
| String | Yes | The type of the request. It must be set to session_resume_req . |
ChatSessionHistoryRequest
This API request is used to retrieve the history of a specific chat session. The connector will send back each DialogMessageEvent and StateEvent as separate WebSocket messages. You can control the range of messages returned by specifying the from_sequence_id
and to_sequence_id
parameters.
Click to see the details
Payload example
JSON
{
"from_sequence_id": 0,
"api_key": "string",
"session_id": "string",
"to_sequence_id": 0,
"client_message_id": "string",
"type": "session_history_req"
}
Parameter | Type | Required | Description |
---|
from_sequence_id
| Integer | No | If provided, the connector will return messages starting from this sequence ID and higher. It helps in resuming from a specific point in the message sequence. |
api_key
| String | Yes | The API key used for authentication. |
session_id
| String | Yes | The chat session ID. |
to_sequence_id
| Integer | No | The sequence ID at which to stop returning messages. If provided, the connector will return messages with equal or lower sequence ID. If not provided, the history will include messages up to the latest one.
|
client_message_id
| String | No | A client-provided UUID for tracking the message. This will be returned by related events. |
type
| String | Yes | The type of the request. It must be set to session_history_req . |
ChatSessionStopRequest
This API request is used to stop a chat session. The connector will remove the session and attempt to end the current active dialog.
Click to see the details
Payload example
JSON
{
"api_key": "string",
"session_id": "string",
"client_message_id": "string",
"type": "stop_session_req"
}
Parameter | Type | Required | Description |
---|
api_key
| String | Yes | The API key used for authentication |
session_id
| String | Yes | The chat session ID. |
client_message_id
| String | No | A client-provided UUID for tracking the message. This will be returned by related events. |
type
| String | Yes | The type of the request. It must be set to stop_session_req . |
TypingRequest
This API request is used to indicate the user's typing status in an active chat session. This status helps convey whether the user is actively typing or has stopped typing. The server uses this information to manage the chat session more efficiently and provide real-time feedback.
Click to see the details
Payload example
JSON
{
"typing_on": true,
"api_key": "string",
"session_id": "string",
"client_message_id": "string",
"type": "typing_req"
}
Parameter | Type | Required | Description |
---|
typing_on
| Boolean | Yes | |
api_key
| String | Yes | The API key used for authentication |
session_id
| String | Yes | The chat session ID. |
client_message_id
| String | No | A client-provided UUID for tracking the message. This will be returned by related events. |
type
| String | Yes | The type of the request. It must be set to typing_req . |
Responses/Events
In this section you will find the description of the messages that are sent by chat connector.
ChatSessionStartResponse
This is the server's response to ChatSessionStartRequest. This response confirms the successful initiation of a new chat session and provides the necessary details for subsequent interactions within the session.
Click to see the details
Payload example
JSON
{
"session_id": "string",
"type": "start_session_resp"
}
Parameter | Type | Required | Description |
---|
session_id
| Sring | Yes | The unique identifier for the chat session. This ID should be used for all further requests within this chat session. |
type
| String | Yes | The type of the response. This is a constant value set to start_session_resp . |
DialogMessageEvent
This event is used for messages originating from the user, bot, or agent and is stored in the chat session history. The sequence_id
must always be set. Different fields are set depending on the message source.
Click to see the details
Payload example
JSON
{
"transfer_info": {
"agent_id": "string",
"dialog_id": "string",
"transfer_id": "string",
"agent_label": "string"
},
"action_type": "string",
"sequence_id": 0,
"session_id": "string",
"dialog_id": "string",
"client_message_id": "string",
"source": "USER",
"type": "dialog_message_event",
"dialog_response": {
"prompt": {
"masked_content": "string",
"content": "string"
},
"ui_component": {
"type": "string"
}
},
"utterance": "string"
}
Parameter | Type | Required | Description |
---|
transfer_info
| Object | Yes | Used only for messages from the agent and contains additional information about the agent and transfer. Additional properties are allowed. |
| agent_id
| String | Yes | The ID of the agent. |
| dialog_id
| String | No | Dialog ID associated with the transfer. |
| transfer_id
| String | No | Transfer ID for the session. |
| agent_label
| String | No | Label for the agent. |
action_type
| String | No | Used only for messages from the bot (DiaManT). Specifies the action type of the DiaManT response. |
sequence_id
| Integer | No | Sequence ID of the event, used for tracking the order in the chat session history. |
session_id
| String | Yes | The chat session ID. |
dialog_id
| String | No | The DiaManT dialog ID. |
client_message_id
| String | No | A unique ID for the client message, provided by the client and returned for reference. |
source
| String | Yes | The origin of the message. The following values are allowed: "USER" , "BOT" , "AGENT" . |
type
| String | Yes | The type of the event. It is set to dialog_message_event . |
dialog_response
| Object | No | Used only for messages from the bot (DiaManT). It contains prompt or ui_component . |
| prompt
| Object | No | Contains the prompt details. |
| | content
| String | No | The prompt text. |
| | masked_content
| String | No | The prompt text with masked sensitive information. |
| ui_component
| Object | No | Contains rich content as part of the response. |
| type
| String | No | Type of the UI component. |
utterance
| String | No | The actual text message or utterance from the user or agent. |
StateEvent
This event is used to notify the client on important state changes. State events are stored in the chat session history.
Click to see the details
Payload example
JSON
{
"metadata": {
"field1": "value1",
"field2": "value2"
},
"sequence_id": 0,
"session_id": "string",
"dialog_id": "string",
"client_message_id": "string",
"state": "DIALOG_END",
"type": "state_event"
}
Parameter | Type | Required | Description |
---|
metadata
| Object | No | A map containing additional properties relevant to the event. Additional properties are allowed. |
sequence_id
| Integer | No | Sequence ID of the event, used for tracking the order in the chat session history. |
session_id
| String | Yes | The chat session ID. |
dialog_id
| String | No | The DiaManT dialog ID. |
client_message_id
| String | No | A unique ID for the client message, provided by the client and returned for reference. |
state
| String | Yes | The state event code. Allowed values are: "DIALOG_END" , "TRANSFERRED" , "AGENT_JOINED" , "AGENT_LEFT" . |
type
| String | Yes | The type of the event. It is set to state_event . |
ErrorEvent
This event is used to notify the client that an error occurred. In most cases error events are sent only to the connection that sent a request. Error events are NOT stored in the history.
Click to see the details
Payload example
JSON
{
"sequence_id": 0,
"session_id": "string",
"dialog_id": "string",
"client_message_id": "string",
"error_code": "UNAUTHORIZED",
"type": "error_event"
}
Parameter | Type | Required | Description |
---|
sequence_id
| Integer | No | The sequence ID of the event. It is used only for events that should be stored in chat session history. |
session_id
| String | Yes | The chat session ID. |
dialog_id
| String | No | The DiaManT dialog ID. |
client_message_id
| String | No | A unique ID for the client message, provided by the client and returned for reference. |
error_code
| String | Yes | Error code of the event. The following values may be returned: "UNAUTHORIZED" , "SESSION_NOT_FOUND" , "SESSION_ALREADY_EXISTS" , "DIALOG_NOT_FOUND" , "MESSAGE_REJECTED" , "INTERNAL_ERROR" , "BAD_REQUEST"
|
type
| String | Yes | The type of the event. It is set to error_event . |
TypingEvent
This event is used to notify the client that the bot or agent has started or stopped typing.
Click to see the details
Payload example
JSON
{
"typing_on": true,
"sequence_id": 0,
"session_id": "string",
"dialog_id": "string",
"client_message_id": "string",
"type": "typing_event"
}
Parameter | Type | Required | Description |
---|
typing_on
| Boolean | Yes | |
sequence_id
| Integer | No | The sequence ID of the event. It is used only for events that should be stored in chat session history. |
session_id
| String | Yes | The chat session ID. |
dialog_id
| String | No | The DiaManT dialog ID. |
client_message_id
| String | No | A unique ID for the client message, provided by the client and returned for reference. |
type
| String | Yes | The type of the event. It is set to typing_event . |
AttachmentEvent
This event is triggered when an attachment is successfully uploaded by the user to the agent platform. It provides details about the file and its type. The sequence_id
is always included, and the event is recorded in the chat session history.
Click to see the details
Payload example
JSON
{
"file_name": "string",
"file_type": "string",
"sequence_id": 7,
"session_id": "string",
"dialog_id": "string",
"client_message_id": "string",
"type": "attachment_event",
"file_size": 128,
"utterance": "string"
}
Parameter | Type | Required | Description |
---|
file_name
| String | Yes | The name of the file uploaded as an attachment. |
file_type
| String | Yes | The type of the file uploaded as an attachment. MIME file types are allowed for this field. For example: image/jpeg, application/pdf, image/png, and so on. |
sequence_id
| Integer | No | The sequence ID of the event. It is used only for events that should be stored in chat session history. |
session_id
| String | Yes | The chat session ID. |
dialog_id
| String | No | The DiaManT dialog ID. |
client_message_id
| String | No | A unique ID for the client message, provided by the client and returned for reference. |
type
| String | Yes | The type of the event. It is set to attachment_event . |
file_size
| Integer | Yes | The size of the file uploaded as an attachment. Measurement unit: byte. |
utterance
| String | No | The utterance that was optionally sent with the attachment |
Rich Content
Part of response that represents rich content, such as buttons, grid, and so on. It is present in the DialogMessageEvent message as the ui_component
parameter.
Posible structures:
Represents a list of buttons.
Click to see the details
Payload example
JSON
{
"type": "CARD",
"title": "string",
"subtitle": "string",
"image_url": "string",
"options": [
{
"label": "string",
"url": "string",
"image_url": "string",
"context": {}
}
]
}
Parameter | Type | Required | Description |
---|
type
| String | Yes | Type of the rich content. The following values are allowed: “BUTTON_GRID" , “INLINE_BUTTONS" , “CARD" , “QUICK_REPLIES" . |
title
| String | No | Title of the rich content. |
subtitle
| String | No | Subtitle of the rich content. |
image_url
| String | No | URL of the image to be displayed. |
options
| Array of strings | No | List of buttons associated with the rich content. |
| label
| String | No | Label to be displayed on the button. |
| url
| String | No | URL to be navigated to when the button is clicked. |
| image_url
| String | No | URL of the image to be displayed on the button. |
| context
| Object | No | This field contains Key-Value pairs and is only used for non-URL buttons. When the button is clicked, the client should send these Key-Value pairs back to the connector in the semantics field of DialogMessageRequest. |
GenericList
Represents a generic list.
Click to see the details
Payload example
JSON
{
"type": "CAROUSEL",
"title": "string",
"subtitle": "string",
"image_url": "string",
"entries": [
{
"header": "string",
"details": "string",
"image_url": "string",
"options": [
{
"label": "string",
"url": "string",
"image_url": "string",
"context": {}
}
]
}
]
}
Parameter | Type | Required | Description |
---|
type
| String | Yes | Type of the rich content. The following values are allowed: "CAROUSEL" , "VERTICAL_LIST" . |
title
| String | No | Title of the rich content. |
subtitle
| String | No | Subtitle of the rich content. |
image_url
| String | No | URL of the image to be displayed. |
entries
| Array | No | List of entries in the generic list. |
| header
| String | No | Header text for an entry. |
| details
| String | No | Detailed text for an entry. |
| image_url
| String | No | URL of the image to be displayed with an entry. |
| options
| Array of strings | No | List of button options associated with an entry. |
| | label
| String | No | Label to be displayed on the button. |
| | url
| String | No | URL to be navigated to when the button is clicked. |
| | image_url
| String | No | URL of the image to be displayed on the button. |
| | context
| Object | No | This field contains Key-Value pairs and is only used for non-URL buttons. When the button is clicked, the client should send these Key-Value pairs back to the connector in the semantics field of DialogMessageRequest. |
Table
Represents a table.
This type of rich content will be supported in one of the upcoming versions.
Click to see the details
Payload example
JSON
{
"type": "TABLE",
"template": "string",
"title": "string",
"subtitle": "string",
"image_url": "string",
"columns": [
{
"index": 1,
"name": "string",
"label": "string"
}
],
"records": [
{
"index": 1,
"image": "string",
"dynamic_field1": "string",
"dynamic_field2": "string"
}
]
}
Parameter | Type | Required | Description |
---|
type
| String | Yes | Specifies that the content type is a table. The only allowed value here is "TABLE" . |
template
| String | No | Template type for the table. |
title
| String | No | Title of the table. |
subtitle
| String | No | Subtitle of the table. |
image_url
| String | No | URL of the image to be displayed with the table. |
columns
| Array | No | List of column definitions, each object in the list defines a column. |
| index
| Integer | No | The index of the column, used to sort or identify columns. |
| name
| String | No | The internal name of the column, used for data binding or processing. |
| label
| String | No | The label of the column, displayed as the header in the table. |
records
| Array | No | Table data. Each record contains index and image fields, and also it may contain dynamic fields with additional properties. |
| index
| Integer | Yes | The index of the record, used for sorting or identifying records. |
| image
| String | Yes | URL of the image to be displayed for the record. |
| dynamic_field
| String | No | Dynamic fields with additional properties. |
Calendar
Represents a calendar.
This type of rich content will be supported in one of the upcoming versions.
Click to see the details
Payload example
JSON
{
"type": "CALENDAR",
"title": "string",
"subtitle": "string",
"timezone": "string",
"date_range": {
"start_date": "string",
"end_date": "string"
}
"time_range": {
"start_date": "string",
"end_date": "string"
},
"time_slots": [
{
"start": "string",
"end": "string",
"description": "string",
"context": {}
}
]
}
Parameter | Type | Required | Description |
---|
type
| String | Yes | Specifies that the content type is a calendar. The only allowed value here is "CALENDAR" . |
title
| String | No | Optional title for the calendar. |
subtitle
| String | No | Optional subtitle for the calendar. |
timezone
| String | No | Optional timezone for the calendar, specified in a string format. For example, "UTC". |
date_range
| Object | No | Defines the date range for the calendar. |
| start_date
| String | No | Start date of the date range, in a recognized date format (for example, "YYYY-MM-DD"). |
| end_date
| String | No | End date of the date range, in a recognized date format (for example, "YYYY-MM-DD"). |
time_range
| Object | No | Defines the time range for each day in the calendar. |
| start_date
| String | No | Start time of the time range, in a recognized time format (for example, "HH:MM:SS"). |
| end_date
| String | No | End time of the time range, in a recognized time format (for example, "HH:MM:SS"). |
time_slots
| Array | No | List of available time slots within the specified date and time range. |
| start
| String | No | Start time of the time slot, in a recognized time format (for example, "HH:MM:SS"). |
| end
| String | No | End time of the time slot, in a recognized time format (for example, "HH:MM:SS"). |
| description
| String | No | Optional description of the time slot. |
| context
| Object | No | Optional data that should be returned to the server when the time slot is selected. Additional properties are allowed. |
Represents a form.
This type of rich content will be supported in one of the upcoming versions.
Click to see the details
Payload example
JSON
{
"type": "FORM",
"title": "string",
"subtitle": "string",
"input_fields": [
{
"type": "string",
"required": true,
"sensistive": true,
"label": "string",
"placeholder": "string",
"tip": "string",
"entity": "string",
"entity_value": "string"
}
]
}
Parameter | Type | Required | Description |
---|
type
| String | Yes | Type of the rich content. The only allowed value is "FORM" . |
title
| String | No | Optional title for the form. |
subtitle
| String | No | Optional subtitle for the form. |
input_fields
| Array | No | List of input fields included in the form. |
| type
| String | No | Type of the input field (for example, text, email, password). |
| required
| Boolean | No | Specifies if the input field is mandatory. |
| sensitive
| Boolean | No | Indicates if the input field contains sensitive information. |
| label
| String | No | The label displayed to the user for each input field. |
| placeholder
| String | No | Text displayed inside the input field when it is empty. |
| tip
| String | No | Additional help text or tip for the user about the field. |
| entity
| String | No | Associated entity name for the input field. |
| entity_value
| String | No | Default or current value for the input field's entity. |
MixedList
Represents a mixed list.
This type of rich content will be supported in one of the upcoming versions.
Click to see the details
Payload example
JSON
{
"type": "MIXED",
"title": "string",
"subtitle": "string",
"entries": [
{
"header": "string",
"details": "string",
}
],
"interactive_option": [
{
"context": {},
"label": "string",
}
]
}
Parameter | Type | Required | Description |
---|
type
| String | Yes | Specifies that the content type is a a mixed list. The only allowed value is "MIXED" . |
title
| String | No | Optional title for the mixed list. |
subtitle
| String | No | Optional subtitle for the mixed list. |
entries
| Array | No | List of entry objects containing content for the mixed list. |
| header
| String | No | The header or title for an entry item in the mixed list. |
| details
| String | No | The detailed text or description for an entry item. |
interactive_option
| Array | No | List of interactive option objects for user interaction. |
| context
| Object | No | Optional data that should be returned to the server when selected. |
| label
| String | No | Label text for the interactive option. |
Represents client specific metadata.
Click to see the details
Payload example
JSON
{
"type": "META_DATA",
"meta": {
"field1": "value1",
"field2": "value2"
}
}
Parameter | Type | Required | Description |
---|
type
| String | Yes | Type of the rich content. The only allowed value is "META_DATA" . |
meta
| Object | No | An object containing metadata key-value pairs. |