Skip to content
Conversation APIs
/
/
/
Get Authentication

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

Create Authentication

Request

Overview

Use this API to register client callback Authentication methods using oAuth or Basic Authentication. This is the first step in creating a new Conversation Account. New Account API process flow: Authenticiation > Client Application > Participant > Channel > Orchestration > Account Use the ID returned in the response when creating the client application. The Conversation Manager also uses this authentication method when sending messages to the callback URL of the client application.

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 authentication type

One of:

OAuth type authentication for callback APIs specified in Client application. Conversation Hub will generate token using this API and use it until it receives 401 from callback API

namestring[ 1 .. 255 ] charactersrequired

Unique name for authentication method

descriptionstring[ 1 .. 1023 ] characters
activeboolean
Default true
typestringrequired

Type of authentication

Value"oauth2"
Example: "oauth2"
oauth2objectrequired
oauth2.​tokenRequestUrlstring[ 1 .. 255 ] charactersrequired

Access token API

oauth2.​methodstringrequired

Http method for access token API

Enum"POST""GET"
oauth2.​headersArray of objects(Attribute)[ 1 .. 25 ] itemsrequired
oauth2.​headers[].​namestring[ 1 .. 255 ] charactersrequired

name of attribute

oauth2.​headers[].​valuestring[ 1 .. 1023 ] charactersrequired

value of attribute

oauth2.​payloadstring[ 1 .. 1024 ] charactersrequired

Access token request payload

oauth2.​accessTokenPathstring[ 1 .. 1024 ] charactersrequired

The JSON query path of an access token in the returned JSON response

Example: "$.accessToken"
curl -i -X POST \
  https://api.egain.cloud/conversation/conversationmgr/v3/authentications \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "custom_bot_callback_authentication",
    "type": "oauth2",
    "oauth2": {
      "tokenRequestUrl": "https://example.com/accesstoken",
      "method": "POST",
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        }
      ],
      "payload": "{ \"clientId\": \"74513d54e112464ea8e69d3d639d0c94\",\"clientSecret\": \"nv1GRtTAL1OcKdqKZrQBb5AqQNilgaitr@JYtsdYZvLbCHx8dRjZeCPENmo8\"}",
      "accessTokenPath": "$.accessToken"
    }
  }'

Responses

Created

Bodyapplication/json
idstring= 36 characters

UUID generated for the object.

Response
application/json
{
  "id": "34fbb53f-ed7f-48d4-b545-e26cc95e075d"
}

Get Authentications

Request

Overview

Use this API to Get details of all authentication types in the Conversation Manager.

Scope

Client application must have 'app.conversation.conversationmgr.manage' assigned to call this API

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

Responses

OK

Bodyapplication/json
paginationInfoobject(PaginationInfo)
authenticationArray of Oauth2Authentication (object) or BasicAuthentication (object)(GetAuthenticationData)
Example: [{"id":"34fbb53f-ed7f-48d4-b545-e26cc95e075d","name":"custom_bot_callback_authentication","type":"oauth2","oauth2":{"tokenRequestUrl":"https://acme.support.com/clientapp/accesstoken","method":"POST","headers":[{"name":"Content-Type","value":"application/json"},{"name":"Accept","value":"application/json"}],"payload":"{ \"clientId\": \"c987cbfc-d59c-11ea-87d0-0242ac130003\",\"clientSecret\": \"c987cde6-d59c-11ea-87d0-0242ac130003\",\"refreshToken\": \"c987cee0-d59c-11ea-87d0-0242ac130003\"}","accessTokenPath":"$.accessToken"},"created":"2021-03-28T14:29:01.516Z","modified":"2021-03-28T14:29:01.516Z"},{"id":"b92fe726-da13-4821-b236-62ade0c1f7fa","name":"custom_bot_callback_authentication_2","type":"basic","basicAuth":{"username":"string","password":"string"},"created":"2021-03-31T03:54:07.620Z","modified":"2021-03-28T14:29:01.516Z"}]
Response
application/json
{
  "authentication": [
    { … },
    { … }
  ]
}

Get Authentication

Request

Overview

Use this API to get details of existing Authentication types 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/authentications/7b6c5fff-036e-4a40-b68a-a67c592fc079 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
One of:

OAuth type authentication for callback APIs specified in Client application. Conversation Hub will generate token using this API and use it until it receives 401 from callback API

namestring[ 1 .. 255 ] charactersrequired

Unique name for authentication method

