Rest API

The REST API allows you to control XiVO from a remote application. It can be accessed through HTTP requests using the following base URL: http://localhost:${XUC_PORT}/xuc/api/2.0 where the default XUC port number is 8090.

Type of users

Two types of users can request the API: CTI users and web service users.

CTI users

CTI users are XiVO users which are usually associated with a line (either plastic phone or WebRTC). They have have limited rights to the API, they can only request specific endpoints.

Web service users

Web service users are technical users. They are not associated with any line. They have specific and custom rights to use the API.

Permissions and ACLs

ACLs handle user permissions. CTI users all have the same permissions, they all are contained into the alias alias.ctiuser. They only can request some endpoints of the API.

However, web service user may have specific and custom permissions to request the API. A web service user can have access to specific endpoints, or to specific methods.

See REST API Permissions for more information.

ACLs of CTI users

All CTI users share the same permissions. The alias alias.ctiuser contains the following permissions:

["xuc.rest.contact.personal.read",
"xuc.rest.contact.personal.create",
"xuc.rest.contact.personal.delete",
"xuc.rest.contact.personal.*.read",
"xuc.rest.contact.personal.*.update",
"xuc.rest.contact.personal.*.delete",
"xuc.rest.contact.export.personal.read",
"xuc.rest.contact.import.personal.create",
"xuc.rest.contact.display.personal.read",
"xuc.rest.call_qualification.queue.*.read",
"xuc.rest.call_qualification.csv.#.read",
"xuc.rest.call_qualification.create",
"xuc.rest.mobile.push.register.create",
"xuc.rest.config.meetingrooms.static.token.*.read",
"xuc.rest.config.meetingrooms.personal.token.*.read",
"xuc.rest.config.meetingrooms.temporary.token.*.read",
"xuc.rest.config.meetingrooms.personal.*.read",
"xuc.rest.config.meetingrooms.personal.create",
"xuc.rest.config.meetingrooms.personal.update",
"xuc.rest.config.meetingrooms.personal.*.delete",
"xuc.rest.config.#.read",
"xuc.rest.config.#.create",
"xuc.rest.config.#.update"]

User basic authentication

Only authenticated users can use the API. The authentication process provides a JWT token that must be used in all subsequent requests.

CTI user authentication

Request

Method

POST

URI

/auth/login

Header

Content-Type: application/json

Body parameters

Field

Type

Description

login

string

CTI user login

password

string

CTI user password

Curl example
curl -X POST http://localhost:8090/xuc/api/2.0/auth/login \
-d '{"login": "cti_user_login", "password": "cti_user_password"}' \
-H "Content-Type: application/json"

Response

{
   login: "$CTI_USER_LOGIN",
   token: "$CTI_USER_JWT_TOKEN",
   TTL: $CTI_USER_TTL
}
Model

Field

Type

Description

login

string

CTI user login

token

string

CTI user JWT token

TTL

integer

Time to live of the token in seconds

Error messages

Error code

HTTP header code

Possible cause

InvalidCredentials

401

Invalid login and/or invalid password

InvalidJson

400

The request body does not follow the body model

NotHandledError

500

Error not covered in current implementation

Web service user authentication

Request

Method

POST

URI

/auth/webservice

Header

Content-Type: application/json

Body parameters

Field

Type

Description

login

string

Web service user login

password

string

Web service user password

Curl example
curl -X POST http://localhost:8090/xuc/api/2.0/auth/webservice \
-d '{"login": "web_service_user_login", "password": "web_service_user_password"}' \
-H "Content-Type: application/json"

Response

{
   login: "$WEB_SERVICE_USER_LOGIN",
   token: "$WEB_SERVICE_USER_JWT_TOKEN",
   TTL: $WEB_SERVICE_USER_TTL
}
Model

Field

Type

Description

login

string

Web service user login

token

string

Web service user JWT token

TTL

integer

Time to live of the token in seconds

Error messages

Error code

HTTP header code

Possible cause

InvalidCredentials

401

Invalid login and/or invalid password

InvalidJson

400

The request body does not follow the body model

NotHandledError

500

Error not covered in current implementation

JWT token

The JWT token is necessary to use the API the other endpoints of the API. It must be provided in the Authorization header of all subsequent requests.

