XiVO Configuration server API

This section describes XiVO Configuration server API. These APIs will replace old legacy apis and will be supported by the configuration server dockerized component. These are mainly REST APIs.

In the following, all url are relative to the config-mgt base url and port. For example a relative URL /callback_lists is meant to be replaced by

http://192.168.29.101:9100/configmgt/api/1.0/callback_lists

assuming that XiVO is available at 192.168.29.101

Important

All configmgt APIs are described in a Swagger UI available at /api for example : http://192.168.29.101/configmgt/api.

Authentication

To use the config-mgt api you need to add an additional header in the HTTP Request. The header name is X-Auth-Token and its value must be the same as the PLAY_AUTH_TOKEN environment variable defined in the custom.env of the docker-compose environment hosting the configuration server container (see Shared token).

Example:

curl -XGET -H "Content-Type: application/json" -H "Accept: application/json" \
     -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}"  http://localhost:9100/configmgt/api/1.0/callback_lists

Dynamic filters

A dynamic filter is just a JSON representation to create lite look-a-like SQL assertions. It contains:

  • field (string): required Field to make your query on

  • operator: Can be one of = , != , > , >= , < , <= , like , ilike , is null , is not null, contains_all

  • value (string, number, boolean): value to filter on

  • list (array): list of values to filter on. Used only with the operator contains_all

  • order: can be ASC or DESC

Examples :

Return all the users ordered by the fullName ascending:

{"field":"fullName", "order": "ASC"}

Filter and return all the users with a fullName beginning with Jack and ordering them ascending:

{"field":"fullName", "operator":"like", "value":"Jack%", "order": "ASC"}

Return the users named James Bond:

{"field":"fullName", "operator":"=", "value":"James Bond"}

Return the users associated with (at least) labels red and blue (i.e. all users belonging to both labels red and blue):

{"field":"label", "operator":"contains_all", "list":["blue", "red"]}

Users

Following API allow to list and find XiVO users

Get all users

This API retrieves all XiVO users.

Description:

URL

api/2.0/users

Method

GET


Example Query:

curl -XGET -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/2.0/users'

Response:

[
   {
      "fullName":"user A",
      "provisioning":583115,
      "lineType":"phone",
      "phoneNumber":"1000",
      "entity":"Test",
      "mdsName":"default",
      "mdsDisplayName":"MDS Main",
      "labels":[
         "blue",
         "green",
         "red"
      ]
   },
   {
      "fullName":"user B",
      "provisioning":273444,
      "lineType":"webrtc",
      "phoneNumber":"1001",
      "entity":"Test",
      "mdsName":"default",
      "mdsDisplayName":"MDS Main",
      "labels":[
         "green",
         "red"
      ]
   }
]

Find users

Finds some users using dynamic filters.

Description:

URL

/api/2.0/users/find

Method

POST

Request body

Json object with field & value pair.


Allowed field names:

filters

List of Dynamic filters

offset

Distance between the beginning and the first result to retrieve, used for pagination

limit

Max number of results to return

List of filterable columns

  • phoneNumber

  • fullName

  • entity

  • mdsDisplayName


Example

Query:

curl -XPOST -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/2.0/users/find' \
  -d '
    {
      "filters":[
        {"field":"phoneNumber", "operator":"=", "value":"1000", "order": "ASC"}
      ],
      "offset":0,
      "limit":100}'

Response:

{
 "total":1,
 "list":[
    {
       "fullName":"user A",
       "provisioning":583115,
       "lineType":"ua",
       "phoneNumber":"1000",
       "entity":"Test",
       "mdsName":"default",
       "mdsDisplayName": "MDS Main",
       "labels":[
          "blue",
          "green",
          "red"
       ]
    }
 ]
}

Get user’s line

This API retrieves XiVO user line associated to it.

Description:

URL

api/2.0/users/:id/line

Method

GET


Line Types:

phone

Physical SIP device

webrtc

Web SIP softphone

ua

Unique account, which is hybrid line allowing webrtc if connected to assistant, otherwise use phone if not connected.

sccp

For Cisco non SIP phones

custom

Customized endpoint which is maybe not a device

Example Query:

curl -XGET -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/2.0/users/1/line'

Response:

{
      "id": 40,
      "lineType": "phone",
      "context": "default",
      "extension": "1000",
      "site": "default",
      "name": "nrzpjngu",
      "lineNum": 1,
      "provisioningId": 661997
}

