Skip to main content
Skip table of contents

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.