The contents of the token changes from Kuma. It now contains the following informations: - login: the login of the user - expiresAt: the date at which the token expires (in milliseconds since the epoch) - issuedAt: the date at which the token was issued (in milliseconds since the epoch) - userType: the type of the user (cti or webservice) - acls: the permissions of the user (see REST API Permissions)

As a consequence, any token generated before Kuma will not work anymore and users need to re-login.

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

Single sign-in (SSO authentication)

Note

Only CTI users can be authenticated using SSO.

Authentication with Kerberos

Request

Method

GET

URI

/auth/sso

Curl example
curl -X GET http://localhost:8090/xuc/api/2.0/auth/sso

Response

{
   login: "$CTI_USER_LOGIN",
   token: "$CTI_USER_JWT_TOKEN",
}
Model

Field

Type

Description

login

string

CTI user login

token

string

CTI user JWT token

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

Error messages

Error code

HTTP header code

Possible cause

UserNotFound

401

The user does not exist

SsoAuthenticationFailed

401

The user could not be authenticated using Kerberos

NotHandledError

500

Error not covered in current implementation

Error messages

Error code

HTTP header code

Possible cause

UserNotFound

401

The user does not exist

SsoAuthenticationFailed

401

The user could not be authenticated using Kerberos

NotHandledError

500

Error not covered in current implementation

Authentication with CAS

Request

Method

GET

URI

/auth/cas

URL parameters

Field

Type

Description

service

string

The URL of the CAS server

service | string | The URL of the CAS server |
Curl example
curl -X GET http://localhost:8090/xuc/api/2.0/auth/cas?service=https://cas.myplatform.com&ticket=ST-11-Qsicgrh1mZ3dgoeOx7m6-af27d9025e0c

Response

{
   login: "$CTI_USER_LOGIN",
   token: "$CTI_USER_JWT_TOKEN",
}
Model

Field

Type

Description

login

string

CTI user login

token

string

CTI user JWT token

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

Error messages

Error code

HTTP header code

Possible cause

UserNotFound

401

The user does not exist

CasServerUrlNotSet

403

XiVOCC containers are not configured (see CAS SSO Authentication)

CasServerInvalidResponse

403

The CAS server returned an invalid response

CasServerInvalidParameter

403

The Parameters sent to the CAS Server are invalid

CasServerInvalidRequest

403

The Request to the CAS server is invalid

CasServerInvalidTicketSpec

403

The ticket specification is invalid

CasServerUnauthorizedServiceProxy

403

The CAS service proxy is not authorized

CasServerInvalidProxyCallback

403

The CAS service proxy callback is invalid

CasServerInvalidTicket

403

The ticket is invalid (probably expired or defined for another service)

CasServerInvalidService

403

The service is invalid

CasServerInternalError

403

CAS Server internal error

NotHandledError

500

Error not covered in current implementation

Authentication with OpenID Connect (OIDC)

Request

Method

GET

URI

/auth/oidc

Note

The token can also be provided in the Authorization header using the Bearer scheme.

URL parameters

Field

Type

Description

token

string

CTI user JWT token

Curl example
curl -X GET http://localhost:8090/xuc/api/2.0/auth/oidc?token=${OAUTH_TOKEN}

Response

{
   login: "$WEBSERVICE_USER_LOGIN",
   token: "$WEBSERVICE_USER_JWT_TOKEN",
   TTL: $WEBSERVICE_USER_TTL
}
Model

Field

Type

Description

login

string

CTI user login

token

string

CTI user JWT token

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

Error messages

Error code

HTTP header code

Possible cause

UserNotFound

401

The user does not exist

OidcNotEnabled

403

OpenID connect authentication is not enabled (see OpenID Connect SSO Authentication)

OidcInvalidParameter

403

Missing access_token

OidcAuthenticationFailed

403

The access_token forwarded to XUC is invalid

NotHandledError

500

Error not covered in current implementation

Check and renew JWT token

Any user, either CTI or Web service, can check and renew their JWT token.

Request

Method

GET

URI

/auth/check

Header

Authorization: Bearer ${JWT_TOKEN}

Curl example
curl -X GET http://localhost:8090/xuc/api/2.0/auth/check \
-H "Authorization: Bearer user_jwt_token"

Response

{
   login: "$USER_LOGIN",
   token: "$USER_JWT_TOKEN",
   TTL: $USER_TTL
}
Model