Result Code

  • 200 : The user line is found

  • 404 : The user line is not found

Create / Update user’s line

These API allow to create/update XiVO user line.

Description:

URL

api/2.0/users/:id/line

Method

POST for creation, PUT for update

Url parameters
id

user’s id

Request body

Json object with field & value pair.

Allowed field names:

lineType

One of phone,*webrtc*,*ua*,*sccp*,*custom*

extension

user line phone number

context

Context of the user (e.g. default)

site

Xivo where will be located the user (e.g. default, mds1…)

device

Hash that reprensent device in XiVO (Optional)

lineNum

Line slot to use on the device itself (not relevant for webrtc line)


Example Query:

curl -XPOST -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/2.0/users/1/line' \
  -d '
    {
      "lineType":"phone",
      "context":"default",
      "site":"default",
      "extension":"1000",
      "lineNum":1
    }'

Response:

{
  "id": 40,
  "lineType": "phone",
  "context": "default",
  "extension": "1000",
  "site": "default",
  "name": "nrzpjngu",
  "lineNum": 1,
  "provisioningId": 661997
}

Result Code

  • 200 : The user line is created

  • 404 : The user line cannot be found or created/updated

If the user line already exists:

{
  "error": "LineNotFound",
  "message": "Unable to create line for user Id 1"
}

Delete user’s line

These API allow to delete a line of a XiVO user.

Description:

URL

api/2.0/users/:id/line

Method

DELETE

Url parameters
id

user’s id


Example Query:

curl -XDELETE -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/2.0/users/1/line'

Result Code

  • 204 : The user line is successfully deleted

  • 404 : The user is not found

If the user line is not found:

{
  "error": "LineNotFound",
  "message": "Unable to delete line for user Id 1"
}

Validate a user

This API allow to validate a user used by authentication.

Description:

URL

api/2.0/user/validate

Method

POST


Example Query:

curl -XPOST -H "Content-Type: application/json" -H "Accept: application/json" \
-H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/2.0/user/validate' \
-d '
  {
    "username":"john",
    "password":"doe"
    }'

Result Code

  • 204 : The user is successfully validated

  • 404 : The user is not found

If the user line is not found:

{
  "error": "NotFoundError",
  "message": "User not found"
}

User services

Following API allow to get and edit user services like forwards and do not disturb feature.

Get user services

Query:

curl -XGET -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/2.0/users/1/services'

Response:

{
  "dndEnabled": false,
  "busy": {
    "enabled": false,
    "destination": "1002"
  },
  "noanswer": {
    "enabled": false,
    "destination": "123"
  },
  "unconditional": {
    "enabled": false,
    "destination": "1001"
  }
}

Update user services

Query:

curl -XPUT -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/2.0/users/1/services' \
  -d '
    {
      "dndEnabled": true,
      "busy": {
        "enabled": false,
        "destination": "1002"
      },
      "noanswer": {
        "enabled": false,
        "destination": "123"
      },
      "unconditional": {
        "enabled": false,
        "destination": "1001"
      }
  }'

Response:

{
  "dndEnabled": true,
  "busy": {
    "enabled": false,
    "destination": "1002"
  },
  "noanswer": {
    "enabled": false,
    "destination": "123"
  },
  "unconditional": {
    "enabled": false,
    "destination": "1001"
  }
}

It is also possible to only update partial information:

curl -XPUT -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/2.0/users/1/services' \
  -d '{"dndEnabled": false}'

Response:

{
  "dndEnabled": false,
}

Profiles

Users can be given a certain profile. The profiles are:

  • Administrator

  • Supervisor

  • Teacher

A profile defines:

  1. an access right to some applications (CC Manager, Recording Server …)

  2. and also some rights inside the application.

These profiles are described in Profile Management page.

Get all users’ profiles

This API retrieves XiVO users having a login and a profile defined.

Description:

URL

/users

Method

GET


Example Query:

curl -XGET -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/1.0/users'

Response:

[
  {"name":"Ménage","firstname":"Jean","login":"jmenage","profile":"teacher"},
  {"name":"Urbain","firstname":"Jocelyn","login":"jurbain","profile":"admin"}
]

Get a user’s profile and rights

This API retrieves the profile and the associated rights of a XiVO user having a login.

Description:

URL

/rights/user

Method

GET

Url parameters
login

user’s login name


