Rest API
General form
http://localhost:$xucport/xuc/api/$version/$method/$domain/$username/
withHeaders((“Content-Type”, “application/json”))
$xucport : Xuc port number (default 8090)
$version : 1.0 or 2.0
$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
Authentication is needed to use version 2.0 of the API
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>", TTL, "<TTL>"}
or an error
{error:"<error_code>", message:"<error_message>"}
where error_code is one of:
InvalidCredentials: Invalid username or password
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: User was authenticated using SSO but the corresponding user does not exist on XiVO
SsoAuthenticationFailed
UnhandledError
This token can then be used with the CTI Authentication and Check authentication token.
Obtain authentication token (SSO/CAS)
curl -XGET http://localhost:8090/xuc/api/2.0/auth/cas?service=https://xucmgt.example.org&ticket=ST-11-Qsicgrh1mZ3dgoeOx7m6-af27d9025e0c
Will retrieve an object
{login: "<login>", token: "<token>"}
or an error
{error:"<error_code>", message:"<error_message>"}
where error_code is one of:
UserNotFound: User was authenticated using SSO but the corresponding user does not exist on XiVO
CasServerUrlNotSet: XiVOCC containers are not configured (see CAS SSO Authentication)
CasServerInvalidResponse: The CAS server returned an invalid response
CasServerInvalidParameter: The Parameters sent to the CAS Server are invalid
CasServerInvalidRequest: The Request to the CAS server is invalid
CasServerInvalidTicketSpec: The ticket specification is invalid
CasServerUnauthorizedServiceProxy: The CAS service proxy is not authorized
CasServerInvalidProxyCallback: The CAS service proxy callback is invalid
CasServerInvalidTicket: The ticket is invalid (probably expired or defined for another service)
CasServerInvalidService: The service is invalid
CasServerInternalError: CAS Server internal error
UnhandledError
This token can then be used with the CTI Authentication and Check authentication token.
Obtain authentication token (SSO/OpenID Connect)
It is possible to connect to Xuc through OpenId Connect 1.0 protocol. You just need to pass a OAuth access_token to xuc RS256 encoded.
curl -XGET http://localhost:$xucport/xuc/api/2.0/auth/oidc?token=eyJhbGciOiJSUzI[...]v8nKAcS1V4pXfOpg
Will retrieve an object
{login: "<login>", token: "<token>"}
or an error
{error:"<error_code>", message:"<error_message>"}
where error_code is one of:
UserNotFound: User was authenticated using SSO but the corresponding user does not exist on XiVO
OidcNotEnabled: Open Id connect authentication is not enabled (see OpenID Connect SSO Authentication)
OidcInvalidParameter: Missing access_token
OidcAuthenticationFailed: The access_token forwarded to Xuc is invalid
UnhandledError
Also, this token can be passed as an Authorization header to the same endpoint in the following format:
curl -XGET -H "Authorization: Bearer eyJhbGciOiJSUzI[...]v8nKAcS1V4pXfOpg" http://localhost:$xucport/xuc/api/2.0/auth/oidc
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>", TTL: "<TTL>"}
or an error
{error:"<error_code>", message:"<error_message>"}
where error_code is one of:
InvalidToken
InvalidJson
BearerNotFound
AuthorizationHeaderNotFound
TokenExpired
UnhandledError
Personal Contacts
To handle personal contacts of 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": <cause>
}
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
curl -XGET -H "Content-Type: application/json" -H "X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbiI6InZtYWNoaW4iLCJleHBpcmVzIjoxNDg5OTk4Mzg2fQ.R6bzc5fBRs74l7ZBdLVjSIbNx3j3e07mV6mAX4_sklI" http://localhost:8090/xuc/api/2.0/contact/personal
Will retrieve an object containing all personal contacts entries with associated values defined in headers (HTTP code 200)
{
"entries": [
{ "status": 0, "entry": [ "hawkeye", "pierce", "1002", "0761187406", "false"]},
{ "status": -2, "entry": [ "peter", "pan", "1004", "", "false"]}],
"headers":
["Firstname", "Lastname", "Number", "Mobile", "Favorite"]
}
Get
curl -XGET -H "Content-Type: application/json" -H "X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbiI6InZtYWNoaW4iLCJleHBpcmVzIjoxNDg5OTk4Mzg2fQ.R6bzc5fBRs74l7ZBdLVjSIbNx3j3e07mV6mAX4_sklI" http://localhost:8090/xuc/api/2.0/contact/personal/28079dc0-2c6b-4332-9075-61da9229389f
Will retrieve an object containing a single personal contact (HTTP code 200)
{
"id":"28079dc0-2c6b-4332-9075-61da9229389f",
"firstname":"doe",
"lastname":"john",
"number":"1111",
"mobile":"2222",
"fax":"3333",
"email":"j.doe@my.corp",
"company":"corp"
}
Create
{
"firstname":"doe",
"lastname":"john",
"number":"1111",
"mobile":"2222",
"fax":"3333",
"email":"j.doe@my.corp",
"company":"corp"
}
curl -XPOST -H "Content-Type: application/json" -H "X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbiI6InZtYWNoaW4iLCJleHBpcmVzIjoxNDg5OTk4Mzg2fQ.R6bzc5fBRs74l7ZBdLVjSIbNx3j3e07mV6mAX4_sklI" http://localhost:8090/xuc/api/2.0/contact/personal -d '{"lastname":"john","firstname":"doe","company":"corp","email":"j.doe@my.corp","number":"1111","mobile":"2222","fax":"3333"}'
Will create and return object containing a single personal contact with id (HTTP code 201)
{
"id":"28079dc0-2c6b-4332-9075-61da9229389f",
"firstname":"doe",
"lastname":"john",
"number":"1111",
"mobile":"2222",
"fax":"3333",
"email":"j.doe@my.corp",
"company":"corp"
}
Update
{
"firstname":"doe",
"lastname":"john",
"number":"1111",
"mobile":"2222",
"fax":"3333",
"email":"j.doe@my.corp",
"company":"corp"
}
curl -XPUT -H "Content-Type: application/json" -H "X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbiI6InZtYWNoaW4iLCJleHBpcmVzIjoxNDg5OTk4Mzg2fQ.R6bzc5fBRs74l7ZBdLVjSIbNx3j3e07mV6mAX4_sklI" http://localhost:8090/xuc/api/2.0/contact/personal/28079dc0-2c6b-4332-9075-61da9229389f -d '{"lastname":"john","firstname":"doe","company":"corp","email":"j.doe@my.corp","number":"1111","mobile":"2222","fax":"3333"}'
Will update and return object containing single personal contact with id (HTTP code 200)
{
"id":"28079dc0-2c6b-4332-9075-61da9229389f",
"firstname":"doe",
"lastname":"john",
"number":"1111",
"mobile":"2222",
"fax":"3333",
"email":"j.doe@my.corp",
"company":"corp"
}
Delete
curl -XGET -H "Content-Type: application/json" -H "X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbiI6InZtYWNoaW4iLCJleHBpcmVzIjoxNDg5OTk4Mzg2fQ.R6bzc5fBRs74l7ZBdLVjSIbNx3j3e07mV6mAX4_sklI" http://localhost:8090/xuc/api/2.0/contact/personal/28079dc0-2c6b-4332-9075-61da9229389f
Will return empty content (HTTP code 204)
Delete All
curl -XGET -H "Content-Type: application/json" -H "X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbiI6InZtYWNoaW4iLCJleHBpcmVzIjoxNDg5OTk4Mzg2fQ.R6bzc5fBRs74l7ZBdLVjSIbNx3j3e07mV6mAX4_sklI" http://localhost:8090/xuc/api/2.0/contact/personal
Will return empty content (HTTP code 204)
Export
curl -XGET -H "X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbiI6InZtYWNoaW4iLCJleHBpcmVzIjoxNDg5OTk4Mzg2fQ.R6bzc5fBRs74l7ZBdLVjSIbNx3j3e07mV6mAX4_sklI" http://localhost:8090/xuc/api/2.0/contact/export/personal
Will return csv text content with UTF-8 encoding (HTTP code 200) containing all personal contacts of a user
company,email,fax,firstname,lastname,mobile,number
corp,jdoe@company.corp,3333,John,Doe,2222,1111
Import
Note
request needs to have plain csv as content with utf-8 charset
company,email,fax,firstname,lastname,mobile,number
corp,jdoe@company.corp,3333,John,Doe,2222,1111
curl -XPOST -H "Content-Type: text/csv;charset=UTF-8" -H "X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbiI6InZtYWNoaW4iLCJleHBpcmVzIjoxNDg5OTk4Mzg2fQ.R6bzc5fBRs74l7ZBdLVjSIbNx3j3e07mV6mAX4_sklI" http://localhost:8090/xuc/api/2.0/contact/import/personal -d 'company,email,fax,firstname,lastname,mobile,number\ncorp,jdoe@company.corp,3333,John,Doe,2222,1111'
Will create and return object containing result of success/failure for each personal contact inserted (HTTP code 201)
{
"created": [{
"id": "e62ee672-f74a-498c-b138-86ac1b0ae429",
"lastname": "Wayne"
}, {
"id": "d3a67f8e-3d8a-465a-9633-bde65a41f1bb",
"lastname": "Hawking"
}],
"failed": [{
"line": 3,
"errors": ["too many fields"]
}]
}
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": <cause>
}
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
curl -XGET -H "Content-Type: application/json" -H "X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbiI6InZtYWNoaW4iLCJleHBpcmVzIjoxNDg5OTk4Mzg2fQ.R6bzc5fBRs74l7ZBdLVjSIbNx3j3e07mV6mAX4_sklI" http://localhost:8090/xuc/api/2.0/call_qualification/queue/$queueId
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
{
"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"
}
curl -XPOST -H "Content-Type: application/json" -H "X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbiI6InZtYWNoaW4iLCJleHBpcmVzIjoxNDg5OTk4Mzg2fQ.R6bzc5fBRs74l7ZBdLVjSIbNx3j3e07mV6mAX4_sklI" http://localhost:8090/xuc/api/2.0/call_qualification -d -d '{"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"}'
Will create a call qualification answer and return id of the created call qualification answer (HTTP code 201)
Export
curl -XGET -H "Content-Type: application/json" -H "X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbiI6InZtYWNoaW4iLCJleHBpcmVzIjoxNDg5OTk4Mzg2fQ.R6bzc5fBRs74l7ZBdLVjSIbNx3j3e07mV6mAX4_sklI" http://localhost:8090/xuc/api/2.0/call_qualification/csv/$queueId/$from/$to
Will return csv text content with UTF-8 encoding (HTTP code 200) containing all call qualification answer 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
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 Android push registration token
{
"token": "1234-5678",
}
curl -XPOST -H "Content-Type: application/json" -H "X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbiI6InZtYWNoaW4iLCJleHBpcmVzIjoxNDg5OTk4Mzg2fQ.R6bzc5fBRs74l7ZBdLVjSIbNx3j3e07mV6mAX4_sklI" http://localhost:8090/xuc/api/2.0/config/mobile/push/register/android?apiVersion=2.0 -d '{"token": "1234-5678"}'
Will register android mobile push notification token to wake up mobile application answer (HTTP code 201)
Set iOS push registration token
{
"token": "1234-5678",
}
curl -XPOST -H "Content-Type: application/json" -H "X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbiI6InZtYWNoaW4iLCJleHBpcmVzIjoxNDg5OTk4Mzg2fQ.R6bzc5fBRs74l7ZBdLVjSIbNx3j3e07mV6mAX4_sklI" http://localhost:8090/xuc/api/2.0/config/mobile/push/register/ios?apiVersion=2.0 -d '{"token": "1234-5678"}'
Will register iOS mobile push notification token to wake up mobile application answer (HTTP code 201)
Deprecated APIs
Set push registration token
{
"token": "1234-5678",
}
curl -XPOST -H "Content-Type: application/json" -H "X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbiI6InZtYWNoaW4iLCJleHBpcmVzIjoxNDg5OTk4Mzg2fQ.R6bzc5fBRs74l7ZBdLVjSIbNx3j3e07mV6mAX4_sklI" http://localhost:8090/xuc/api/2.0/mobile/push/register -d '{"token": "1234-5678"}'
Will register mobile push notification token to wake up mobile application answer (HTTP code 201)
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"}
]