Field

Type

Description

login

string

CTI user login

token

string

CTI user JWT token

TTL

integer

Time to live of the token in seconds

Error messages

Error code

HTTP header code

Possible cause

InvalidToken

403

Token does not match XUC signature tokens

InvalidJson

400

The request body is not a valid JSON or does not follow the body model

BearerNotFound

400

The token is not found in the Authorization header

AuthorizationHeaderNotFound

400

The Authorization header is not found in the request

TokenExpired

403

The Authorization header is not found in the request

NotHandledError

500

Error not covered in current implementation

Personal contacts

CTI users can use the endpoints related to personal contacts.

Error management

If an error occurs while using API actions, error will always be raised with proper HTTP return code and will be wrapped in JSON object with following format

{
   "error": ${ERROR_CODE}
   "message": ${ERROR_MESSAGE}
}

Error codes

Error code

HTTP header code

Possible cause

InvalidContact

400

Personal contact has bad format

ContactNotFound

404

Personal contact does not exist

DuplicateContact

409

Personal contact already exists

Unreachable

503

Directory server is not reachable

JsonParsingError

500

Personal Contact sent to API is not JSON valid

NotHandledError

500

Error not covered in current implementation

List all personal contacts

Request

Method

GET

URI

/contact/personal

Header

Content-Type: application/json

Header

Authorization: Bearer ${JWT_TOKEN}

Curl example
curl -X GET http://localhost:8090/xuc/api/2.0/contact/personal \
-H "Content-Type: application/json" \
-H "Authorization: Bearer user_jwt_token"

Response

{
  "entries": [
      { "status": 0, "entry": [ "hawkeye", "pierce", "1002", "0761187406", "false"]},
      { "status": -2, "entry": [ "peter", "pan", "1004", "", "false"]}],
  "headers":
      ["Firstname", "Lastname", "Number", "Mobile", "Favorite"]
 }

Retrieve a specific personal contact

Request

Method

GET

URI

http://localhost:${XUC_PORT}/xuc/api/2.0/contact/personal/${CONTACT_UUID}

Header

Content-Type: application/json

Header

Authorization: Bearer ${JWT_TOKEN}

URL parameters

Field

Type

Description

CONTACT_UUID

string

UUID of the requested personal contact

Curl example
curl -X GET http://localhost:8090/xuc/api/2.0/contact/personal/28079dc0-2c6b-4332-9075-61da9229389f \
-H "Content-Type: application/json" \
-H "Authorization: Bearer user_jwt_token"

Response

{
   "id":"28079dc0-2c6b-4332-9075-61da9229389f",
   "firstname":"doe",
   "lastname":"john",
   "number":"1111",
   "mobile":"2222",
   "fax":"3333",
   "email":"j.doe@my.corp",
   "company":"corp"
}

Create a personal contact

Request

Method

POST

URI

http://localhost:${XUC_PORT}/xuc/api/2.0/contact/personal

Header

Content-Type: application/json

Header

Authorization: Bearer ${JWT_TOKEN}

Body parameters

Field

Type

Description

lastname

string

Last name of the personal contact

firstname

string

First name of the personal contact

company

string

Company of the personal contact

email

string

Email address of the personal contact

number

string

Phone number of the personal contact

mobile

string

Mobile number of the personal contact

fax

string

Fax number of the personal contact

Note

At least one of the following fields must be set: number, mobile, fax, email and lastname and/or firstname.

Curl example
curl -X POST http://localhost:8090/xuc/api/2.0/contact/personal \
-H "Content-Type: application/json" \
-H "Authorization: Bearer user_jwt_token" \
-d '{"firstname":"doe","lastname":"john","number":"1111","mobile":"2222","fax":"3333","email":"j.doe@my.corp","number":"1111","mobile":"2222","fax":"3333"}'

Response

{
   "id":"28079dc0-2c6b-4332-9075-61da9229389f",
   "firstname":"doe",
   "lastname":"john",
   "number":"1111",
   "mobile":"2222",
   "fax":"3333",
   "email":"j.doe@my.corp",
   "company":"corp"
}

Update a personal contact

Request

Method

PUT

URI

http://localhost:${XUC_PORT}/xuc/api/2.0/contact/personal/${CONTACT_UUID}

