Chat Session API

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	`true` - the user is currently typing, `false` - the user has stopped typing.
`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	`true` - the user is currently typing, `false` - the user has stopped typing.
`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:

ButtonList

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.

Form

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.

Metadata

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.