Example Query:

curl -XGET -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/1.0/rights/user/jbond'

Response:

{
  "type":"supervisor",
  "data":{"queueIds":[3,2,1,7],
  "groupIds":[3,1,2],"incallIds":[],
  "recordingAccess":true,
  "dissuasionAccess":false}
}

Update user’s profile or rights

Updates the profile or the associated right of a XiVO user having login.

Description:

URL

/rights/user

Method

POST

Url parameters
login

user’s login name

Request body

Json object with field & value pair.


Allowed field names:

type

The profile to set (admin, supervisor or teacher)

data

The rights to update

queueIds

IDs of the queues the supervisor has access to (for supervisors and teachers)

groupIds

IDs of the groups the supervisor has access to (for supervisors and teachers)

incallIds

IDs of the incalls the supervisor has access to (for supervisors and teachers)

recordingAccess

whether or not the supervisor can access recordings (for supervisors only, true by default)

dissuasionAccess

whether or not the supervisor can update dissuasion destinations (for supervisors only, false by default)


Example Query:

curl -v -XPOST -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/1.0/rights/user/jbond' \
  -d '{"type":"supervisor",
        "data":{  "queueIds":[3,2,1,7],
                  "groupIds":[3,1,2],
                  "incallIds":[],
                  "recordingAccess":true,
                  "dissuasionAccess":false  }
      }'

Delete user’s profile

Delete the profile associated to a XiVO user having login.

Description:

URL

/rights/user

Method

DELETE

Url parameters
login

user’s login name


Example Query:

curl -XDELETE -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/1.0/rights/user/jbond'

Users preferences

Following APIs allow the management of the users preferences.

List of preferences :

  • preferred_device : For unique account users, this property is the value of the default device used by the user with the applications. It can be either phone or webrtc.

Get all the user’s preferences

Get all the preferences for a user.

Description:

URL

/users/:id/preferences

Method

GET

Url parameters
id

user’s id


Example

Query:

curl -XPUT -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/2.0/users/3/preferences'

Result:

[{
  "key": "preferred_device",
  "value": "phone",
  "value_type" : "String"
},
{
  "key": "other_preference",
  "value": "42",
  "value_type" : "number"
}]

Get a user’s preference

Get a specific preference for a user.

Description:

URL

/users/:id/preferences/:preference_key

Method

GET

Url parameters
id

user’s id

preference_key

key of the preference


Example

Query:

curl -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/2.0/users/3/preferences/preferred_device'

Result:

{
  "value": "phone",
  "value_type" : "String"
}

Create user preference

Initialize the value of a preference for a user.

Description:

URL

/users/:id/preferences/:preference_key

Method

POST

Url parameters
id

user’s id

preference_key

key of the preference

Request body

Json object with field & value pair.


Example

Query:

curl -XPOST -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/2.0/users/3/preferences/preferred_device'
  -d {"value": "phone", "value_type": "String"}

Result Code

  • 204 : The preference is successfully created

  • 409 : The preference is already set for this user

Update user preference

Update the value of a preference for a user.

Description:

URL

/users/:id/preferences/:preference_key

Method

PUT

Url parameters
id

user’s id

preference_key

key of the preference

Request body

Json object with field & value pair.

Result Code

  • 204 : The preference is successfully updated

  • 404 : The preference is not set for this user


Example

Query:

curl -XPUT -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/2.0/users/3/preferences/preferred_device'
  -d {"value": "webrtc", "value_type": "string"}

Delete a specific user preference

Delete a specific preference for a user.

Description:

URL

/users/:id/preferences/:preference_key

Method

DELETE

Url parameters
id

user’s id

preference_key

key of the preference


Example

Query:

curl -XDELETE -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/2.0/users/3/preferences/preferred_device'

Result Code

  • 204 : The preference is successfully updated

  • 404 : The preference is not set for this user

Callbacks

The following API allow to define callbacks, a callback, is a shared note for agents in the same queue to know that he must call his customer before a deadline. It is used in CC Agent feature existing in Xivo solutions.

A what so called Callback is in fact splitted in four distinct entities:
  • Callback list: Container object used to define a set of callback requests

  • Callback request: Core object that contains firstname, lastname, phone number… of the customer to call back

  • Callback period: The preferred interval of time in which the call should be performed

  • Callback ticket: Once callback request is taken by an agent, a ticket is created to sum up actions made on the request, like the status of the call and if the request is now closed or not.