Header

Content-Type: application/json

Header

Authorization: Bearer ${JWT_TOKEN}

URL parameters

Field

Type

Description

CONTACT_UUID

string

UUID of the requested personal contact

Body parameters

Field

Type

Description

lastname

string

Last name of the personal contact

firstname

string

First name of the personal contact

company

string

Company of the personal contact

email

string

Email address of the personal contact

number

string

Phone number of the personal contact

mobile

string

Mobile number of the personal contact

fax

string

Fax number of the personal contact

Note

All fields are optional

Curl example
curl -X PUT http://localhost:8090/xuc/api/2.0/contact/personal/28079dc0-2c6b-4332-9075-61da9229389f \
-H "Content-Type: application/json" \
-H "Authorization: Bearer user_jwt_token" \
-d '{"firstname":"doe","lastname":"john","number":"1111","mobile":"2222","fax":"3333","email":"j.doe@my.corp","number":"1111","mobile":"2222","fax":"3333"}'

Response

{
   "id":"28079dc0-2c6b-4332-9075-61da9229389f",
   "firstname":"doe",
   "lastname":"john",
   "number":"1111",
   "mobile":"2222",
   "fax":"3333",
   "email":"j.doe@my.corp",
   "company":"corp"
}

Delete a personal contact

Request

Method

DELETE

URI

http://localhost:${XUC_PORT}/xuc/api/2.0/contact/personal/${CONTACT_UUID}

Header

Authorization: Bearer ${JWT_TOKEN}

URL parameters

Field

Type

Description

CONTACT_UUID

string

UUID of the requested personal contact

Curl example
curl -X DELETE http://localhost:8090/xuc/api/2.0/contact/personal/28079dc0-2c6b-4332-9075-61da9229389f \
-H "Authorization: Bearer user_jwt_token"

Response

It will return a 204 response.

Delete all personal contacts

Request

Method

DELETE

URI

http://localhost:${XUC_PORT}/xuc/api/2.0/contact/personal

Header

Authorization: Bearer ${JWT_TOKEN}

Curl example
curl -X DELETE http://localhost:8090/xuc/api/2.0/contact/personal \
-H "Authorization: Bearer user_jwt_token"

Response

It will return a 204 response.

Export personal contacts

Request

Method

GET

URI

http://localhost:${XUC_PORT}/xuc/api/2.0/contact/export/personal

Header

Authorization: Bearer ${JWT_TOKEN}

Curl example
curl -X GET http://localhost:8090/xuc/api/2.0/contact/export/personal \
-H "Authorization: Bearer user_jwt_token"

Response

It will return a csv file with UTF-8 encoding containing all personal of a user

company,email,fax,firstname,lastname,mobile,number
corp,jdoe@company.corp,3333,John,Doe,2222,1111

Import personal contacts

Request

Method

POST

URI

http://localhost:${XUC_PORT}/xuc/api/2.0/contact/import/personal

Header

Authorization: Bearer ${JWT_TOKEN}

Curl example
curl -X POST http://localhost:${XUC_PORT}/xuc/api/2.0/contact/import/personal \
-H "Authorization: Bearer user_jwt_token" \
-F 'file=@/path/to/file.csv;type=text/csv'

Note

A CSV file must be sent as the body of the request. The first line of the CSV file must be the header. The file may contain the following fields: company, email, fax, firstname, lastname, mobile, number. The fields are optional. However, at least one of these fields is required: number, mobile, fax, email and lastname and/or firstname The fields must be separated by a comma. The CSV file must be encoded in UTF-8.

company,email,fax,firstname,lastname,mobile,number
corp,jdoe@company.corp,3333,John,Doe,2222,1111

Response

The request will create and return the response for each personal contact (either success or failure) (HTTP code 201).

Example
{
   "created": [{
      "id": "e62ee672-f74a-498c-b138-86ac1b0ae429",
      "lastname": "Wayne"
   }, {
      "id": "d3a67f8e-3d8a-465a-9633-bde65a41f1bb",
      "lastname": "Hawking"
   }],
   "failed": [{
      "line": 3,
      "errors": ["too many fields"]
   }]
}

Call qualifications

To retrieve call qualification options and create call qualification answer.

Error management

If an error occurs while using API actions, error will always be raised with proper HTTP return code and will be wrapped in JSON object with following format

