Chat API (REST API)

Overview

This documentation outlines the methods for creating and managing messages, attachments, and chat sessions using our REST API. It provides a detailed overview of the available endpoints and describes the structure of messages that can be sent and received through these endpoints.

Authentication

The Chat API operates using a special form of authorization rather than traditional authentication mechanisms. To interact with a miniApp via the Chat connector REST API, you are required to include an Authorization header in the HTTP requests. The header must contain the API key token, prefixed with Bearer. Therefore, the value should be formatted like this: Bearer {token}.

Obtaining the API Key Token

Each miniApp has a unique API key token that is essential for establishing communication through the Chat connector.

To find your miniApp's API key token, follow the guidelines below:

Navigate to your OCP → miniApps.
Select a miniApp and click on it to open its settings.
Go to the Chat tab and find the key token within the Webchat Configuration section.

Error Codes

Omilia's HTTP response codes can be found on the HTTP Code Responses page.

API Reference

{{baseUrl}} depends on the user's environment which could be the following:

EU1 - https://eu1-m.ocp.ai/chat

US1 - https://us1-m.ocp.ai/chat

US2 - https://us2-m.ocp.ai/chat

US1W - https://us1-w-m.ocp.ai/chat

Dialogs

This API enables interaction with a chatbot by handling user inputs and generating appropriate responses from the bot..

POST	{{baseUrl}}/dialogs	Communicates with Chat connector.

Click to see the details

Endpoint for communication with Chat connector via REST.

Headers

Content-type: application/json

Body Parameters

Parameter	Type	Required	Description
`User-Agent`	String	No	Identifies the client software making the request. This parameter typically includes information about the browser, operating system, and device. For example: `Mozilla/5.0 (Windows NT 10.0; Win64; x64)`

Request Body

JSON

