How to use the Chat Session REST API

Note Enterprise license and higher

Using the Swagger spec to generate a client

The REST API is using a swagger specification to define the REST interface. A client for every programming language can be generated with the Swagger.IO editor.

The Swagger spec can be found on http://ip-address-of-ucc-server:configured-port/ucc-name/swagger. For example http://localhost:8118/ucc_name/swagger.

 

Callback URL

In order to receive events from the API you need to specify a callbackThe CallBack feature enables the customer to leave his / her number to be called back by an available agent during business hours. URL. You can specify a callback url in the create session action of the API. The following events will be published to your callback URL once they occur. All events are HTTP POST requests with json data in the request body.

SessionStateChanged

{

"EventType": "SessionStateChanged",

"PreviousState": "<PREVIOUS_STATE>",

"CurrentState": "<CURRENT_STATE>",

"SessionId": "<SESSION_ID>"

}

This event is raised when any state change occurs on the session SessionId. The following list contains the states with their description.

  • Idle

    The Session is now known in the API, but not yet enqueued in the UCC

  • Queued

    The Session is now queued in the UCC (skill needs still to be set)

  • Hunting

    The UCC is hunting an agent for the skill you have set (try to connect with an agent)

  • Connected

    The Session is now connected with an agent. Not applicable when using forward skills to other UCC endpoints.

  • Disconnected

    The Session is no longer connected with an agent

  • Closed

    The Session is finished and removed from the UCC

Valid state transitions are:

  • Idle -> Queued

  • Queued -> Hunting

  • Queued -> Closed

  • Hunting -> Connected

  • Hunting -> Closed

  • Connected -> Disconnected

  • Disconnected -> Closed

 

QueuePositionChanged

{

"EventType": "QueuePositionChanged",

"Real": <REAL>,

"PreviousReal": <PREVIOUS_REAL>,

"Best": <BEST>,

"PreviousBest": <PREVIOUS_BEST>,

5

"SessionId": "<SESSION_ID>"

}

This event is raised when the session's position in the queue is changed, starting from 2147483647 (integers max value). Explanation of fields can be found below:

  • Real

    The current queue position of the session

  • Best

    The best queue position the session ever had. (eg. when position is 5, but another session is added with priority flag, the real position becomes 6 and the best position stays 5. You should communicate this value to the user.)

  • PreviousReal

    The previous value of real. Starts at 2147483647 in first QueuePositionChanged event.

  • PreviousBest

    The previous value of best. Starts at 2147483647 in first QueuePositionChanged event

 

MessageReceived

{

"EventType": "MessageReceived",

"Text": "<MESSAGE_TEXT>",

"Index": <INDEX_NO>,

"SessionId": "<SESSION_ID>"

}

This event is raised when the agent sent a message. Explanation of fields can be found below:

  • Text

    The message text as a string value

  • Index

    The sequence number of the message (starts at 0) (int)

 

AgentComposingStateChanged

{

"EventType": "AgentComposingStateChanged",

"IsComposing": <COMPOSING_STATE>,

"SessionId": "4a3c8b11-cddf-469b-a65c-3d51f10993af"

}

This event is raised when the agent's composing state (is typing indicator) changes. Explanation of fields can be found below:

  • IsComposing

    boolean indicating wheter the agent is typing or not.

 

Example

The following HTTP log shows the typical usage of the rest api.

 

Create a chat session

To create a chat session, a customer sip uri and customer display name are required. The Customer Sip URI is used for impersonating Skype for Business contacts. This Sip URI will show up in Anywhere365 reporting. The customer display name is the name of the customer.

Request

POST http://hostname:port/ucc_name/chatsession HTTP/1.1

Accept: application/json

Content-Type: application/json

Authorization: <token>

Host: hostname:port

Content-Length: 133

{

"CustomerSipUri": "sip:user@domain.com",

"CustomerDisplayName": "User Name",

"CallbackUrl": http://localhost/callback

}

 

Response

HTTP/1.1 200 OK

Content-Length: 118

Content-Type: application/json; charset=utf-8

Server: Microsoft-HTTPAPI/2.0

Date: Mon, 22 Jul 2019 11:18:58 GMT

{

"Id":"4d372533-cb61-4fe8-b6a5-f5b1845e039e",

"CustomerSipUri":"sip:user@domain.com",

"CustomerDisplayName":"user"

}

 

Change the skill

Note We took the Id from the response and put it in the URL

Response codes in range 200 - 299 are success codes. You need to wait for the Connected state after performing this action.

Skills that are sent within this request, must be setup as ChatSkill in the SharePoint settings site of the UCC.

 

Request

POST http://hostname:port/ucc_name/chatsession/4d372533-cb61-4fe8-b6a5-f5b1845e039e/changeskill HTTP/1.1

Accept: application/json

Content-Type: application/json

Authorization: <token>

Host: app16:8118

Content-Length: 39

{

"SkillName": "InstantMessaging"

}

 

Response

HTTP/1.1 204 No Content

Content-Length: 0

Server: Microsoft-HTTPAPI/2.0

Date: Mon, 22 Jul 2019 12:07:25 GMT

 

Send composing state

Request

POST http://hostname:port/ucc_name/chatsession/4d372533-cb61-4fe8-b6a5-f5b1845e039e/composing HTTP/1.1

Accept: application/json

Content-Type: application/json

Authorization: <token>

Host: hostname:port

Content-Length: 27

{

"IsComposing": true

}

 

Response

HTTP/1.1 204 No Content

Content-Length: 0

Server: Microsoft-HTTPAPI/2.0

Date: Mon, 22 Jul 2019 12:33:59 GMT

 

Send message

Request

POST http://hostname:port/ucc_name/chatsession/4d372533-cb61-4fe8-b6a5-f5b1845e039e/message HTTP/1.1

Accept: application/json

Content-Type: application/json

Authorization: <token>

Host: hostname:port

Content-Length: 32

{

"Message": "Hello world"

}

 

Response

HTTP/1.1 204 No Content

Content-Length: 0

Server: Microsoft-HTTPAPI/2.0

Date: Mon, 22 Jul 2019 12:36:16 GMT

 

End conversation

Request

DELETE http://hostname:port/ucc_name/chatsession/4d372533-cb61-4fe8-b6a5-f5b1845e039e HTTP/1.1

Accept: application/json

Content-Type: application/json

Authorization: <token>

Host: hostname:port

Content-Length: 0

 

Response

HTTP/1.1 204 No Content

Content-Length: 0

Server: Microsoft-HTTPAPI/2.0

Date: Mon, 22 Jul 2019 12:37:53 GMT