{
   "error": ${ERROR_CODE}
   "message": ${ERROR_MESSAGE}
}

Error codes

Error code

HTTP header code

Possible cause

JsonBodyNotFound

400

Qualification answer sent to API is not found

JsonErrorDecoding

400

Qualification answer sent to API is not JSON valid

Unreachable

503

Config management server is not available

NotHandledError

500

Error not covered in current implementation

Get call qualifications for a queue

Request

Method

GET

URI

/call_qualification/queue/${QUEUE_ID}

Header

Authorization: Bearer ${JWT_TOKEN}

Curl example
curl -X GET http://localhost:8090/xuc/api/2.0/call_qualification/queue/42 \
-H "Authorization: Bearer user_jwt_token"

Response

Will retrieve a list of objects containing all qualifications and sub qualifications for a single queue (HTTP code 200)

[
   {
      "id": 6,
         "name": "General Questions",
         "subQualifications": [
            { "id": 14, "name": "Common"},
            { "id": 15, "name": "Technical" }
         ]
   },
   {
      "id": 5,
         "name": "Support",
         "subQualifications": [
            { "id": 12, "name": "Technical" },
            { "id": 13, "name": "General" }
         ]
   }
]

Create call qualifications

Request

Method

POST

URI

/call_qualification

Header

Authorization: Bearer ${JWT_TOKEN}

Curl example
curl -X GET http://localhost:8090/xuc/api/2.0/call_qualification \
-H "Authorization: Bearer user_jwt_token"

Response

{
   "sub_qualification_id": 1,
   "time": "2018-03-21 17:00:00",
   "callid": "callid1",
   "agent": 1,
   "queue": 1,
   "first_name": "john",
   "last_name": "doe",
   "comment": "some comment",
   "custom_data": "some custom data"
}

Export call qualifications

Request

Method

GET

URI

/call_qualification/csv/${QUEUE_ID}/${FROM}/${TO}

Header

Authorization: Bearer ${JWT_TOKEN}

Curl example
curl -X GET http://localhost:8090/xuc/api/2.0/call_qualification/42/home/office \
-H "Authorization: Bearer user_jwt_token"

Response

It will return a csv file with UTF-8 encoding containing all call qualification answers of a queue

sub_qualification_id,time,callid,agent,queue,first_name,last_name,comment,custom_data
1,2018-03-21 17:00:00,callid1,1,1,john,doe,some comment,some custom data

Mobile application

To configure/handle XiVO mobile phone application

Error management

If an error occurs while using API actions, error will always be raised with proper HTTP return code and will be wrapped in JSON object with following format

{
    "error": <error_code>
    "message": <cause>
}

Error codes

Error code

HTTP header code

Possible cause

JsonBodyNotFound

400

Token sent to API is not found

JsonErrorDecoding

400

Request sent to API is not JSON valid

NotHandledError

500

Error not covered in current implementation

Set push registration token

Request

Method

POST

URI

/mobile/push/register

Header

Content-Type: application/json

Header

Authorization: Bearer ${JWT_TOKEN}

Body parameters

Field

Type

Description

login

string

CTI user login

Curl example
curl -X GET http://localhost:8090/xuc/api/2.0/mobile/push/register  \
-d '{"token": "1234-5678"}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer user_jwt_token"

Response

The response will register push notification token to wake up the mobile application answer (HTTP code 201).

Dial

Multiple dial APIs are available to generate dial actions from a user.

Error management

If an error occurs while using API actions, error will always be raised with proper HTTP return code and will be wrapped in JSON object with following format

{
   "error": ${ERROR_CODE}
   "message": ${ERROR_MESSAGE}
}

Else, the API will return the following JSON format

{
   "res": "success"
}

Error codes

Error code

HTTP header code

Possible cause

BadRequest

400

The body is missing or is invalid

NotHandledError

500

Error not covered in current implementation

Dial a number

This request dials the destination using the username of a CTI user provided in the url, also passing optional variables along.

Note

The CTI user whose username is provided must be an authenticated.

Warning

This action is only available for web service users with xuc.rest.dial.number.*.create ACL.

Request

Method

POST

URI

/dial/number/${USERNAME}

Header

Content-Type: application/json

Header

Authorization: Bearer ${JWT_TOKEN}