descriptionstring[ 1 .. 1023 ] characters
activeboolean
Default true
typestringrequired

Type of authentication

Value"oauth2"
Example: "oauth2"
oauth2objectrequired
oauth2.​tokenRequestUrlstring[ 1 .. 255 ] charactersrequired

Access token API

oauth2.​methodstringrequired

Http method for access token API

Enum"POST""GET"
oauth2.​headersArray of objects(Attribute)[ 1 .. 25 ] itemsrequired
oauth2.​headers[].​namestring[ 1 .. 255 ] charactersrequired

name of attribute

oauth2.​headers[].​valuestring[ 1 .. 1023 ] charactersrequired

value of attribute

oauth2.​payloadstring[ 1 .. 1024 ] charactersrequired

Access token request payload

oauth2.​accessTokenPathstring[ 1 .. 1024 ] charactersrequired

The JSON query path of an access token in the returned JSON response

Example: "$.accessToken"
idstring= 36 characters
createdstring(date-time)

Last modified time in GMT

modifiedstring(date-time)

Last modified time in GMT

Response
application/json
{
  "id": "34fbb53f-ed7f-48d4-b545-e26cc95e075d",
  "name": "custom_bot_callback_authentication",
  "type": "oauth2",
  "oauth2": {
    "tokenRequestUrl": "https://acme.support.com/clientapp/accesstoken",
    "method": "POST",
    "headers": [ … ],
    "payload": "{ \"clientId\": \"c987cbfc-d59c-11ea-87d0-0242ac130003\",\"clientSecret\": \"c987cde6-d59c-11ea-87d0-0242ac130003\",\"refreshToken\": \"c987cee0-d59c-11ea-87d0-0242ac130003\"}",
    "accessTokenPath": "$.accessToken"
  },
  "created": "2021-03-28T14:29:01.516Z",
  "modified": "2021-03-28T14:29:01.516Z"
}

Update Authentication

Request

Overview

Use this API to update an existing authentication type.

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 authentication type

One of:

OAuth type authentication for callback APIs specified in Client application. Conversation Hub will generate token using this API and use it until it receives 401 from callback API

namestring[ 1 .. 255 ] charactersrequired

Unique name for authentication method

descriptionstring[ 1 .. 1023 ] characters
activeboolean
Default true
typestringrequired

Type of authentication

Value"oauth2"
Example: "oauth2"
oauth2objectrequired
oauth2.​tokenRequestUrlstring[ 1 .. 255 ] charactersrequired

Access token API

oauth2.​methodstringrequired

Http method for access token API

Enum"POST""GET"
oauth2.​headersArray of objects(Attribute)[ 1 .. 25 ] itemsrequired
oauth2.​headers[].​namestring[ 1 .. 255 ] charactersrequired

name of attribute

oauth2.​headers[].​valuestring[ 1 .. 1023 ] charactersrequired

value of attribute

oauth2.​payloadstring[ 1 .. 1024 ] charactersrequired

Access token request payload

oauth2.​accessTokenPathstring[ 1 .. 1024 ] charactersrequired

The JSON query path of an access token in the returned JSON response

Example: "$.accessToken"
modifiedstring(date-time)

Last modified time in GMT

curl -i -X PUT \
  https://api.egain.cloud/conversation/conversationmgr/v3/authentications/7b6c5fff-036e-4a40-b68a-a67c592fc079 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "custom_bot_callback_authentication",
    "type": "oauth2",
    "oauth2": {
      "tokenRequestUrl": "https://acme.support.com/clientapp/accesstoken",
      "method": "POST",
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Accept",
          "value": "application/json"
        }
      ],
      "payload": "{ \"clientId\": \"c987cbfc-d59c-11ea-87d0-0242ac130003\",\"clientSecret\": \"c987cde6-d59c-11ea-87d0-0242ac130003\",\"refreshToken\": \"c987cee0-d59c-11ea-87d0-0242ac130003\"}",
      "accessTokenPath": "$.accessToken"
    },
    "modified": "2021-03-28T14:29:01.516Z"
  }'

Responses

No Content

Response
No content

Delete Authentication

Request

Overview

Use this API to delete an existing authentication method. An authentication method 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/authentications/7b6c5fff-036e-4a40-b68a-a67c592fc079 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

No Content

Response
No content

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

Conversation

Use this API to send messages through the Conversation Manager.

Operations

Assets

Use this API to upload/download Assets like attachments.

Operations