Skip to main content
Skip table of contents

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:

  1. Navigate to your OCPminiApps.

  2. Select a miniApp and click on it to open its settings.

  3. Go to the Chat tab and find the key token within the Webchat Configuration section.

chat_tab.png

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:

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.

JavaScript errors detected

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

If this problem persists, please contact our support.