Skip to content
Conversation APIs
/
Conversation Manager
/
/Channel

Conversation Manager APIs

This section provides the requisite APIs needed to create Conversation Manager accounts and to configure conversation workflows. To create the Conversation Manager acccount, use the Conversation APIs in this order when setting up a complete eGain application:

  • Authentication
  • Client Application
  • Participant
  • Channel
  • Orchestration
  • Account

After the account is created you can use the following APIs to send / receive messages.

  • Conversation
  • Asset

Note: You can configure your system to use third party Bots and third party Channels. The API instructions provided here assume you are using eGain's application setup.

Download OpenAPI description
api-bundled.json
api-bundled.yaml
Overview
URL
https://apidev.egain.com
API Support
apisupport@egain.com
Languages
Servers
Production Server
https://api.egain.cloud/conversation/conversationmgr/v3

Authentication

Use this API to register client callback Authentication methods using oAuth or Basic Authentication.

Operations

Client Application

Use this API to register external client applications where we send and receive messages.

Operations

Participant

Use this API to register Bots. You can register multiple Bots for each client application.

Operations

Channel

Use this API to register and define channel parameters which is used for chat messages.

Operations

Create Channel

Request

Overview

Use this API to register and define custom channel parameters in the Conversation Manager which is used for chat messages. New Account API process flow: Authenticiation > Client Application > Participant > Channel > Orchestration > Account

Note: You can configure your system to use third party Channels. The API instructions provided here assume you are using eGain's application setup.

Scope

Client application must have 'app.conversation.conversationmgr.manage' scope assigned.

Security
oAuthClient(Required scopes:
https://api.egain.cloud/auth/.de...
)
Bodyapplication/json

Register new custom channel

typestring[ 1 .. 255 ] charactersrequired

Unique channel type. Do not prefix with 'custom.' for channels supported by eGain.

Example: "custom.teams"
displayNamestring[ 1 .. 255 ] charactersrequired
Example: "Teams"
iconstring[ 1 .. 512000 ] charactersrequired

base64 encoded image. This icon is used in eGain Chat Advisor desktop for activities of this channel. If eGain Chat is used for live agents then use icon file in ‘png’ format with pixel dimensions 32 X 32.

descriptionstring[ 1 .. 1023 ] characters
activeboolean
Default true
restrictionsobject(Restrictions)

Channel restriction on inbound(from customer) and outbound( to customer) messages.

l10nPropertiesArray of objects(L10nProperties)[ 1 .. 25 ] items
curl -i -X POST \
  https://api.egain.cloud/conversation/conversationmgr/v3/channels \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "custom_channel",
    "icon": "<base64>",
    "displayName": "Custom Channel",
    "description": "Custom Channel",
    "active": true,
    "restrictions": {
      "inbound": {
        "maxTextLength": 140,
        "features": [
          "typing_events",
          "attachments",
          "richText"
        ],
        "attachmentPolicy": {
          "enabled": true,
          "maxSize": 12345,
          "type": "block",
          "extensions": [
            "bat",
            "exe"
          ]
        }
      },
      "outbound": {
        "maxTextLength": 140,
        "systemMessages": true,
        "midChatAuth": true,
        "features": [
          "typing_events",
          "attachments",
          "richText"
        ],
        "richMessageTypes": [
          "listpicker",
          "quickreply",
          "timepicker",
          "richlink"
        ],
        "attachmentPolicy": {
          "enabled": true,
          "maxSize": 12345,
          "type": "allow",
          "extensions": [
            "jpeg",
            "txt"
          ]
        }
      }
    },
    "l10nProperties": [
      {
        "language": "en-US",
        "properties": [
          {
            "name": "msg_hub_retain_and_retry",
            "value": "Thank you for reaching out. We will respond to you at the earliest."
          },
          {
            "name": "msg_hub_off_hours",
            "value": "Thank you for your inquiry. Our service hours are 9am-5pm PST, Monday-Friday. If you are trying within the service hours and still getting this message, please try again after some time."
          },
          {
            "name": "msg_hub_invalid_content_type_to_customer",
            "value": "This content type is not currently supported."
          },
          {
            "name": "msg_hub_invalid_content_type_to_agent",
            "value": "This content type is not currently supported."
          },
          {
            "name": "msg_hub_channel_msg_failed",
            "value": "Message could not be delivered. Please try again after some time."
          },
          {
            "name": "msg_hub_blocked_file_extension",
            "value": "Attachment file type '\''{0}'\'' is not allowed."
          },
          {
            "name": "msg_hub_attachment_size_exceeds_limit",
            "value": "File could not be sent. It exceeded the maximum limit of {0}"
          }
        ]
      }
    ]
  }'