More information on how to Process Callbacks with CCAgent

Create Callbacks list

Create a Callback list container for a queue

Description:

URL

/callback_lists

Method

POST

Request body

Json object with field & value pair.


Allowed field names:

name

The name of the list

queueId

The queue to affect the callback requests


Example

Query:

curl -XPOST -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/1.0/callback_lists'  \
  -d '{"name":"newlist", "queueId":1}'

Response:

{
    "callbacks": [],
    "name": "newlist",
    "queueId": 1,
    "uuid": "9d28d8fe-0548-4d45-aa08-9623ef69a04b"
}

Get Callbacks list

List all the Callback list containers

Description:

URL

/callback_lists

Method

GET

Url parameters
withRequest

boolean to retrieve list if and only if it contains ongoing callback requests


Example

Query:

curl -XGET -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" \
  'http://localhost:9100/configmgt/api/1.0/callback_lists'

Response:

[
  {
    "uuid": "fea963f5-1920-468c-b52a-93dc88791ba8",
    "name": "Mine",
    "queueId": 2,
    "callbacks": [
      {
        "uuid": "edb734e7-9d8f-403d-8cf6-d42ecf9e48d7",
        "listUuid": "fea963f5-1920-468c-b52a-93dc88791ba8",
        "phoneNumber": "0230210092",
        "mobilePhoneNumber": "0689746321",
        "firstName": "John",
        "lastName": "Doe",
        "company": "MyCompany",
        "description": "Call back quickly",
        "preferredPeriodUuid": "31f91ef6-ebda-4e0d-a9fa-5ebd3da30951",
        "dueDate": "2017-09-27",
        "queueId": 2,
        "clotured": false,
        "preferredPeriod": {
          "uuid": "31f91ef6-ebda-4e0d-a9fa-5ebd3da30951",
          "name": "Toute la journ\u00e9e",
          "periodStart": "09:00:00",
          "periodEnd": "17:00:00",
          "default": true
        }
      }
    ]
  },
  {
    "uuid": "75509ad3-3f81-40be-ad90-2c36d7a2c809",
    "name": "another",
    "queueId": 2,
    "callbacks": [

    ]
  }
]

Delete Callbacks list

Delete a Callback list container

Description:

URL

/callback_lists

Method

DELETE


Example

Query:

curl -XDELETE -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/1.0/callback_lists'

Response:

{
    "callbacks": [],
    "name": "newlist",
    "queueId": 1,
    "uuid": "9d28d8fe-0548-4d45-aa08-9623ef69a04b"
}

Import Callbacks requests

Import callback request in a Callback list container

Description:

URL

/callback_lists/<listUuid>/callback_requests/csv

Method

POST

Url parameters
listUuid

id of the callback list

Request body

should be compliant with following format


Example

Query:

curl -XPOST -H "Content-Type: text/plain" -H "Accept: text/plain" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" \
  'http://localhost:9100/configmgt/api/1.0//callback_lists/9d28d8fe-0548-4d45-aa08-9623ef69a04b/callback_requests/csv' \
  -d 'phoneNumber|mobilePhoneNumber|firstName|lastName|company|description|dueDate|period
      0230210092|0689746321|John|Doe|MyCompany|Call back quickly||
      0587963214|0789654123|Alice|O'Neill|YourSociety||2016-08-01|Afternoon'

Create Callback request

Create a single callback request in a callback list

Description:

URL

/callback_lists/<listUuid>/callback_requests

Method

POST

Url parameters
listUuid

id of the callback list

Request body

Json object with field & value pair.


Allowed field names:

phoneNumber

The number to call

mobilePhoneNumber

Alternate number to call

firstName

Contact first name (optional)

lastName

Contact last name (optional)

company

Contact company name (optional)

description

Note displayed inside the callback for the agent (optional)

dueDate

Deadline of the callback, using ISO format: YYYY-MM-DD

period

Name of the period as defined in callback list. (optional)


Example

Query:

curl -XPOST -H "Content-Type: application/json" -H "Accept: application/json"  \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/1.0//callback_lists/9d28d8fe-0548-4d45-aa08-9623ef69a04b/callback_requests' \
  -d '
  {
      "company":"Cie",
      "phoneNumber":"0298765432",
      "mobilePhoneNumber":"0654321234",
      "firstName":"Jack"
  }'

Find Callback request

