Skip to content
Conversation APIs
/
Conversation Manager
/
/Client Application

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

Create Client Application

Request

Overview

API to register new Client Applications that can integrate with the Conversation Hub. Client applications are used to send and receive messages. New Account API process flow: Authenticiation > Client Application > Participant > Channel > Orchestration > Account

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 client application

namestring[ 1 .. 255 ] charactersrequired

Unique name for client application

descriptionstring[ 1 .. 1023 ] characters
activeboolean
Default true
rolesArray of objects(Role)[ 1 .. 7 ] itemsrequired
roles[].​namestring[ 1 .. 255 ] charactersuniquerequired

Client aplication type

Enum"customer""custom_bot""egain_bot""egain_agent""custom_agent""business_notification"
roles[].​versionstringrequired

Conversation Hub will send payload which is specific to this version.

Enum"v1""v3"
Example: "v3"
roles[].​callbackstring[ 1 .. 1023 ] charactersrequired

Callback API to recieve messages from Conversation Hub sent by various participants in conversation. Callback APIs needs to respond within 5 seconds. We strongly recommend to process message asynchronously. API must return 401 if Authorization header is expired, Conversation Hub will generate new Authorization header on 401.

Example: "https://example.support.com/messaging/callback/customer"
roles[].​notificationEmailstring[ 1 .. 255 ] charactersrequired

If client application callback is not reachable, Conversation Hub sends a notification to this email address

Example: "admin@example.com"
roles[].​headersArray of objects(Attribute)[ 1 .. 25 ] items

Custom headers for callback, Conversation Hub will include these while sending message to callback

roles[].​authenticationobject

Authentication for callback API.

curl -i -X POST \
  https://api.egain.cloud/conversation/conversationmgr/v3/clientapplications \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "custom_bot_client_application_1",
    "description": "Client app for Eva bot",
    "active": true,
    "roles": [
      {
        "name": "custom_bot",
        "version": "v3",
        "callback": "https://example.support.com/messaging/customBot",
        "notificationEmail": "client_app_admin@example.com",
        "headers": [
          {
            "name": "X-custom-header",
            "value": "xyz"
          }
        ],
        "authentication": {
          "id": "34fbb53f-ed7f-48d4-b545-e26cc95e075d"
        }
      }
    ]
  }'

Responses

Created

Bodyapplication/json
idstring= 36 characters

UUID generated for the object.

Response
application/json
{
  "id": "9e1d7993-cc82-4d5f-a193-0d6b0d48a959"
}

Get Client Applications

Request

Overview

Use this APi to get details of all Client applications.

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/clientapplications \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
paginationInfoobject(PaginationInfo)
clientApplicationArray of objects(GetClientApplicationData)
Response
application/json
{
  "clientApplication": [
    { … },
    { … }
  ]
}

Get Client Application

Request

Overview

Use this API to get details of the Client application 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/clientapplications/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

namestring[ 1 .. 255 ] charactersrequired

Unique name for client application

descriptionstring[ 1 .. 1023 ] characters
activeboolean
Default true
rolesArray of objects(Role)[ 1 .. 7 ] itemsrequired
roles[].​namestring[ 1 .. 255 ] charactersuniquerequired

Client aplication type

Enum"customer""custom_bot""egain_bot""egain_agent""custom_agent""business_notification"
roles[].​versionstringrequired

Conversation Hub will send payload which is specific to this version.

Enum"v1""v3"
Example: "v3"
roles[].​callbackstring[ 1 .. 1023 ] charactersrequired

Callback API to recieve messages from Conversation Hub sent by various participants in conversation. Callback APIs needs to respond within 5 seconds. We strongly recommend to process message asynchronously. API must return 401 if Authorization header is expired, Conversation Hub will generate new Authorization header on 401.

Example: "https://example.support.com/messaging/callback/customer"
roles[].​notificationEmailstring[ 1 .. 255 ] charactersrequired

If client application callback is not reachable, Conversation Hub sends a notification to this email address

Example: "admin@example.com"
roles[].​headersArray of objects(Attribute)[ 1 .. 25 ] items

Custom headers for callback, Conversation Hub will include these while sending message to callback

roles[].​authenticationobject

Authentication for callback API.

Response
application/json
{
  "id": "9e1d7993-cc82-4d5f-a193-0d6b0d48a959",
  "name": "custom_bot_client_application_1",
  "description": "Client app for Eva bot",
  "active": true,
  "roles": [
    { … }
  ]
}

Update Client Application

Request

Overview

Use this API to update an existing Client application registered with the Conversation Manager.

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 Client application

namestring[ 1 .. 255 ] charactersrequired

Unique name for client application

descriptionstring[ 1 .. 1023 ] characters
activeboolean
Default true
rolesArray of objects(Role)[ 1 .. 7 ] itemsrequired
roles[].​namestring[ 1 .. 255 ] charactersuniquerequired

Client aplication type

Enum"customer""custom_bot""egain_bot""egain_agent""custom_agent""business_notification"
roles[].​versionstringrequired

Conversation Hub will send payload which is specific to this version.

Enum"v1""v3"
Example: "v3"
roles[].​callbackstring[ 1 .. 1023 ] charactersrequired

Callback API to recieve messages from Conversation Hub sent by various participants in conversation. Callback APIs needs to respond within 5 seconds. We strongly recommend to process message asynchronously. API must return 401 if Authorization header is expired, Conversation Hub will generate new Authorization header on 401.

Example: "https://example.support.com/messaging/callback/customer"
roles[].​notificationEmailstring[ 1 .. 255 ] charactersrequired

If client application callback is not reachable, Conversation Hub sends a notification to this email address

Example: "admin@example.com"
roles[].​headersArray of objects(Attribute)[ 1 .. 25 ] items

Custom headers for callback, Conversation Hub will include these while sending message to callback

roles[].​authenticationobject

Authentication for callback API.

modifiedstring(date-time)

Last modified time in GMT

curl -i -X PUT \
  https://api.egain.cloud/conversation/conversationmgr/v3/clientapplications/7b6c5fff-036e-4a40-b68a-a67c592fc079 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "custom_bot_client_application_1",
    "description": "Client app for Eva bot",
    "active": true,
    "roles": [
      {
        "name": "custom_bot",
        "version": "v3",
        "callback": "https://example.support.com/messaging/customBot",
        "notificationEmail": "client_app_admin@example.com",
        "authentication": {
          "id": "34fbb53f-ed7f-48d4-b545-e26cc95e075d"
        }
      }
    ]
  }'

Responses

No Content

Response
No content

Delete Client Application

Request

Overview

Use this APi to delete a Client application. If client application is used by a participant then it can not be deleted.

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/clientapplications/7b6c5fff-036e-4a40-b68a-a67c592fc079 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

No Content

Response
No content

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

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