Responses

Created

Bodyapplication/json
idstring= 36 characters

UUID generated for the object.

Response
application/json
{
  "id": "45a095f4-d0ee-4220-a689-22b541c58f67"
}

Get Channels

Request

Overview

Use this API to Get all channel details for the Conversation Manager.

Scope

Client application must have 'app.conversation.conversationmgr.manage' or 'app.conversation.conversationmgr.read' scope assigned.

Security
oAuthClient(Required scopes:
https://api.egain.cloud/auth/.de...
)
curl -i -X GET \
  https://api.egain.cloud/conversation/conversationmgr/v3/channels \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
paginationInfoobject(PaginationInfo)
channelArray of objects(GetChannelData)
Example: [{"id":"6121306b-59c2-4a2c-afee-1e025a84b0d9","type":"custom_channel","icon":"<base64>","displayName":"Custom Channel","description":"Custom Channel","active":true,"created":"2021-06-11T21:14:41.836Z","modified":"2021-06-11T23:14:41.836Z","restrictions":{"inbound":{"maxTextLength":140,"features":["typing_events","attachments","richText"],"attachmentPolicy":{"enabled":true,"maxSize":12345,"type":"block","extensions":["bat","exe"]}},"outbound":{"maxTextLength":140,"systemMessages":true,"midChatAuth":true,"features":["typing_events","attachments","richText"],"richMessageTypes":["listpicker","timepicker","richlink"],"attachmentPolicy":{"enabled":true,"maxSize":12345,"type":"block","extensions":["bat","exe"]}}},"l10nProperties":[{"language":"en-US","properties":[{"name":"msg_hub_retain_and_retry","value":"Thank you for reaching out. We will respond to you at the earliest."},{"name":"msg_hub_off_hours","value":"Thank you for your inquiry. Our service hours are 9am-5pm PST, Monday-Friday. If you are trying within the service hours and still getting this message, please try again after some time."},{"name":"msg_hub_invalid_content_type_to_customer","value":"This content type is not currently supported."},{"name":"msg_hub_invalid_content_type_to_agent","value":"This content type is not currently supported."},{"name":"msg_hub_channel_msg_failed","value":"Message could not be delivered. Please try again after some time."},{"name":"msg_hub_blocked_file_extension","value":"Attachment file type '{0}' is not allowed."},{"name":"msg_hub_attachment_size_exceeds_limit","value":"File could not be sent. It exceeded the maximum limit of {0}"}]}]}]
Response
application/json
{
  "channel": [
    { … }
  ]
}

Get Channel

Request

Overview

Use this API to Get channel detail information in the Conversation Manager.

Scope

Client application must have 'app.conversation.conversationmgr.manage' or 'app.conversation.conversationmgr.read' scope assigned.

Security
oAuthClient(Required scopes:
https://api.egain.cloud/auth/.de...
)
Path
idstring= 36 charactersrequired

id of object

Example: 7b6c5fff-036e-4a40-b68a-a67c592fc079
curl -i -X GET \
  https://api.egain.cloud/conversation/conversationmgr/v3/channels/7b6c5fff-036e-4a40-b68a-a67c592fc079 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
idstring= 36 characters
createdstring(date-time)

Last modified time in GMT

modifiedstring(date-time)

Last modified time in GMT

typestring[ 1 .. 255 ] characters

Unique channel type. Do not prefix with 'custom.' for channels supported by eGain.

Example: "custom.teams"
displayNamestring[ 1 .. 255 ] characters
Example: "Teams"
iconstring[ 1 .. 512000 ] characters

base64 encoded image. This icon is used in eGain Chat Advisor desktop for activities of this channel. If eGain Chat is used for live agents then use icon file in ‘png’ format with pixel dimensions 32 X 32.

descriptionstring[ 1 .. 1023 ] characters
activeboolean
Default true
restrictionsobject(Restrictions)

Channel restriction on inbound(from customer) and outbound( to customer) messages.

l10nPropertiesArray of objects(L10nProperties)[ 1 .. 25 ] items
Response
application/json
{
  "id": "6121306b-59c2-4a2c-afee-1e025a84b0d9",
  "type": "custom_channel",
  "icon": "<base64>",
  "displayName": "Custom Channel",
  "description": "Custom Channel",
  "active": true,
  "created": "2021-06-11T21:14:41.836Z",
  "modified": "2021-06-11T23:14:41.836Z",
  "restrictions": {
    "inbound": { … },
    "outbound": { … }
  },
  "l10nProperties": [
    { … }
  ]
}

Update Channel