URL parameters

Field

Type

Description

USERNAME

string

Username of the CTI user to make the call

Body parameters

Field

Type

Description

destination

string

Number to be called someone is in queue

variables

object

Any other variables

Curl example
curl -X POST http://localhost:8090/xuc/api/2.0/dial/number/jbond \
-d '{"destination":"0123456789", "variables": { "varname1": "varval1",  "varname2": "varval2"}}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer user_jwt_token"

Dial a user

This request dials the payload username using the username provided in the url, also passing optional variables along.

Note

The CTI user whose username is provided must be an authenticated.

Warning

This action is only available for web service users with xuc.rest.dial.user.*.create ACL.

Request

Method

POST

URI

/dial/user/${USERNAME}

Header

Content-Type: application/json

Header

Authorization: Bearer ${JWT_TOKEN}

URL parameters

Field

Type

Description

USERNAME

string

Username of the CTI user to make the call

Body parameters

Field

Type

Description

username

string

Username of the user to call

variables

object

Any other variables

Curl example
curl -X POST http://localhost:8090/xuc/api/2.0/dial/user/jbond \
-d '{"username":"drno", "variables": { "varname1": "varval1",  "varname2": "varval2"}}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer user_jwt_token"

Dial from queue

This request dials the destination from a queue using the username provided in the url, also passing optional variables along.

Warning

This action is only available for web service users with xuc.rest.dial.fromqueue.create ACL.

Request

Method

POST

URI

/dial/fromqueue/${USERNAME}

Header

Content-Type: application/json

Header

Authorization: Bearer ${JWT_TOKEN}

URL parameters

Field

Type

Description

USERNAME

string

Username of the CTI user to make the call

Body parameters

Field

Type

Description

destination

string

Number to be called someone is in queue

queueId

Int

Identifier of the queue

variables

object

Any other variables

Curl example
curl -X POST http://localhost:8090/xuc/api/2.0/dial/fromqueue/jbond  \
-d '{"destination":"0123456789", "queueId": 152, "variables": { "varname1": "varval1",  "varname2": "varval2"}}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer user_jwt_token"

Dial to queue

This request dials the destination with a specific caller ID and then add it into a queue, also passing optional variables along.

Warning

This action is only available for web service users with xuc.rest.dial.toqueue.create ACL.

Request

Method

POST

URI

/dial/toqueue

Header

Content-Type: application/json

Header

Authorization: Bearer ${JWT_TOKEN}

Body parameters

Field

Type

Description

destination

string

Number to be called someone is in queue

queueName

string

Name of the queue

callerIdNumber

string

Number displayed to people in queue

variables

object

Any other variables

Curl example
curl -X POST http://localhost:8090/xuc/api/2.0/dial/toqueue  \
-d '{"destination":"0123456789", "queueName":"support", "callerIdNumber":"0403010200", "variables": { "varname1": "varval1",  "varname2": "varval2"}}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer user_jwt_token"

Do not disturb status and forwarding

Multiple APIs are available to control user forwards and DND status

Error management

If an error occurs while using API actions, error will always be raised with proper HTTP return code and will be wrapped in JSON object with following format

{
  "error": <error_code>
  "message": <cause>
}

Else, the API will return the following JSON format

{
   "res": "success"
}

Error codes

Error code

HTTP header code

Possible cause

JsonBodyNotFound

400

Token sent to API is not found

JsonErrorDecoding

400

Request sent to API is not JSON valid

UserNotFound

400

User not found

NotHandledError

500

Error not covered in current implementation

Set do not disturb status

This request will set the do not disturb status of the user provided in the url according to the state in the payload.

Warning

This action is only available for web service users with xuc.rest.dnd.*.create ACL.

Request

Method

POST

URI

/dnd/${USERNAME}

Header

Content-Type: application/json

Header

Authorization: Bearer ${JWT_TOKEN}

URL parameters

Field

Type

Description

USERNAME

string

Username of the CTI user to make the call

Body parameters

Field

Type

Description

state

boolean

Whether the do not disturb status is enabled or not

Curl example
curl -X POST http://localhost:8090/xuc/api/2.0/dnd/jbond  \
-d '{"state": true}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer user_jwt_token"

Unconditional forwarding

This requests sets the unconditional forwarding of the user provided in the url according to the payload.