{
  "dialog_id": "string",
  "utterance": "string",
  "user": {
    "user_id": "string",
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "fullname": "string",
    "phone_number": "string",
    "username": "string"
  },
  "semantics": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "input_fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

Parameter		Type	Required	Description
`dialog_id`		String	No	Unique identifier for the dialog session. This parameter should be left empty when starting a new dialog. Then, for every subsequent dialog step, it should be set to the `dialog_id` value returned in the first dialog response.
`utterance`		String	Yes	The actual text input from the user.
`user`		Object	No	Contains information about the user initiating the request.
	`user_id`	String	No	Unique identifier for the user.
	`email`	String	No	User's email.
	`first_name`	String	No	User's first name.
	`last_name`	String	No	User's last name.
	`fullname`	String	No	User's full name.
	`phone_number`	String	No	User's phone number.
	`username`	String	No	User's username.
`samantics`		Map	No	Contains key-value string pairs with semantic information related to the request. These properties can be defined based on the application requirements.
`input_fields`		Map	No	Contains input fields to be passed to the DiaManT.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "dialog_id": "string",
  "action_type": "string",
  "responses": [
    {
      "prompts": [
        {
          "content": "This is a sample prompt",
          "masked_content": "******/6"
        }
      ],
      "ui_component": "ButtonList"
    }
  ],
  "meta": {
    "additionalProp1": {},
    "additionalProp2": {},
    "additionalProp3": {}
  },
  "outgoing_data": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

Parameter			Type	Description
`dialog_id`			String	The ID of the current dialog
`action_type`			String	Action type.
`responses`			Array of objects	List of responses.
	`prompts`		Array of objects	List of prompts.
		`content`	String	The content of the prompt.
		`masked_content`	String	Optional property provided by DiaManT when the prompt contains sensitive data.
	`ui_component`		String	The type of the UI component. The following values are allowed: ButtonList Calendar Form GenericList Metadata MixedList Table
`meta`			Object	Metadata.
`outgoing_data`			Object	Outgoing data.

ButtonList

Represents a list of interactive buttons that can be rendered in different styles such as grids, inline buttons, cards, or quick replies.

Parameter		Type	Description
`type`		String	Specifies the type of button list. Accepted values are: `BUTTON_GRID`, `INLINE_BUTTONS`,`CARD`, `QUICK_REPLIES`.
`title`		String	The title of the button list.
`subtitle`		String	An optional subtitle providing additional context or description.
`image_url`		String	URL of the image to be displayed alongside the button list.
`options`			A list of button options. Each option is an object containing the following attributes:
	`label`	String	The label text to display on the button.
	`url`	String	The URL that the button should link to.
	`image_url`	String	An optional URL for an image to display on the button.
	`context`	Object	An optional object containing contextual information relevant to the button.

Calendar

Represents a calendar view with various parameters allowing for customization of dates, times, and contextual information.

Parameter		Type	Description
`type`		Array	Specifies the type of the UI component. Accepted value is `CALENDAR`.
`title`		String	A title for the calendar.
`subtitle`		String	An optional subtitle providing additional context or description.
`timezone`		String	The timezone for the calendar entries.
`view`		String	The view mode of the calendar (for example, monthly, weekly, daily).
`date_range`		Object	An object specifying the date range for the calendar.
	`start_date`	String	The start date in the format `YYYY-MM-DD`.
	`end_date`	String	The end date in the format `YYYY-MM-DD`.
`time_range`			An object specifying the time range for the calendar.
	`start_date`	String	The start date in the format `YYYY-MM-DD`.
	`end_date`	String	The end date in the format `YYYY-MM-DD`.
`time_slots`			An array specifying available time slots.
	`start`	String	The start time of the slot in the format `HH:MM`.
	`end`	String	The end time of the slot in the format `HH:MM`.
	`description`	String	An optional description for the time slot.
	`context`	Object	An optional object containing additional contextual information relevant to the calendar.

Form

Represents a form view with various parameters.

Parameter		Type	Description
`type`		Array	Specifies the type of the UI component. Accepted value is `FORM`.
`title`		String	A title for the form meant to provide a brief summary or heading.
`subtitle`		String	An optional subtitle providing additional context or description.
`input_fields`		Object	An object containing input fields of the form.
	`type`	String	The type of field. For example, `text`, `email`, `password`.
	`required`	Boolean	Specifies if the field is mandatory of optional.
	`sensitive`	Boolean	Specifies if the field contains sensitive information.
	`label`	String	The input text label.
	`placeholder`	String	A short hint, displayed in the input field before the user enters a value, which indicates the expected input format.
	`tip`	String	Additional helpful information near the input field to clarify requirements or provide examples.
	`entity`	String	Associated entity name for the input field.
	`entity_value`	String	Default or current value for the input field's entity.

GenericList

Represents a generic list that can be rendered in different styles such as carousel and vertical list.

Parameter			Type	Description
`type`			String	Specifies the type of generic list. Accepted values are: `CAROUSEL`, `VERTICAL_LIST`.
`title`			String	The title of the generic list.
`subtitle`			String	An optional subtitle providing additional context or description.
`image_url`			String	URL of the image to be displayed alongside the generic list.
`options`			Object	A list of generic list options. Each option is an object containing the following attributes:
	`label`		String	The label text to display next to a generic list option.
	`url`		String	The URL that the generic list option should link to.
	`image_url`		String	An optional URL for an image to display on the generic list option.
	`context`		Object	An optional object containing contextual information relevant to the generic list option.
`entries`				List of entries in the generic list.
	`header`		String	Header text for an entry.
	`details`		String	Detailed text for an entry.
	`image_url`		String	URL of the image to be displayed with an entry.
	`options`		Object	List of button options associated with an entry.
		`label`	String	The label text to display next to a generic list entry.
		`url`	String	The URL that the generic list entry should link to.
		`image_url`	String	An optional URL for an image to display on the generic list entry.
		`context`	Object	An optional object containing contextual information relevant to the generic list entry.

Metadata

Represents client specific metadata.

Parameter	Type	Description
`type`	String	Specifies the type of the UI component. Accepted value is `METADATA`.
`meta`	Object	Metadata.

MixedList

Represents a mixed list.

Parameter		Type	Description
`type`		Array	Specifies the type of the UI component. Accepted value is `MIXED`.
`title`		String	A title for the mixed list meant to provide a brief summary or heading.
`subtitle`		String	An optional subtitle providing additional context or description.
`entries`		Array of objects	List of entries, each of entries having the following attributes:
	`header`	String	The header or title for an entry item in the mixed list.
	`details`	String	The detailed text or description for an entry item.
`interactive_option`			List of interactive option objects for user interaction.
	context	Object	Optional data that should be returned to the server when selected.
	label	String	Label text for the interactive option.

Table

Represents a table.

Parameter		Type	Description
`type`		String	Specifies that the type of the UI component is a table. Accepted value is `"TABLE"`.
`template`		String	Template type for the table.
`title`		String	Title of the table.
`subtitle`		String	Subtitle of the table.
`image_url`		String	URL of the image to be displayed with the table.
`columns`		Array	List of column definitions, each object in the list defines a column.
	`index`	Integer	The index of the column, used to sort or identify columns.
	`name`	String	The internal name of the column, used for data binding or processing.
	`label`	String	The label of the column, displayed as the header in the table.
`records`		Array	Table data. Each record contains `index` and `image` fields, and also it may contain dynamic fields with additional properties.
	`index`	Integer	The index of the record, used for sorting or identifying records.
	`image`	String	URL of the image to be displayed for the record.

Status

This API provides comprehensive information about the current state of the chatbot.

GET	{{baseUrl}}/status	Retrieves the status of the connector.

Click to see the details

Response (Success)

JSON

HTTP/1.1 200 OK

Example

JSON

{
  "message": "Some message",
  "version": "8.5.0",
  "name": "chat-connector"
}

Parameter	Type	Description
`message`	String	The content of the message.
`version`	String	The current version of Chat connector.
`name`	String	Shows the name of the service. Its value is always set to `chat-connector`.

Agent messages

The Agent messages API is used by contact centers to send messages or events while the dialog is transferred to a live agent.

Talkdesk dialog transfer

POST	{{baseUrl}}/transfer/talkdesk	Talkdesk transfer endpoint.

Click to see the details

The endpoint is used by Talkdesk to send messages from an agent to Chat connector.

Headers

Content-type: application/json

Request Body

JSON

{
  "event_type": "message_created",
  "conversation_id": "string",
  "timestamp": "string",
  "payload": {
    "id": "string",
    "content": "string",
    "created_at": "string",
    "author": {
      "name": "string",
      "type": "string"
    }
  }
}

Parameter			Type	Required	Description
`event_type`			String	Yes	The type of the event.
`conversation_id`			String	Yes	The ID of the conversation.
`timestamp`			String	No	The timestamp of the message.
`payload`			Object	Yes	The payload of the message.
	`id`		String	Yes	The message ID.
	`content`		String	Yes	The text of the message.
	`created_at`		String	Yes	The time when message was created.
	`author`		Object	Yes	Author of the message.
		`name`	String	No	The name of the agent.
		`type`	String	No	Type of the agent.

Response (Success)

JSON

HTTP/1.1 200 OK

Cfront dialog transfer

POST	{{baseUrl}}/transfer/cfront	Cfront transfer endpoint.

Click to see the details

The endpoint is used by CFront to send messages from an agent to Chat connector.

Headers

Content-type: application/json

Request Body

JSON

{
  "State": "string",
  "CFrontServiceID": "string",
  "ConversationID": "string",
  "Agent": "string",
  "Content": {},
  "ReferenceData": "string"
}

Parameter	Type	Required	Description
`State`	String	Yes	The state of the chat session that is identified by `ConversationID`. Allowed values are: `Active` – For normal agent messages; `Typing` – The `Content` is `true` when the agent is typing and `false` when the agent stops typing; `Ended` – The agent leaves the chat session – empty `Content`; `System` – For system messages that may not need to be exposed; `Error` – When error occurs in CFront – `Content` may include details.
`CFrontServiceID`	String	Yes	The identifier of the CFront Chat Service.
`ConversationID`	String	Yes	The identification number of the conversation.
`Agent`	String	No	The agent that entered the message.
`Content`	Object	No	The content of the message.
`ReferenceData`	String	Yes	The ReferenceData of the `startchat` method.

Response (Success)

JSON

HTTP/1.1 200 OK

Attachments

This API is used to handle attachments during a dialog. It can be used only for dialogs created using the Websockets API.

POST	{{baseUrl}}/attachments	Uploads an attachment.

Click to see the details

Uploads an attachment file with session ID, utterance, and client message ID.

Headers

Content-type: multipart/form-data

Form data

Parameter	Type	Required	Description
`session_id`	String	Yes	Session ID associated with the attachment.
`utterance`	String	No	Utterance related to the attachment.
`client_message_id`	String	No	Client message ID associated with the attachment.

Response (Success)

JSON

HTTP/1.1 200 OK

Attachment uploaded successfully.

Response (Invalid)

JSON

HTTP/1.1 400

Invalid input or bad request.