Request

Overview

Use this API to update an existing channel in the Conversation Manager with your specific custom requirements.

Scope

Client application must have 'app.conversation.conversationmgr.manage' scope assigned.

Security
oAuthClient(Required scopes:
https://api.egain.cloud/auth/.de...
)
Path
idstring= 36 charactersrequired

id of object

Example: 7b6c5fff-036e-4a40-b68a-a67c592fc079
Bodyapplication/json

Update channel

typestring[ 1 .. 255 ] charactersrequired

Unique channel type. Do not prefix with 'custom.' for channels supported by eGain.

Example: "custom.teams"
displayNamestring[ 1 .. 255 ] charactersrequired
Example: "Teams"
iconstring[ 1 .. 512000 ] charactersrequired

base64 encoded image. This icon is used in eGain Chat Advisor desktop for activities of this channel. If eGain Chat is used for live agents then use icon file in ‘png’ format with pixel dimensions 32 X 32.

descriptionstring[ 1 .. 1023 ] characters
activeboolean
Default true
restrictionsobject(Restrictions)

Channel restriction on inbound(from customer) and outbound( to customer) messages.

l10nPropertiesArray of objects(L10nProperties)[ 1 .. 25 ] items
modifiedstring(date-time)

Last modified time in GMT

curl -i -X PUT \
  https://api.egain.cloud/conversation/conversationmgr/v3/channels/7b6c5fff-036e-4a40-b68a-a67c592fc079 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "custom_channel",
    "icon": "<base64>",
    "displayName": "Custom Channel",
    "description": "Custom Channel",
    "active": true,
    "modified": "2021-06-11T23:14:41.836Z",
    "restrictions": {
      "inbound": {
        "maxTextLength": 140,
        "features": [
          "typing_events",
          "attachments",
          "richText"
        ],
        "attachmentPolicy": {
          "enabled": true,
          "maxSize": 12345,
          "type": "block",
          "extensions": [
            "bat",
            "exe"
          ]
        }
      },
      "outbound": {
        "maxTextLength": 140,
        "systemMessages": true,
        "midChatAuth": true,
        "features": [
          "typing_events",
          "attachments",
          "richText"
        ],
        "richMessageTypes": [
          "listpicker",
          "quickreply",
          "timepicker",
          "richlink"
        ],
        "attachmentPolicy": {
          "enabled": true,
          "maxSize": 12345,
          "type": "block",
          "extensions": [
            "bat",
            "exe"
          ]
        }
      }
    },
    "l10nProperties": [
      {
        "language": "en-US",
        "properties": [
          {
            "name": "msg_hub_retain_and_retry",
            "value": "Thank you for reaching out. We will respond to you at the earliest."
          },
          {
            "name": "msg_hub_off_hours",
            "value": "Thank you for your inquiry. Our service hours are 9am-5pm PST, Monday-Friday. If you are trying within the service hours and still getting this message, please try again after some time."
          },
          {
            "name": "msg_hub_invalid_content_type_to_customer",
            "value": "This content type is not currently supported."
          },
          {
            "name": "msg_hub_invalid_content_type_to_agent",
            "value": "This content type is not currently supported."
          },
          {
            "name": "msg_hub_channel_msg_failed",
            "value": "Message could not be delivered. Please try again after some time."
          },
          {
            "name": "msg_hub_blocked_file_extension",
            "value": "Attachment file type '\''{0}'\'' is not allowed."
          },
          {
            "name": "msg_hub_attachment_size_exceeds_limit",
            "value": "File could not be sent. It exceeded the maximum limit of {0}"
          }
        ]
      }
    ]
  }'

Responses

No Content

Response
No content

Delete Channel

Request

Overview

Use this API to delete a channel in the Conversation Manager. A channel can not be deleted if it is in use in the client application.

Scope

Client application must have 'app.conversation.conversationmgr.manage' scope assigned.

Security
oAuthClient(Required scopes:
https://api.egain.cloud/auth/.de...
)
Path
idstring= 36 charactersrequired

id of object

Example: 7b6c5fff-036e-4a40-b68a-a67c592fc079
curl -i -X DELETE \
  https://api.egain.cloud/conversation/conversationmgr/v3/channels/7b6c5fff-036e-4a40-b68a-a67c592fc079 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

No Content

Response
No content

Orchestration

Use this API to configure workflows for conversation between participants (Customer/Agent/Bot applications).

Operations

Account

Use this API to create the Conversation Account for Conversation Manager.

Operations

Conversation

Use this API to send messages through the Conversation Manager.

Operations

Assets

Use this API to upload/download Assets like attachments.

Operations