Warning

This action is only available for web service users with xuc.rest.forward.unconditional.*.create ACL.

Request

Method

POST

URI

/forward/unconditional/${USERNAME}

Header

Content-Type: application/json

Header

Authorization: Bearer ${JWT_TOKEN}

URL parameters

Field

Type

Description

USERNAME

string

Username of the CTI user to make the call

Body parameters

Field

Type

Description

destination

string

Destination of the forwarding

enabled

boolean

State of the unconditional forwarding

Curl example
curl -X POST http://localhost:8090/xuc/api/2.0/forward/unconditional/jbond  \
-d '{"destination": "0123456789", "enabled": true}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer user_jwt_token"

No answer forwarding

This requests sets the no answer forwarding of the user provided in the url according to the payload

Warning

This action is only available for web service users with xuc.rest.forward.noanswer.*.create ACL.

Request

Method

POST

URI

/forward/noanswer/${USERNAME}

Header

Content-Type: application/json

Header

Authorization: Bearer ${JWT_TOKEN}

URL parameters

Field

Type

Description

USERNAME

string

Username of the CTI user to make the call

Body parameters

Field

Type

Description

destination

string

Destination of the forwarding

enabled

boolean

State of the no answer forwarding

Curl example
curl -X POST http://localhost:8090/xuc/api/2.0/forward/noanswer/jbond  \
-d '{"destination": "0123456789", "enabled": true}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer user_jwt_token"

Busy forwarding

This requests sets the busy forwarding of the user provided in the url according to the payload.

Warning

This action is only available for web service users with xuc.rest.forward.busy.*.create ACL.

Request

Method

POST

URI

/forward/busy/${USERNAME}

Header

Content-Type: application/json

Header

Authorization: Bearer ${JWT_TOKEN}

URL parameters

Field

Type

Description

USERNAME

string

Username of the CTI user to make the call

Body parameters

Field

Type

Description

destination

string

Destination of the forwarding

enabled

boolean

State of the busy forwarding

Curl example
curl -X POST http://localhost:8090/xuc/api/2.0/forward/busy/jbond  \
-d '{"destination": "0123456789", "enabled": true}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer user_jwt_token"

User call history

Multiple APIs are available to retrieve user call history

Error management

If an error occurs while using API actions, error will always be raised with proper HTTP return code and will be wrapped in JSON object with following format:

{
  "error": <error_code>
  "message": <cause>
}

Else, the API will return the following JSON format:

{
   "res": "success",
   "data": {...}
}

Error codes

Error code

HTTP header code

Possible cause

JsonBodyNotFound

400

Token sent to API is not found

JsonErrorDecoding

400

Request sent to API is not JSON valid

UserNotFound

400

User not found

NotHandledError

500

Error not covered in current implementation

User call history

This request retrieves the call history of the user provided in the url.

Warning

This action is only available for web service users with xuc.rest.history.*.read ACL.

Request

Method

GET

URI

/history/${USERNAME}

Header

Authorization: Bearer ${JWT_TOKEN}

URL parameters

Field

Type

Description

USERNAME

string

Username of the CTI user to make the call

Path parameters

Field

Type

Description

size

integer

Number of calls to retrieve

Curl example
curl -X POST http://localhost:8090/xuc/api/2.0/history/jbond?size=10  \
-H "Authorization: Bearer user_jwt_token"

User call history by days

This request retrieves the call history of the user provided in the url.

Warning

This action is only available for web service users with xuc.rest.history.days.*.read ACL.

Request

Method

GET

URI

/history/days/${USERNAME}

Header

Authorization: Bearer ${JWT_TOKEN}

URL parameters

Field

Type

Description

USERNAME

string

Username of the CTI user to make the call

Path parameters

Field

Type

Description

days

integer

Number of days to retrieve

Curl example
curl -X POST http://localhost:8090/xuc/api/2.0/history/days/jbond?days=10  \
-H "Authorization: Bearer user_jwt_token"

Agent callbacks and tickets

Import and export callback requests and tickets

Error management

If an error occurs while using API actions, error will always be raised with proper HTTP return code and will be wrapped in JSON object with following format

{
  "error": <error_code>
  "message": <cause>
}

Else, the API will return the following JSON format

{
   "res": "success",
   "data": {...}
}

Error codes