Finds a callback request using dynamic filters.

Description:

URL

callback_requests/find

Method

POST

Request body

Json object with field & value pair.


Allowed field names:

filters

List of Dynamic filters

offset

Distance between the beginning and the first result to retrieve, used for pagination (optional)

limit

Max number of result to return (optional)


Example

Query:

curl -XPOST -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/1.0/callback_requests/find' \
  -d '
    {
      "filters":[
        {"field":"phoneNumber", "operator":"=", "value":"1000"}
      ],
      "offset":0,
      "limit":100}'

Response:

{
  "total": 1,
  "list": [
    {
      "uuid": "7691e6c8-6ebc-4d8f-a41c-45c049ac0dd4",
      "listUuid": "fea963f5-1920-468c-b52a-93dc88791ba8",
      "phoneNumber": "1000",
      "mobilePhoneNumber": "2000",
      "preferredPeriodUuid": "a6119323-a793-4264-987b-c565ceac342b",
      "dueDate": "2018-07-05",
      "queueId": 2,
      "clotured": false,
      "preferredPeriod": {
        "uuid": "a6119323-a793-4264-987b-c565ceac342b",
        "name": "Toute la journ\u00e9e",
        "periodStart": "09:00:00",
        "periodEnd": "17:00:00",
        "default": true
      }
    }
  ]
}

Agents

Get agent configuration

This api retrieves the agent configuration together with associated queues

Description:

URL

/agent_config

Method

GET

Url parameters
id

agent’s id


Example

Query:

curl -XGET -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/1.0/agent_config/1'

Response:

{
  "id": 1,
  "firstname": "John", "lastname": "Doe", "number": "1001", "context": "default",
  "member": [
    {
      "queue_name": "queue1", "queue_id": 1,
      "interface": "Agent\/1001", "penalty": 1,
      "commented": 0,
      "usertype": "Agent", "userid": 1, "channel": "Agent",
      "category": "Queue", "position": 1
    },
    {
      "queue_name": "queue2", "queue_id": 2,
      "interface": "Agent\/1001", "penalty": 2,
      "commented": 0,
      "usertype": "Agent", "userid": 1, "channel": "Agent",
      "category": "Queue", "position": 1
    }
  ],
  "numgroup": 1,
  "userid": 1
}

Get all agent configurations list

List all the agents together with associated queues

Description:

URL

/agent_config

Method

GET

Url parameters


Example

Query:

curl -XGET -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/1.0/agent_config'

Response:

  [{
  "id": 1,
  "firstname": "Agent",
  "lastname": "One",
  "number": "1001",
  "context": "default",
  "member": [{
      "queue_name": "queue1",
      "queue_id": 1,
      "interface": "Agent/1001",
      "penalty": 1,
      "commented": 0,
      "usertype": "Agent",
      "userid": 1,
      "channel": "Agent",
      "category": "Queue",
      "position": 1
    }],
  "numgroup": 1,"userid": 1
},
{
  "id": 2,
  "firstname": "Agent",
  "lastname": "Two",
  "number": "1002",
  "context": "default",
  "member": [{
      "queue_name": "queue2",
      "queue_id": 2,
      "interface": "Agent/1002",
      "penalty": 1,
      "commented": 0,
      "usertype": "Agent",
      "userid": 2,
      "channel": "Agent",
      "category": "Queue",
      "position": 1
    }],
  "numgroup": 1,"userid": 2 }]

Queue Dissuasion

Get the dissuasion for a queue

Returns the dissuasion of a given queue: if a queue has its No Answer ‣ Fail case configured to

  • Destination: Sound file

  • Filename: <some_file>

then it returns the sound file name <some_file> configured.

Description:

URL

/queue/:id/dissuasion

Method

GET

Url parameters
id

queue’s id


Example:

Query:

curl -XGET -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" localhost:9000/configmgt/api/1.0/queue/3/dissuasion

Response:

If the queue sales has its dissuasion configured towards the sound file sales_audio_file.wav:

{
  "id": 3,
  "name": "sales",
  "dissuasion": {
    "type": "soundFile",
    "value": {
      "soundFile": "sales_audio_file"
    }
  }
}

If the queue sales has its dissuasion configured towards an other queue with id support:

{
  "id": 3,
  "name": "sales",
  "dissuasion": {
    "type": "queue",
    "value": {
      "queueName": "support"
    }
  }
}

