CTI Broker REST API

Endpoints

The following tables describe how the CTI Broker interface can be utilized. There are two endpoints: 1)

to fire commands to the Anywhere365 UCCUCC stands for Unified Contact Center and consists of a queue that can be handled by Agents Each Contact Center has its own settings, interactive voice response questions and Agent with specific skills. Agents can be member of, or sign up to, one or more Contact Centers. (e.g. sign-in/sign-out an Agent or call a phone number)

and 2) to subscribe/unsubscribe a callbackWith CallBack the customer can leave his / her number to be called back by an available agent during business hours. URL in order to receive events from Anywhere365. These

events are posted as JSON messages to the callback URL.

Fire Commands

Item

Description

URL

/api/command

Method

POST

Payload

{

ImAddress : [string],

commandType : [enum],

number : [string]

}

Parameters

• ImAddress – the sipThe Session Initiation Protocol (SIP) is a protocol to make multimedia communication (audio, video and other data communication) possible and it is also used for Voice over IP (VoIP). SIP has similarities with other Internet protocols such as HTTP and SMTP. address of the agent

Example: sip:agentname@domain.com

  • commandType – Enum of commands

    • 0 = AgentLogin

    • 1 = AgentLogout

    • 4 = Dial

    • 14 = HeartBeat

  • Number – used for command “dial” and is optional for other

    commands. This is the customer number which will be dialed.

    Example: tel:+31880000000

Sample

{

'ImAddress' : 'sip:agentname@domain.com',

'commandType' : 'AgentLogin',

'number' :

}

Success response

202 – No Content

Error response

500 – Internal Server Error

Notes

When sending the command ‘Dial’ the ‘number’ parameter must be in the

e.164 format:

tel:+<countryCode><nationalDestinationCode><subscriberNumber>

E.g. tel:+31880000000

 

Subscribe for Events

Item

Description

URL

/api/subscribe

Method

POST

Payload

{

'CallbackUrl' : [string]

'ImAddress' : [string]

}

Parameters

  • CallbackUrl – The URL which will be called to POST the events of the CTI broker

  • ImAddress – the sip address of the Agent for which events should be received on the supplied callback URL. Example: sip:agentname@domain.com

Sample

{

'CallbackUrl' : 'http://example.com/api/events'

'ImAddress’ : 'sip:agentname@domain.com'

}

Success response

Code : 201 created

Location: api/subscribe/:id

Error response

500 – Internal Server Error

Notes

The callback URL must support a POST method with the following

payload:

{

SubscriptionId : [guidGUID stands for Globally Unique Identifier and is a pseudo random number used in software applications that is assumed to be unique. The total number of unique keys (2<sup>128</sup> of 3.4028×10<sup>38</sup>) is very large and the probability of the creating the same GUID twice is very small, though not 100% guaranteed.],

SessionType : [enum],

ImAddress : [string],

eventType : [enum],

callId : [guid],

ani : [string]

}

  • SubscriptionId

    The id of the subscription (returned when the callback URL was subscribed) •

  • SessionType

    • 0 = Inbound

    • 1 = Outbound

  • ImAddress

    The sip address of the agent

  • eventType

    • 0 = LoggedIn

    • 1 = LoggedOff

    • 3 = Hunting

    • 4 = Connected

    • 5 = Disconnected

    • 6 = OnHold

    • 7 = Retrieve

  • callId

    The id of the conversation

  • ani

    The caller’s number

Note loginEvent

If the eventType is LoggedIn and the login is success, the callId is empty.

If the login failed, the callId contains “failed”

 

Unsubscribe for Events

Item

Description

URL

/api/subscribe/:id

Method

DELETE

Parameters

  • id – The id of the subscription

Sample

/api/subscribe/296854af-2ba7-45d0-b460-085dc1843b3d

Success response

202 – No Content

Error response

404 – Not found

500 – Internal Server Error

 

Events

When a callback URL is subscribed events will be posted to this URL as JSON messages. Currently the

following events are supported:

  • Hunting

    This event informs the CTI service the agent is currently invited for the call session

  • Connected

    This event informs the CTI service the agent accepted the call

  • Disconnected

    This event informs the CTI service the agent disconnected the call

  • OnHold

    This event informs the CTI service the agent put the customer on-hold

  • Retrieve

    This event informs the CTI service the agent resumed the call (after it was put on-hold)

 

Payload

The callback URL must support a POST method with the following payload:

{

SubscriptionId : [guid],

SessionType : [enum],

ImAddress : [string],

eventType : [enum],

callId : [guid],

ani : [string]

}

 

Parameters

  • SubscriptionId

    The id of the subscription (returned when the callback URL was subscribed)

  • SessionType

    • 0 = Inbound

    • 1 = Outbound

  • ImAddress

    The sip address of the agent

  • eventType

    • 0 = LoggedIn

    • 1 = LoggedOff

    • 3 = Hunting

    • 4 = Connected

    • 5 = Disconnected

    • 6 = OnHold

    • 7 = Retrieve

  • callId

    The id of the conversation

  • ani

    The caller’s phone number

 

Additional note

When an event is received indicating that Agent X is connected for CallId Y and this Agent initiates a transfer, an OnHold event will be received for this Agent / Call combination. Next a Retrieve event will be received, this event can have two Agent / Call combinations:

  1. The Agent for the Retrieve event is the same as the Agent for the OnHold event; in this case the transfer failed and the Agent took back the call

  2. The Agent for the Retrieve event is different from the Agent for the OnHold event; in this case the transfer was successful.

    This implies two things:

    1. The Agent that initiated the transfer (i.e. for which the OnHold event was received) is now disconnected.

    2. The Agent that accepted the transfer (i.e. for which the Retrieve event was received) is now connected.