Error code

HTTP header code

Possible cause

JsonBodyNotFound

400

Token sent to API is not found

JsonErrorDecoding

400

Request sent to API is not JSON valid

UserNotFound

400

User not found

NotHandledError

500

Error not covered in current implementation

Import callback requests

This requests imports a csv of callback requests as text.

Warning

This action is only available for web service users with xuc.rest.callback_lists.callback_requests.csv.create ACL.

Request

Method

POST

URI

/callback_lists/callback_requests/csv

Header

Content-Type: text/json

Header

Authorization: Bearer ${JWT_TOKEN}

Body parameters

Field

Type

Description

listUuid

string

UUID of the list of callback requests

csv

string

CSV contents of the callback requests

Note

The csv parameter consists in one line: each line break should be replace with n.

Curl example
curl -X POST http://localhost:8090/xuc/api/2.0/callback_lists/callback_requests/csv \
-H "Content-Type: text/json" \
-H "Authorization: Bearer user_jwt_token" \
-d '{"listUuid": "1", "csv": "phoneNumber|mobilePhoneNumber|firstName|lastName|company|description|dueDate|period\n0230210092|0689746321|John|Doe|MyCompany|Call back quickly||\n0587963214|0789654123|Alice|O'Neill|YourSociety||2016-08-01|Afternoon"}'

Export callback tickets

This requests exports the list of tickets associated with the callback list uuid.

Warning

This action is only available for web service users with xuc.rest.callback_lists.callback_tickets.csv.create ACL.

Request

Method

POST

URI

/callback_lists/callback_tickets/csv

Header

Content-Type: application/json

Header

Authorization: Bearer ${JWT_TOKEN}

Body parameters

Field

Type

Description

listUuid

string

UUID of the list to export

Curl example
curl -X POST http://localhost:8090/xuc/api/2.0/callback_lists/callback_tickets/csv  \
-d '{"listUuid": "jsdfh-90298J-hdjkfd"}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer user_jwt_token"

Deprecated APIs

Warning

The following APIs are now deprecated. You can re-enable them to specific client based on their IP address. To allow a client, add its IP address to the DEPRECATED_API_HOST key in the XiVO CC custom.env file. You can add multiple address separated by comma (,).

Connection

This api is deprecated all the method are now able to autoconnect the user.

{"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>/

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].

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.

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

Agent

AgentLogin

Log an agent on an extension

curl -XPOST -d '{"agentphonenumber":"<phone number>", "agentnumber":"<agent number>"}' -H "Content-Type: application/json"  http://localhost:8090/xuc/api/1.0/agentLogin/

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 or on wrapup

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

User Call History by size

Get the last X calls of the user call history

curl -XGET -H "Content-Type: application/json"  http://localhost:8090/xuc/api/1.0/historyByUsername/<domain>/<username>?size=X

Answer

[
  {"start":"2018-09-20 17:38:41","duration":"00:00:02","srcUsername":"bruce","dstUsername":"alicej","status":"emitted"},
  {"start":"2018-09-20 17:19:40","duration":"00:00:01","srcUsername":"bruce","dstUsername":"cquefia","status":"emitted"},
  {"start":"2018-09-20 17:15:00","duration":"00:00:18","srcUsername":"cquefia","dstUsername":"bruce","status":"missed"},
  {"start":"2018-09-20 17:14:16","duration":"00:00:11","srcUsername":"cquefia","dstUsername":"bruce","status":"missed"}
]

User Call History by days

Get user call history of the last X days

curl -XGET -H "Content-Type: application/json"  http://localhost:8090/xuc/api/1.0/historyByUsername/<domain>/<username>?days=X

Answer

[
  {"start":"2018-09-20 17:38:41","duration":"00:00:02","srcUsername":"bruce","dstUsername":"alicej","status":"emitted"},
  {"start":"2018-09-20 17:19:40","duration":"00:00:01","srcUsername":"bruce","dstUsername":"cquefia","status":"emitted"},
  {"start":"2018-09-20 17:15:00","duration":"00:00:18","srcUsername":"cquefia","dstUsername":"bruce","status":"missed"},
  {"start":"2018-09-20 17:14:16","duration":"00:00:11","srcUsername":"cquefia","dstUsername":"bruce","status":"missed"}
]

Export 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"}}}}