If the queue sales has its dissuasion configured neither towards a sound file nor a queue:

{
  "id": 3,
  "name": "sales",
  "dissuasion": {
    "type": "other"
  }
}

If the queue does not exist:

{
  "error": "QueueNotFound",
  "message": "Unable to perform getQueueDissusasion on queue 3 - QueueNotFound"
}

Get all the sound files dissuasion for a queue

Returns the list of dissuasions available for a given queue:

  • the list of sound files is taken from directory /var/lib/xivo/sounds/playback/,

  • a sound file is available for a given queue if it starts with the queuename (e.g. for queue sales the sound file must start with sales_).

  • the default queue is defined in the custom.env

Description:

URL

/queue/:id/dissuasions

Method

GET

Url parameters
id

queue’s id


Example:

Query:

curl -XGET -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" localhost:9000/configmgt/api/1.0/queue/3/dissuasions

Response:

For the queue named sales with sound files sales_audio_file.wav and sales_audio_file_2 present in dir /var/lib/xivo/sounds/playback/, and the queue switchboard defined in custom.env:

{
  "id": 3,
  "name": "sales",
  "dissuasions": {
    "soundFiles": [
      {
        "soundFile": "sales_audio_file"
      },
      {
        "soundFile": "sales_audio_file_2"
      }
    ],
    "queues": [
      {
        "queueName": "switchboard"
      }
    ]
  }
}

If the queue does not exist

{
  "error": "QueueNotFound",
  "message": "Unable to perform getQueueDissusasionList on queue 3 - QueueNotFound"
}

Set the dissuasion sound file for a given queue

Sets the dissuasion sound file for a given queue.

Description:

URL

/queue/<id>/dissuasion/sound_file

Method

PUT

Url parameters
id

queue’s id

Request body

Json object with soundFile


Example:

Query:

curl -XPUT -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" localhost:9000/configmgt/api/1.0/queue/3/dissuasion/sound_file -d '{"soundFile": "sales_newSoundFile"}'

Response:

If the change was successful (with the new file being, for instance, sales_newSoundFile.wav)

{
  id: 3,
  soundFile: "sales_newSoundFile"
}

If the queue does not exist

{
  "error": "QueueNotFound",
  "message": "Unable to perform updateQueueDissuasion on queue 3 - QueueNotFound"
}

If the file does not exist

{
  "error": "FileNotFound",
  "message": "Unable to perform updateQueueDissuasion on queue 3 with file sales_newSoundFile - FileNotFound"
}

For a given queue, set the queue to redirect calls to in case of dissuasion

For a given queue, sets the queue to redirect calls to in case of dissuasion.

Description:

URL

/queue/<id>/dissuasion/queue

Method

PUT

Url parameters
id

queue’s id

Request body

Json object with queueName


Example:

Query:

curl -XPUT -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" localhost:9000/configmgt/api/1.0/queue/3/dissuasion/queue -d '{"queueName": "sales_queue"}'

Response:

If the change was successful (with the new queue to redirect calls to being, for instance, sales_queue)

{
  id: 3,
  queueName: "sales_queue"
}

If the queue we want to change the dissuasion destination of does not exist

{
  "error": "QueueNotFound",
  "message": "Unable to perform updateQueueDissuasion on queue 3 - QueueNotFound"
}

If the queue to redirect calls to does not exist

{
  "error": "QueueNotFound",
  "message": "Unable to perform updateQueueDissuasion on queue 3: could not find the queue 'sales_queue' - QueueNotFound"
}

Sip Configuration

Get sip configuration

Retrieve the configured stun address.

Example:

Query:

curl -XGET -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" localhost:9000/configmgt/api/1.0/sip/ice_servers

Response::

{
  "stun_address": "stun:stun.l.google.com:19302"
}

Meeting Rooms

The following API allows to retrieve, edit and delete meeting rooms.

Get a meeting room

Retrieve a meeting room by id

Description:

URL

/meetingrooms/<id>

Method

GET

Url parameters
id

meeting room’s id

Example:

Query:

curl -XGET -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" localhost:9000/configmgt/api/2.0/meetingrooms/1

Response::

{
 "id":1,
 "name":"myConfRoom1",
 "displayName":"My Conf Room 1",
 "number":1050,
 "userPin":1234
}

Result Code

  • 200 : The meeting room is retrieved

  • 500 : The meeting room is not retrieved due to an exception

