Skip to content
Conversation APIs
/
Conversation Manager
/
/Account

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

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

Create Account

Request

Overview

Use this API to create a Conversation Account for the Conversation Manager. New Account API process flow: Authentication > 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 account

namestring[ 1 .. 255 ] charactersrequired

Unique name for account

descriptionstring[ 1 .. 1023 ] characters
activeboolean
Default true
addressstring[ 1 .. 255 ] charactersrequired

Account ID like email address, phone numbers.

channelobjectrequired
channel.​idstring= 36 characters

UUID generated for account

Example: "c987d07a-d59c-11ea-87d0-0242ac130200"
caseManagementobject(CaseManagement)
chatConfigurationsobject(ChatConfigurations)required
chatConfigurations.​timeoutnumber[ 3 .. 10080 ]

Timeout for conversation created for this account. Time is calculated from last message in conversation. Client applications should start new conversation after timeout.

Default 240
chatConfigurations.​defaultLanguagestring

Default language

Default "en-US"
Example: "en-US"
chatConfigurations.​onAgentUnavailabilitystring

This attribute indicates action on agent unavailability, in case of 'off_hours' if agent is not available then 'off hours' message is sent back. In case of 'retain_and_retry' message is held on Conversation Hub until agent is online

Default "off_hours"
Enum"off_hours""retain_and_retry"
Example: "off_hours"
chatConfigurations.​allowLogoutWithOpenChatsboolean

Allow agents to logout with open messages in their inbox.

Default false
chatConfigurations.​allowQueueTransferOnAgentUnavailabilityboolean

Allow agents to transfer messages back to queue when no agents are available.

Default false
chatConfigurations.​orchestrationobjectrequired
chatConfigurations.​orchestration.​idstring= 36 characters

UUID generated for orchestration object, which will be used for orchestration of conversations for this account

Example: "c987d07a-d59c-11ea-87d0-0242ac13000d"
chatConfigurations.​entryPointobject(EntryPoint)required
chatConfigurations.​entryPoint.​idstring[ 1 .. 255 ] charactersrequired

Unique id of entrypoint in client application

attributesArray of objects(Attribute)[ 1 .. 10 ] items
curl -i -X POST \
  https://api.egain.cloud/conversation/conversationmgr/v3/accounts \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "order_account",
    "address": "123456789",
    "channel": {
      "id": "45a095f4-d0ee-4220-a689-22b541c58f67"
    },
    "chatConfigurations": {
      "timeout": 30,
      "defaultLanguage": "en-US",
      "onAgentUnavailability": "off_hours",
      "allowLogoutWithOpenChats": false,
      "allowQueueTransferOnAgentUnavailability": false,
      "orchestration": {
        "id": "c37e975f-6b2f-490f-9cac-dfa05499f744"
      },
      "entryPoint": {
        "id": "1001"
      }
    }
  }'

Responses

Created

Bodyapplication/json
idstring= 36 characters

UUID generated for the object.

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

Get Accounts

Request

Overview

This APIs allows you to get details of all accounts

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

Responses

OK

Bodyapplication/json
paginationInfoobject(PaginationInfo)
accountArray of objects(GetAccountData)
Example: [{"id":"ae103957-9c82-4fa8-a34e-925be85e06ec","created":"2021-03-21T14:29:01.516Z","modified":"2021-03-28T14:29:01.516Z","name":"order_account","address":"123456789","channel":{"id":"45a095f4-d0ee-4220-a689-22b541c58f67"},"chatConfigurations":{"timeout":30,"defaultLanguage":"en-US","onAgentUnavailability":"off_hours","orchestration":{"id":"c37e975f-6b2f-490f-9cac-dfa05499f744"},"entryPoint":{"id":"1001"}}},{"id":"b5fc053c-77f4-4445-b6df-2e744aef8f4f","created":"2021-03-21T14:29:01.516Z","modified":"2021-03-28T14:29:01.516Z","name":"purplenile_account","address":"123456789","channel":{"id":"45a095f4-d0ee-4220-a689-22b541c58f67"},"chatConfigurations":{"timeout":30,"defaultLanguage":"en-US","onAgentUnavailability":"off_hours","orchestration":{"id":"c37e975f-6b2f-490f-9cac-dfa05499f744"},"entryPoint":{"id":"1001"}}}]
Response
application/json
{
  "account": [
    { … },
    { … }
  ]
}

Get account

Request

Overview

Use this API to get details of a registered Conversation Manager account.

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/accounts/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 account

descriptionstring[ 1 .. 1023 ] characters
activeboolean
Default true
addressstring[ 1 .. 255 ] charactersrequired

Account ID like email address, phone numbers.

channelobjectrequired
channel.​idstring= 36 characters

UUID generated for account

Example: "c987d07a-d59c-11ea-87d0-0242ac130200"
caseManagementobject(CaseManagement)
chatConfigurationsobject(ChatConfigurations)required
chatConfigurations.​timeoutnumber[ 3 .. 10080 ]

