Rest API

General form

http://localhost:$xucport/xuc/api/1.0/$method/$domain/$username/

withHeaders((“Content-Type”, “application/json”))

  • $xucport : Xuc port number (default 8090)
  • $method : See available methods below
  • $domain : Represents a connection site, can be anything
  • $username : XiVO client user username

Events

Xuc post JSON formated events on URL eventUrl = "http://localhost:8090/xivo/1.0/event/avencall.com/dropbox/" configured in /usr/share/xuc/application.conf

Phone Event Notification

Related to a username, phone event is in message payload same structure as javascript Phone Events

{
  "username":"alicej",
  "message":{
     "msgType":"PhoneEvent",
     "ctiMessage":{"eventType":"EventDialing","DN":"1058","otherDN":"3000","linkedId":"1447670380.34","uniqueId":"1447670380.34","userData":{"XIVO_USERID":"9"}}}}

Obtain authentication token

::
curl -XPOST -d ‘{“login”: “<login>”, “password”: “<password>”}’ -H “Content-Type: application/json” http://localhost:8090/xuc/api/2.0/auth/login

Will retrieve an object

::
{login: “<login>”, token: “<token>”}

or an error

::
{error:”<error_code>”, message:”<error_message>”}

where error_code is one of:

  • UserNotFound
  • InvalidPassword
  • InvalidJson
  • UnhandledError

This token can then be used with the CTI Authentication and Check authentication token.

Obtain authentication token (SSO/Kerberos)

::
curl -XGET http://localhost:8090/xuc/api/2.0/auth/sso

Will retrieve an object

::
{login: “<login>”, token: “<token>”}

or an error

::
{error:”<error_code>”, message:”<error_message>”}

where error_code is one of:

  • UserNotFound
  • SsoAuthenticationFailed
  • UnhandledError

This token can then be used with the CTI Authentication and Check authentication token.

Check authentication token

You can check the validity of a token using the following web service with an Authorization header set to ‘Bearer <token>’

curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbiI6InZtYWNoaW4iLCJleHBpcmVzIjoxNDg5OTk4Mzg2fQ.R6bzc5fBRs74l7ZBdLVjSIbNx3j3e07mV6mAX4_sklI" "http://localhost:8090/xuc/api/2.0/auth/check"

Will retrieve an object with a refreshed token

::
{login: “<login>”, token: “<token>”}

or an error

::
{error:”<error_code>”, message:”<error_message>”}

where error_code is one of:

  • InvalidToken
  • InvalidJson
  • BearerNotFound
  • AuthorizationHeaderNotFound
  • TokenExpired
  • UnhandledError

Connection

{"password" : "password"}

 curl -XPOST -d '{"password":"<password>"}' -H "Content-Type: application/json"  http://localhost:8090/xuc/api/1.0/connect/avencall.com/<username>/

DND

{"state" : [false|true]}


curl -XPOST -d '{"state":false}' -H "Content-Type: application/json"  http://localhost:8090/xuc/api/1.0/dnd/avencall.com/<username>/

Dial

{"number" : "1101"}

curl -XPOST -d '{"number":"<number>"}' -H "Content-Type: application/json"  http://localhost:8090/xuc/api/1.0/dial/avencall.com/<username>/

DialByUsername

{"username" : "john"}

curl -XPOST -d ‘{“username”:”<username>”}’ -H “Content-Type: application/json” http://localhost:8090/xuc/api/1.0/dialByUsername/avencall.com/<username>/

DialFromQueue

{"destination":"1002","queueId":5,"callerIdName":"Thomas","callerIdNumber":"999999","variables":{"foo":"bar"}}

curl -XPOST -d '{"destination":"1002","queueId":5,"callerIdName":"Thomas","callerIdNumber":"999999","variables":{"foo":"bar"}}' -H "Content-Type: application/json"  http://localhost:8090/xuc/api/1.0/dialFromQueue/avencall.com/<username>/

Limitations: Queue No Answer settings does not work - see No Answer. Except: when there is no free Agent to queue (none attached, all Agents on pause or busy), then No answer settings work (but Fail does not).

Note

Line should be configured with enabled “Ring instead of On-Hold Music” enabled (on “Application: tab in queue configuration - see Queues). Otherwise the queue will answers the call and the destination rings even if there are no agents available.

Phone number sanitization

Dial command automatically applies filters to the phone number provided to make it valid for Xivo. Especially, it removes invalid characters and handles properly different notations of international country code.

Some countries don’t follow the international standard and actually keep the leading zero after the country code (e.g. Italy). Because of this, if the zero isn’t surrounded by parenthesis, the filter keeps it [1].

[1]See Redmine ticket #150

Forward

All forward commands use the above payload

{"state" : [true|false],
  "destination" : "1102")

Unconditionnal

curl -XPOST -d '{"state":true,"destination":"<destnb>"}' -H "Content-Type: application/json"  http://localhost:8090/xuc/api/1.0/uncForward/avencall.com/<username>/

On No Answer

curl -XPOST -d '{"state":true,"destination":"<destnb>"}' -H "Content-Type: application/json"  http://localhost:8090/xuc/api/1.0/naForward/avencall.com/<username>/

On Busy

curl -XPOST -d '{"state":true,"destination":"<destnb>"}' -H "Content-Type: application/json"  http://localhost:8090/xuc/api/1.0/busyForward/avencall.com/<username>/

Handshake

Will repost all events on the configured URL

AgentLogout

Logout un agent

curl -XPOST -d '{"phoneNumber":"<phoneNumber>"}' -H "Content-Type: application/json"  http://localhost:8090/xuc/api/1.0/agentLogout/

TogglePause

Change state of an agent, pause if ready, ready if on pause

curl -XPOST -d '{"phoneNumber":"<phoneNumber>"}' -H "Content-Type: application/json"  http://localhost:8090/xuc/api/1.0/togglePause/