Get all meeting rooms

Description:

URL

/meetingrooms

Method

GET

Example:

Query:

curl -XGET -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" localhost:9000/configmgt/api/2.0/meetingrooms

Response::

[
 {
    "id":1,
    "name":"myConfRoom1",
    "displayName":"My Conf Room 1",
    "number":1050,
    "userPin":1234
 },
 {
    "id":2
    "name":"myConfRoom2",
    "displayName":"My Conf Room 2",
    "number":1051
 }
]

Result Code

  • 200 : The meeting rooms are retrieved

  • 500 : The meeting rooms are not retrieved due to an exception

Create / Update a meeting room

Description:

URL

/meetingrooms

Method

POST for create, PUT for update

Request body

Json object with field & value pair.

Allowed field names:

id

Id of the meeting room, only required when updating the meeting room

name

Technical unique name of the meeting room (e.g. myMeetingRoom1)

displayName

Display name of the meeting room (e.g. My Meeting Room 1)

number

Number of the meeting room

userPin

Optional, the pin to access the meeting room (e.g. 1234)

Example:

Query:

curl -XPOST -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" localhost:9000/configmgt/api/2.0/meetingrooms
  -d {"name": "myConfRoom1", "displayName": "My Conf Room 1", "number": 1050, "userPin": 1234}

Query:

curl -XPUT -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" localhost:9000/configmgt/api/2.0/meetingrooms
  -d {"id": 1, "name": "myConfRoom1", "displayName": "My Conf Room 1", "number": 1050, "userPin": 1234}

Response::

{
    "id":1,
    "name":"myConfRoom1",
    "displayName":"My Conf Room 1",
    "number":1050,
    "userPin":1234
}

Result Code

  • 200 : The meeting room is created/updated

  • 400 : The meeting room is not created/updated (bad JSON or duplicate)

  • 500 : The meeting room is not created/updated

If the meeting room already exists:

{
  "error": "Duplicate",
  "message": "duplicate key value violates unique constraint <constraint_name>"
}

Delete a meeting room

Description:

URL

/meetingrooms/<id>

Method

DELETE

Example:

Query:

curl -XGET -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" localhost:9000/configmgt/api/2.0/meetingrooms/1

Response::

{
    "id":1,
    "name":"myConfRoom1",
    "displayName":"My Conf Room 1",
    "number":1050,
    "userPin":1234
}

Result Code

  • 200 : The meeting room is deleted

  • 500 : The meeting room is not deleted

Find meeting rooms

This API allows to find meeting rooms using dynamic filters.

Description:

URL

/meetingrooms/find

Method

POST

Request body

Json object with field & value pair.


Allowed field names:

filters

List of Dynamic filters

offset

Distance between the beginning and the first result to retrieve, used for pagination

limit

Max number of results to return

List of filterable columns

  • name

  • displayName

  • number

  • userPin


Example

Query:

curl -XPOST -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/2.0/meetingrooms/find' \
  -d '
    {
      "filters":[
        {"field":"name", "operator":"=", "value":"myConfRoom1conf", "order": "ASC"}
      ],
      "offset":0,
      "limit":100
    }'

Response:

{
 "total":1,
 "list":[
    {
      "id":1,
      "name":"myConfRoom1",
      "displayName":"My Conf Room 1",
      "number":1050,
      "userPin":1234
    }
 ]
}

Get Xivo Users With contact informations

This API allows to get Xivo Users with contact informations

Description:

URL

/api/2.0/users/ascontact

Method

GET


Example

Query:

curl -XGET -H "Content-Type: application/json" -H "Accept: application/json" \
     -H "X-Auth-Token: ${PLAY_AUTH_TOKEN}" 'http://localhost:9100/configmgt/api/2.0/users/ascontact'

Response:

[
   {
      "firstname":"toto",
      "lastname":"user",
      "email":"t.user@xivo.solutions",
      "mobilephoneNumber":"1000",
      "internalphonenumber":"9999",
      "labels":[
        "red",
        "green",
        "blue"
      ],
      "externalphonenumber":"2000"
   },
   {
     "firstname":"Albert",
      "lastname":"Einstein",
      "email":"a.einstein@xivo.solutions",
      "mobilephoneNumber":"2012",
      "internalphonenumber":"2019",
      "labels":[
        "green",
        "yellow"
      ],
      "externalphonenumber":"0007"
   }
]