Timeout for conversation created for this account. Time is calculated from last message in conversation. Client applications should start new conversation after timeout.

Default 240
chatConfigurations.​defaultLanguagestring

Default language

Default "en-US"
Example: "en-US"
chatConfigurations.​onAgentUnavailabilitystring

This attribute indicates action on agent unavailability, in case of 'off_hours' if agent is not available then 'off hours' message is sent back. In case of 'retain_and_retry' message is held on Conversation Hub until agent is online

Default "off_hours"
Enum"off_hours""retain_and_retry"
Example: "off_hours"
chatConfigurations.​allowLogoutWithOpenChatsboolean

Allow agents to logout with open messages in their inbox.

Default false
chatConfigurations.​allowQueueTransferOnAgentUnavailabilityboolean

Allow agents to transfer messages back to queue when no agents are available.

Default false
chatConfigurations.​orchestrationobjectrequired
chatConfigurations.​orchestration.​idstring= 36 characters

UUID generated for orchestration object, which will be used for orchestration of conversations for this account

Example: "c987d07a-d59c-11ea-87d0-0242ac13000d"
chatConfigurations.​entryPointobject(EntryPoint)required
chatConfigurations.​entryPoint.​idstring[ 1 .. 255 ] charactersrequired

Unique id of entrypoint in client application

attributesArray of objects(Attribute)[ 1 .. 10 ] items
Response
application/json
{
  "id": "ae103957-9c82-4fa8-a34e-925be85e06ec",
  "created": "2021-03-21T14:29:01.516Z",
  "modified": "2021-03-28T14:29:01.516Z",
  "name": "order_account",
  "address": "123456789",
  "channel": {
    "id": "45a095f4-d0ee-4220-a689-22b541c58f67"
  },
  "chatConfigurations": {
    "timeout": 30,
    "defaultLanguage": "en-US",
    "onAgentUnavailability": "off_hours",
    "orchestration": { … },
    "entryPoint": { … }
  }
}

Update account

Request

Overview

This APIs allows you to update an existing Conversation Manager account.

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 account

namestring[ 1 .. 255 ] charactersrequired

Unique name for account

descriptionstring[ 1 .. 1023 ] characters
activeboolean
Default true
addressstring[ 1 .. 255 ] charactersrequired

Account ID like email address, phone numbers.

channelobjectrequired
channel.​idstring= 36 characters

UUID generated for account

Example: "c987d07a-d59c-11ea-87d0-0242ac130200"
caseManagementobject(CaseManagement)
chatConfigurationsobject(ChatConfigurations)required
chatConfigurations.​timeoutnumber[ 3 .. 10080 ]

Timeout for conversation created for this account. Time is calculated from last message in conversation. Client applications should start new conversation after timeout.

Default 240
chatConfigurations.​defaultLanguagestring

Default language

Default "en-US"
Example: "en-US"
chatConfigurations.​onAgentUnavailabilitystring

This attribute indicates action on agent unavailability, in case of 'off_hours' if agent is not available then 'off hours' message is sent back. In case of 'retain_and_retry' message is held on Conversation Hub until agent is online

Default "off_hours"
Enum"off_hours""retain_and_retry"
Example: "off_hours"
chatConfigurations.​allowLogoutWithOpenChatsboolean

Allow agents to logout with open messages in their inbox.

Default false
chatConfigurations.​allowQueueTransferOnAgentUnavailabilityboolean

Allow agents to transfer messages back to queue when no agents are available.

Default false
chatConfigurations.​orchestrationobjectrequired
chatConfigurations.​orchestration.​idstring= 36 characters

UUID generated for orchestration object, which will be used for orchestration of conversations for this account

Example: "c987d07a-d59c-11ea-87d0-0242ac13000d"
chatConfigurations.​entryPointobject(EntryPoint)required
chatConfigurations.​entryPoint.​idstring[ 1 .. 255 ] charactersrequired

Unique id of entrypoint in client application

attributesArray of objects(Attribute)[ 1 .. 10 ] items
modifiedstring(date-time)

Last modified time in GMT

curl -i -X PUT \
  https://api.egain.cloud/conversation/conversationmgr/v3/accounts/7b6c5fff-036e-4a40-b68a-a67c592fc079 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "order_account",
    "address": "123456789",
    "modified": "2021-03-28T14:29:01.516Z",
    "channel": {
      "id": "45a095f4-d0ee-4220-a689-22b541c58f67"
    },
    "chatConfigurations": {
      "timeout": 30,
      "defaultLanguage": "en-US",
      "onAgentUnavailability": "off_hours",
      "orchestration": {
        "id": "c37e975f-6b2f-490f-9cac-dfa05499f744"
      },
      "entryPoint": {
        "id": "1001"
      }
    }
  }'

Responses

No Content

Response
No content

Delete account

Request

Overview

Use this API to delete a Conversation Manager account.

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

Responses

No Content

Response
No content

Conversation

Use this API to send messages through the Conversation Manager.

Operations

Assets

Use this API to upload/download Assets like attachments.

Operations