OXO Connect REST API (1.1.4)

Download OpenAPI specification:Download

The OXO platform offers REST APIs to make it easier doing administrative and provisioning tasks.

List of OXO REST APIs:
• Authentication API, to manage user login and logout,
• Audio file API, to manage audio files for Music On Hold and Preannouncement Messages.

For being able to use these APIs, you need first to authenticate to OXO.
Authentication to OXO is done by calling the authentication API api/oxo/authentication/v1.0/login.
This API will try to authenticate you, and in case of success will return a JSON Web Token that is mandatory for calling other APIs, like audio file.

Authentication

Basic

Basic authentication used for login.
The following syntax must be used in the "Authorization" header:
"Basic <base64encode(userLogin:userPassword)>"

Security Scheme Type	HTTP
HTTP Authorization Scheme	basic

JWT

For accessing all API except login a valid JSON Web Token (JWT) must be passed in the "Authorization" header. A valid JWT is generated by the API and returned as answer of a call to the GET /api/oxo/authentication/v1.0/login giving a valid user & password.
The following syntax must be used in the "Authorization" header:
"Bearer xxxxxx.yyyyyyy.zzzzzz"

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer
Bearer format	"JWT"

Authentication API

To authenticate, you need to use one of below account:

the OXO operator account and password,
the OXO administrator account and password,
the OXO installer account and password.

In return, you will receive a valid JSON Web Token (JWT) to use for all other API calls.

JWT description

A JWT consist of three parts, each part is base 64 encoded, separated by dots which are:

the header that contains a description of the token (type and signing algorithm),
the payload that contains information about the user and the login,
the signature used to authenticate and verify the token.

Only the payload part should be used by the API client.

The JWT payload part contains the below fields:

user	the login name used to get the token
level	the level of API the user can manage with this token, should be operator or administrator or installer
exp	the expiration time, after this date/time, request containing this token will no more be accepted
iat	issued at, the time when the token was issued
iss	issuer, the identification of the system that issued the JWT
countRenew	the number of time this token has been renewed
maxRenew	the maximum number of times that the token can be renewed

Login user.

This API allows users to login to use complete REST API.
If login is successful, the API returns a JSON Web Token (JWT) which must be provided by clients for all APIs requiring user authentication:

The JWT is valid only for a given time (1 hour).
The JWT is no more valid after a system restart.
The JWT can be renewed a few times using API GET /authentication/v1.0/renew.
The maximum number of renew is given in the JWT payload (fixed to 5), as well as the current number of time the token has been renewed (see below).
Once the JWT expired, or if the maximum of token renew has been reached, user must login again using this API.

Authorizations:

Basic

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0,
"data": {"token_type": "Bearer",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
}

Logout user.

This API allows users to logout.
Remark: Current JWT is disabled on logout, user must login again to continue using this API.

Authorizations:

JWT

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Renew user JWT.

This API allows users to renew their JSON Web Token (JWT), thus extending the expiration date of their current JWT.
This API requires user to be authenticated with the latest generated JWT to maintain the renew counter.
If so, a new JWT is returned, with the expiration date starting from now and an incremented renew counter.

Warning: The JWT can only be renewed a given number of times, after this user must login again to get a new token using API GET /api/authentication/v1.0/login.
The maximum number of renew is given in the JWT, as well as the current number of time the token has been renewed.

Authorizations:

JWT

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0,
"data": {"token_type": "Bearer",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
}

MOH audio file API

Music On-Hold allows audio file to be played to external callers while their call is put on hold.
The music can be sourced from:
• The default music provided with the system or from an external audio source (tape player connected to the system).
Note: tape source is not available on OXO connect Evolution.
• A customized external audio wave files stored in the system.
The MOH feature works conjointly with the entities feature. The entities feature allows the configuration of several (up to four) entities or groups of phones.
To one entity (containing several phone sets) is associated one customized MOH audio file.

The system can store up to 4 MOH audio files, one for each entity.

API described herein is used to manage the customized external audio wave files.

Upload a MOH audio file.

This API can be used to update / upload a new MOH audio file.
After upload the new MOH is automatically activated on OXO Connect unless the system is configured to use the tape input.

The source file for a MOH resource must satisfy one of the following audio encoding requirements:

Encoding type	Bits per sample	sample frequency	Channels
Linear PCM (on OXO Connect)	8	8 kHz	Single (mono)
Linear PCM (on OXO Connect Evolution)	8/16	8-16 kHz	Single (mono)
CCITT a-law encoded PCM (G711)	8	8 kHz	Single (mono)
CCITT µ-law encoded PCM (G711)	8	8 kHz	Single (mono)
ADPCM (G726) only on OXO Connect	4	8 kHz	Single (mono)

The maximum duration of a MOH audio resource is 600 seconds.
A request to transfer an audio file to the system will be refused if this limit is exceeded.
A request to transfer an unsupported audio file format will be refused with an error message.

Authorizations:

JWT

path Parameters

id

required

integer [ 1 .. 4 ]

Entity ID to update.

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Request Body schema: audio/x-wav

string <binary> (AudioFile)

Audio file content.

Responses

Request samples

Payload

Content type

audio/x-wav

RIFF....wavefmt ... ...data... wav audio file content

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Download a MOH audio file.

This API can be used to download a MOH audio file.

Remark: the file is retrieved in stored system format.

System	Encoding type	Bits per sample	sample frequency	Channels
OXO Connect	ADPCM (G726)	4	8 kHz	Single (mono)
OXO Connect Evolution	Linear PCM	8/16	8/16 kHz	Single (mono)

Authorizations:

JWT

path Parameters

id

required

integer [ 1 .. 4 ]

Entity ID to update.

header Parameters

Accept

required

string

Default: audio/x-wav

Accept the result in wav format.

Responses

Response samples

Content type

audio/x-wav

RIFF....wavefmt ... ...data... wav audio file content

Delete a MOH audio file.

This API can be used to delete a MOH audio file.
After delete the OXO Connect automatically uses the default system MOH.

Authorizations:

JWT

path Parameters

id

required

integer [ 1 .. 4 ]

Entity ID to update.

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Pre-announcement audio file API

A pre-announcement message can be played to an external caller before their call is answered (either before the phone starts ringing or while it is ringing), as a company welcome message, for example.

Such a message can be externally recorded in a (.wav) audio file and downloaded to the system.

The system can store up to 20 pre-announcement messages, the maximum number is depending on the license.
A request to upload an audio file to the system will be refused if this limit is exceeded.

API described herein is used to manage the customized external audio wave files.

Remark: This API is not developed to manage any configuration regarding pre-announcement, it only allows to manage the audio file.
To use it you have first to configure the OXO system in term of pre-announcement, using OMC to configure the system time ranges, to put some messages file on OXO and to configure the pre-announcement for the time ranges.
Then the REST API can be used to replace/delete existing audio files.

Upload a pre-announcement audio file.

This API can be used to update / upload a new pre-announcement audio file.

The source file for a pre-announcement resource must satisfy one of the following audio encoding requirements:

Encoding type	Bits per sample	sample frequency	Channels
Linear PCM	8/16	8-16 kHz	Single (mono)
CCITT a-law encoded PCM (G711)	8	8 kHz	Single (mono)
CCITT µ-law encoded PCM (G711)	8	8 kHz	Single (mono)

The maximum duration of the pre-announcement resources are pooled and the total length of all the resources must not exceed 20 x 16 seconds = 320 seconds (which depends on your license).
A request to transfer an audio file to the system will be refused if this limit is exceeded.
A request to transfer an unsupported audio file format will be refused with an error message.

Authorizations:

JWT

path Parameters

id

required

integer [ 1 .. 20 ]

Pre-announcement ID to update.

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Request Body schema: audio/x-wav

string <binary> (AudioFile)

Audio file content.

Responses

Request samples

Payload

Content type

audio/x-wav

RIFF....wavefmt ... ...data... wav audio file content

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Download a pre-announcement audio file.

This API can be used to download a pre-announcement audio file.

Remark: the file is retrieved in stored system format.

System	Encoding type	Bits per sample	sample frequency	Channels
OXO Connect	CCITT a/µ-law encoded PCM (G711)	8	8 kHz	Single (mono)
OXO Connect Evolution	Linear PCM	8/16	8/16 kHz	Single (mono)

Authorizations:

JWT

path Parameters

id

required

integer [ 1 .. 20 ]

Pre-announcement ID to update.

header Parameters

Accept

required

string

Default: audio/x-wav

Accept the result in wav format.

Responses

Response samples

Content type

audio/x-wav

RIFF....wavefmt ... ...data... wav audio file content

Delete a pre-announcement audio file.

This API can be used to delete a pre-announcement audio file.

Authorizations:

JWT

path Parameters

id

required

integer [ 1 .. 20 ]

Pre-announcement ID to update.

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Automated Attendant audio file API

Two welcome messages can be played by the automated attendant,
one in normal mode during opening hours
and one in restricted mode during closing hours,
and a goodbye message can also be played.

These messages can be externally recorded in a (.wav) audio file and downloaded to the system.

API described herein is used to manage the customized external audio wave files.

Remark: This API is not developed to manage any configuration regarding automated attendant, it only allows to manage the audio file.
To use it you have first to configure the OXO system in term of automated attendant, using OMC to configure the system, to put some audio file on OXO and to configure the automated attendant".
Then the REST API can be used to replace/delete existing audio files.

Attention: API currently not available on OXO 3.2.

Upload an automated attendant audio file.

This API can be used to update / upload a new automated attendant audio file.

The source file for a automated attendant resource must satisfy one of the following audio encoding requirements:

Encoding type	Bits per sample	sample frequency	Channels
Linear PCM	8/16	8-16 kHz	Single (mono)
CCITT a-law encoded PCM (G711)	8	8 kHz	Single (mono)
CCITT µ-law encoded PCM (G711)	8	8 kHz	Single (mono)

The maximum duration of the automated attendant greeting message is 120 seconds.
The maximum duration of the automated attendant goodbye message is 20 seconds.
A request to transfer an audio file to the system will be refused if this limit is exceeded.
A request to transfer an unsupported audio file format will be refused with an error message.

Authorizations:

JWT

path Parameters

id

required

string

Enum: "normal" "restricted" "goodbye"

Automated attendant ID to update:

normal = normal mode welcome audio file,
restricted = restricted mode welcome audio file,
goodbye = goodbye audio file.

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Request Body schema: audio/x-wav

string <binary> (AudioFile)

Audio file content.

Responses

Request samples

Payload

Content type

audio/x-wav

RIFF....wavefmt ... ...data... wav audio file content

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Download an automated attendant audio file.

This API can be used to download a Automated attendant audio file.

Remark: the file is retrieved in stored system format.

System	Encoding type	Bits per sample	sample frequency	Channels
OXO Connect	CCITT a/µ-law encoded PCM (G711)	8	8 kHz	Single (mono)
OXO Connect Evolution	Linear PCM	8/16	8/16 kHz	Single (mono)

Authorizations:

JWT

path Parameters

id

required

string

Enum: "normal" "restricted" "goodbye"

Automated attendant ID to update:

normal = normal mode welcome audio file,
restricted = restricted mode welcome audio file,
goodbye = goodbye audio file.

header Parameters

Accept

required

string

Default: audio/x-wav

Accept the result in wav format.

Responses

Response samples

Content type

audio/x-wav

RIFF....wavefmt ... ...data... wav audio file content

Delete an automated attendant audio file.

This API can be used to delete a Automated attendant audio file.

Authorizations:

JWT

path Parameters

id

required

string

Enum: "normal" "restricted" "goodbye"

Automated attendant ID to update:

normal = normal mode welcome audio file,
restricted = restricted mode welcome audio file,
goodbye = goodbye audio file.

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Time ranges API

The time ranges are used to configure the system normal or restricted mode for each days of a week, and for public holidays. This API is used to define time ranges related to operation of the system, a maximum of 7 time ranges can be assigned to each day of the week and to public holidays. The following must be specified for each time range:

an operating mode: normal or restricted,
an attendant group (attendant group 1 to 8),
whether diversion of all internal and external calls for the active attendant group is enabled or not (defined by a collective speed dialing number or by an internal recipient).

Attention: API currently not available on OXO 3.2.

Get the time ranges global parameters.

This API can be used to download the global time ranges configuration.

Authorizations:

JWT

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

200
401
404
405
500

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0,
"data": {"AttendantCallDiversionManualRestrictedMode": "500",
"AttendantCallDiversionAutomatic": "501",
"DefaultAttendantGroup": 7,
"AttendantDiversionEnabled": true
}
}

Update the time ranges global parameters.

This API can be used to update / upload the global time ranges configuration.

Authorizations:

JWT

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Request Body schema: application/json

AttendantCallDiversionManualRestrictedMode	string (AttendantCallDiversionManual) This field defines the destination of the diversion of active attendant group calls when the system is manually switched to restricted mode. This destination is unique irrespective of the time of the manual switch to restricted mode. If this field is empty, the calls of an active attendant group are diverted to the default attendant group when the system is manually switched to restricted mode. This field contains the directory number of the diversion destination.
AttendantCallDiversionAutomatic	string (AttendantCallDiversionAutomatic) This field defines the destination when diverting an active attendant group to a time range. Diversion must be authorized in the field AttendantDiversion. This destination is common to all time ranges in which diversion of the calls of the attendant group has been authorized. This field contains the directory number of the diversion destination.
DefaultAttendantGroup	integer (AttendantGroup) [ 0 .. 7 ] Default: 0 This field is used to choose the attendant group that will reply to the calls over a time range (or active attendant group). The same group can be assigned to several time ranges.

Responses

Request samples

Payload

Content type

application/json

{"AttendantCallDiversionManualRestrictedMode": "500",
"AttendantCallDiversionAutomatic": "501",
"DefaultAttendantGroup": 7
}

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Get all time ranges id.

This API can be used to download the list of existing time ranges id.

Authorizations:

JWT

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

200
401
404
405
500

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0,
"data": {"Days": [{"Id": 0,
"Label": "Monday"
},
{"Id": 1,
"Label": "Tuesday"
},
{"Id": 2,
"Label": "Wednesday"
},
{"Id": 3,
"Label": "Thursday"
},
{"Id": 4,
"Label": "Friday"
},
{"Id": 5,
"Label": "Saturday"
},
{"Id": 6,
"Label": "Sunday"
},
{"Id": 7,
"Label": "Holidays"
}
]
}
}

Delete all time ranges.

This API can be used to delete all the time ranges on system.

Authorizations:

JWT

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

200
401
404
405
500

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Get the time ranges for one day.

This API can be used to download the time ranges for one day.

Authorizations:

JWT

path Parameters

dayid

required

integer [ 0 .. 7 ]

Day ID to update.
Each dayid corresponds to one day, with:

0 for Monday,
1 for Tuesday,
...
6 for Sunday
7 for Public Holidays

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0,
"data": {"TimeRanges": [{"Index": 0,
"Hour": "08:00",
"CallDistribution": 0,
"AttendantGroup": 0,
"AttendantDiversion": false
},
{"Index": 1,
"Hour": "20:00",
"CallDistribution": 0,
"AttendantGroup": 1,
"AttendantDiversion": true
}
]
}
}

Update the time ranges for one day.

This API can be used to update / upload the time ranges for one day.
Remark: the ranges must be ordered by increasing hour.

Authorizations:

JWT

path Parameters

dayid

required

integer [ 0 .. 7 ]

Day ID to update.
Each dayid corresponds to one day, with:

0 for Monday,
1 for Tuesday,
...
6 for Sunday
7 for Public Holidays

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Request Body schema: application/json

required

Array of objects [ 1 .. 7 ] items

Time ranges for one day, maximum 7.

Responses

Request samples

Payload

Content type

application/json

{"TimeRanges": [{"Hour": "08:00",
"CallDistribution": 0,
"AttendantGroup": 0,
"AttendantDiversion": false
},
{"Hour": "12:00",
"CallDistribution": 0,
"AttendantGroup": 1,
"AttendantDiversion": true
},
{"Hour": "14:00",
"CallDistribution": 0,
"AttendantGroup": 0,
"AttendantDiversion": false
},
{"Hour": "20:00",
"CallDistribution": 0,
"AttendantGroup": 1,
"AttendantDiversion": false
}
]
}

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Delete the time ranges for one day.

This API can be used to delete the time ranges for one day.

Authorizations:

JWT

path Parameters

dayid

required

integer [ 0 .. 7 ]

Day ID to update.
Each dayid corresponds to one day, with:

0 for Monday,
1 for Tuesday,
...
6 for Sunday
7 for Public Holidays

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Pre-announcement API

The pre-announcement is used to configure the messages broadcast to callers for incoming calls.
It is possible to configure these messages so that they are broadcast before the call is received (before the handset rings) or during the call (while the handset rings).
Handsets can be configured individually and/or as a group for each day of the week and for different time slots, as defined in time ranges.

API described herein is used to manage the pre-announcement.

Attention: API currently not available on OXO 3.2.

Get the pre-announcement global parameters.

This API can be used to download the global pre-announcement configuration.

Authorizations:

JWT

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

200
401
404
405
500

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0,
"data": {"MessageVoiceGuidanceForDiversionToExternal": 255,
"TimerAutoRealeaseAfterPreannouncementNormalMode": 2400,
"TimerAutoRealeaseAfterPreannouncementRestrictedMode": 600,
"TimerBeforePreannouncement": 80
}
}

Update the pre-announcement global parameters.

This API can be used to update / upload the global pre-announcement configuration.

Authorizations:

JWT

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Request Body schema: application/json

MessageVoiceGuidanceForDiversionToExternal	integer (MessageVoiceGuidanceForDiversionToExternal) [ 0 .. 255 ] Default: 255 Configure the pre-announcement message for a handset with call forwarding set up: 0 for MSG1 to 19 for MSG20 255 for no message.
TimerAutoRealeaseAfterPreannouncementNormalMode	integer (TimerAutoRealeaseAfterPreannouncementNormalMode) [ 0 .. 65535 ] Default: 2400 Define the time before the call is automatically released by system after pre-announcement in normal mode. Value is given in 1/10 of a second.
TimerAutoRealeaseAfterPreannouncementRestrictedMode	integer (TimerAutoRealeaseAfterPreannouncementRestrictedMode) [ 0 .. 65535 ] Default: 600 Define the time before the call is automatically released by system after pre-announcement in restricted mode. Value is given in 1/10 of a second.
TimerBeforePreannouncement	integer (TimerBeforePreannouncement) [ 0 .. 65535 ] Default: 80 Define the time before activation of the pre-announcement. Value is given in 1/10 of a second.

Responses

Request samples

Payload

Content type

application/json

{"MessageVoiceGuidanceForDiversionToExternal": 16,
"TimerAutoRealeaseAfterPreannouncementNormalMode": 2400,
"TimerAutoRealeaseAfterPreannouncementRestrictedMode": 600,
"TimerBeforePreannouncement": 80
}

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Get pre-announcement list.

This API can be used to download the list of pre-announcement configured.
The response contains the list of DDI for which a pre-annoucement configuration exist.

Authorizations:

JWT

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

200
401
404
405
500

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0,
"data": {"preannouncementList": [{"Id": "0",
"Edn": "",
"Name": ""
},
{"Id": "1104",
"Edn": "104",
"Name": "Martin"
}
]
}
}

Create a pre-announcement configuration.

This API can be used to create a pre-announcement configuration for one DDI.
If you want to configure only some days you have to send empty day objects to skip days without specific configuration.

Authorizations:

JWT

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Request Body schema: application/json

DdiNumber	string DDI number to configure, "0" for system global pre-announcement.
	Array of objects [ 1 .. 8 ] items Pre-announcement configuration for one day. The objet order in the array defines the day: first object for Monday, second object for Tuesday, ... sixth object for Sunday seventh object for Public Holidays
ActivatedRestrictedMode	boolean (ActivatedRestrictedMode) Configure of a special behavior on manually activate restricted or normal mode from a handset. If the mode is activated manually and this mode is activated, it is possible to hear the message selected when a handset of the PCX is called: false = restricted mode not activated. true = restricted mode activated.
RestrictedMode	integer (Mode) [ 0 .. 3 ] Pre-annoucement mode: 0 = no messages selected, 2 = Before Call Distribution means that the message will be broadcast before the telephone rings. 3 = During Call Distribution means that the message will be broadcast while the telephone is ringing.
RestrictedMessage	integer (Message) [ 0 .. 19 ] Configure the pre-announcement message: 0 for MSG1 to 19 for MSG20.
RestrictedOnlyIfBusy	boolean (OnlyIfBusy) Behavior on busy call: false = the message will always be broadcast (whether the handset is busy or not). true = the message will only be broadcast if the handset is busy. If the handset is not busy, no message is broadcast.

Responses

Request samples

Payload

Content type

application/json

{"DdiNumber": "1103",
"Days": [{"Timeranges": null
},
{"TimeRanges": [{"Mode": 2,
"Message": 1,
"OnlyIfBusy": false
},
{"Mode": 3,
"Message": 3,
"OnlyIfBusy": true
}
]
},
{"TimeRanges": [{"Mode": 2,
"Message": 1,
"OnlyIfBusy": false
},
{"Mode": 3,
"Message": 3,
"OnlyIfBusy": true
}
]
}
],
"ActivatedRestritedMode": true,
"RestritedMode": 3,
"RestritedMessage": 19,
"RestritedOnlyIfBusy": true
}

Response samples

Content type

application/json

{"httpCode": 201,
"httpMessage": "Created",
"status": "success",
"code": 0,
"data": {"Id": "1103"
}
}

Delete complete pre-announcement configuration.

This API can be used to delete all the pre-announcement configuration.

Authorizations:

JWT

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

200
401
404
405
500

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Get the pre-announcement configuration for one DDI.

This API can be used to download a pre-announcement configuration for one DDI.
The full configuration is returned, including the height days and the seven time ranges for each days.

Authorizations:

JWT

path Parameters

id

required

string

DDI number for which the pre-announcement must be updated.
"0" to use for system global pre-announcement.

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0,
"data": {"DdiNumber": "1103",
"Days": [{"Index": 0,
"TimeRanges": [{"Index": 0,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 1,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 2,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 3,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 4,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 5,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 6,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
}
]
},
{"Index": 1,
"TimeRanges": [{"Index": 0,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 1,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 2,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 3,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 4,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 5,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 6,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
}
]
},
{"Index": 2,
"TimeRanges": [{"Index": 0,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 1,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 2,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 3,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 4,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 5,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 6,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
}
]
},
{"Index": 3,
"TimeRanges": [{"Index": 0,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 1,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 2,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 3,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 4,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 5,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 6,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
}
]
},
{"Index": 4,
"TimeRanges": [{"Index": 0,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 1,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 2,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 3,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 4,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 5,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 6,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
}
]
},
{"Index": 5,
"TimeRanges": [{"Index": 0,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 1,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 2,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 3,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 4,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 5,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 6,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
}
]
},
{"Index": 6,
"TimeRanges": [{"Index": 0,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 1,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 2,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 3,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 4,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 5,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 6,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
}
]
},
{"Index": 7,
"TimeRanges": [{"Index": 0,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 1,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 2,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 3,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 4,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 5,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Index": 6,
"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
}
]
}
],
"ActivatedRestrictedMode": true,
"RestrictedMode": 3,
"RestrictedMessage": 19,
"RestrictedOnlyIfBusy": true
}
}

Update the pre-announcement configuration for one DDI.

This API can be used to update / upload a pre-announcement configuration for one DDI.
To modify an entry in the current configuration, it is recommended to read the configuration, modify it, then rewrite it on the system.
If you want to only modify one day you have to send empty day objects to skip unchanged days.

Authorizations:

JWT

path Parameters

id

required

string

DDI number for which the pre-announcement must be updated.
"0" to use for system global pre-announcement.

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Request Body schema: application/json

DdiNumber	string DDI number to configure, "0" for system global pre-announcement.
	Array of objects [ 1 .. 8 ] items Pre-announcement configuration for one day. The objet order in the array defines the day: first object for Monday, second object for Tuesday, ... sixth object for Sunday seventh object for Public Holidays
ActivatedRestrictedMode	boolean (ActivatedRestrictedMode) Configure of a special behavior on manually activate restricted or normal mode from a handset. If the mode is activated manually and this mode is activated, it is possible to hear the message selected when a handset of the PCX is called: false = restricted mode not activated. true = restricted mode activated.
RestrictedMode	integer (Mode) [ 0 .. 3 ] Pre-annoucement mode: 0 = no messages selected, 2 = Before Call Distribution means that the message will be broadcast before the telephone rings. 3 = During Call Distribution means that the message will be broadcast while the telephone is ringing.
RestrictedMessage	integer (Message) [ 0 .. 19 ] Configure the pre-announcement message: 0 for MSG1 to 19 for MSG20.
RestrictedOnlyIfBusy	boolean (OnlyIfBusy) Behavior on busy call: false = the message will always be broadcast (whether the handset is busy or not). true = the message will only be broadcast if the handset is busy. If the handset is not busy, no message is broadcast.

Responses

Request samples

Payload

Content type

application/json

{"DdiNumber": "1103",
"Days": [{"TimeRanges": [{"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Mode": 0,
"Message": 1,
"OnlyIfBusy": false
},
{"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
}
]
},
{"TimeRanges": [{"Mode": 0,
"Message": 0,
"OnlyIfBusy": false
},
{"Mode": 0,
"Message": 2,
"OnlyIfBusy": false
}
]
}
],
"ActivatedRestrictedMode": true,
"RestrictedMode": 3,
"RestrictedMessage": 19,
"RestrictedOnlyIfBusy": true
}

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Delete the pre-announcement configuration for one DDI.

This API can be used to delete the pre-announcement configuration for one DDI.

Authorizations:

JWT

path Parameters

id

required

string

DDI number for which the pre-announcement must be updated.
"0" to use for system global pre-announcement.

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Public holidays API

This API is used to program public holidays by defining the day, the month and the year.
These days have a specific behavior regarding time ranges and pre-announcement.
A maximum of twenty public holidays can be defined on system.

Attention: API currently not available on OXO 3.2.

Get all public holidays.

This API can be used to download the list of configured public holidays.

Authorizations:

JWT

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

200
401
404
405
500

Content type

application/json

Example

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0,
"data": {"PublicHolidays": [null
]
}
}

Update the public holidays.

This API can be used to update the public holidays list on system.
The sent list replaces the current list on the system.
To modify an entry in the current list, it is recommended to read the list, modify it, then rewrite it on the system.

Authorizations:

JWT

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Request Body schema: application/json

PublicHolidays

required

Array of strings [ 0 .. 20 ] items

Public holiday date using format dd/mm/yyyy with:
- dd for the day, from 01 to 31,
- mm for the month, from 01 to 12,
- yyyy for the year. Without /yyyy the day is managed for every year.

Responses

Request samples

Payload

Content type

application/json

{"PublicHolidays": ["01/02",
"08/05/2020"
]
}

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Delete all public holidays.

This API can be used to delete all the public holidays.

Authorizations:

JWT

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

200
401
404
405
500

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Normal / restricted mode API

This API is used to change the entire system from the normal operating mode to the restricted operating mode.

Attention: API currently not available on OXO 3.2.

Get the normal / restricted mode.

This API can be used to download the current normal / restricted mode.

Authorizations:

JWT

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Responses

Response samples

200
401
404
405
500

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0,
"data": {"RestrictedMode": false
}
}

Update the normal / restricted mode.

This API can be used to configure the normal / restricted mode.

Authorizations:

JWT

header Parameters

Accept

required

string

Default: application/json

Accept the result in JSON format.

Request Body schema: application/json

RestrictedMode

required

boolean

Mode:

false normal mode,
true restricted mode.

Responses

Request samples

Payload

Content type

application/json

{"RestrictededMode": true
}

Response samples

Content type

application/json

{"httpCode": 200,
"httpMessage": "OK",
"status": "success",
"code": 0
}

Errors handling

Error response

In case of login authentication error, only an html page is returned by system.

 <html><head><title>Authentication required</title></head> 
 <body><h1>Please authenticate to access this zone</h1></body></html>

All other API errors output are returned as a JSon with the following fields:

{ 
   "httpCode": xxx,            HTTP result code (20x, 40x, 50x) 
   "httpMessage": "HTTP result message", 
   "status": "request state", 
     • success if request is managed without problem, 
     • error in case or request error, 
     • fail in case of server problem. 
   "code": xxx,                API error code 
   "details": { 
     "message": "API error message", 
      "param": "field name in error", 
      "value": field value in error 
}

HTTP result code list

The following array list the HTTP result code and message.

HTTP code	HTTP message	Description
200	OK	The request succeeded
201	Created	A POST method successfully created a resource.
204	No Content	The server successfully executed the method but returns no response body. Response of DELETE command.
400	Bad Request	Request is not well-formed, syntactically incorrect, or violates schema. Indicates one of these conditions: - The API cannot convert the payload data to the underlying data type. - The data is not in the expected data format. - A required field is not available. - A simple data validation error occurred.
401	Unauthorized	Authentication failed due to invalid authentication credentials.
403	Forbidden	Authorization failed due to insufficient permissions. The client is not authorized to access this resource although it might have valid credentials.
404	Not found	The specified resource does not exist. The server did not find anything that matches the request URI. Either the URI is incorrect or the resource is not available. For example, no data exists in the database at that key.
405	Method not allowed	The server does not support the requested HTTP method. For example, PATCH.
406	Not acceptable	The server does not implement the media type that would be acceptable to the client.
409	Conflict	The request could not be processed because of conflict in the current state of the resource, such as an edit conflict between multiple simultaneous updates.
422	Unprocessable Entity	The request was well-formed but was unable to be followed due to semantic errors.
500	Internal Server Error	A system or application error occurred. Although the client appears to provide a correct request, something unexpected occurred on the server.
503	Service Unavailable	The server cannot handle the request for a service due to temporary maintenance.
507	Insufficient Storage	The server is unable to store the representation needed to complete the request.

REST API error code list

The following array list the REST API error code and message.

API code	API message	Description
1	Unknown error Wave.cgi start problem Wave.cgi problem: No error code send by cgi Encountered EOF while looking for the POST mark Encountered EOF while changing group (data missing) Encountered EOF prematurely (data missing) Encountered EOF while searching a key (string) in the data Error, group of filename is already passed (internal error) Error in WAVE main Error, the posted WAV file name cannot be retrieved POST mark is too long Error, file is locked Error, cannot lock file Error, memory allocation failed Error, cannot remove file Error, cannot open or write to stdout Error, cannot read file contents Wbm start problem Wbm process problem Wbm process without response file Wbm problem: No http code send by wbm Unhandled exception: Unhandled Exception message Access Forbidden: Nox request not authorized	Internal server error.
2	Invalid command Missing resource identifier in URL Error, file missing Unknown feature Unknown API operation	Invalid command error.
3	Missing parameter	Missing parameter error.
4	Value out of the specified range [...] Invalid argument: Maximum number of retry reached The file send is not a WAV file WAV file name is too long WAV size is too long Bad WAV format Bad id number Malformed Hour error : expected hh:mm Malformed Date error : expected dd/mm/yyyy or dd/mm Voice messages are between 0 to 19 or 255 for no message Time ranges must be provided sorted in ascending order of hours Error on time range mode. Possible values : 0 - 2 – 3	Invalid parameter error.
5	Insufficient free space in the storage	Insufficient storage error.
6	Resource not found Entry not found in system Resource with identifier xxxx not found	Resource not found.
7	Entry already present in system Duplicated entry: xxxx The target date is already present in system	Resource already existing.
8	Request method not supported Method not supported	Method not alllowed on this resource.
9	Authentication failed: Expired token Authentication failed: Signature verification failed Authentication failed, missing parameter Authentication failed, invalid argument: Key may not be empty Authentication failed, token not yet valid: Cannot handle token prior to ‘nbf’ Authentication failed, token not yet valid: Cannot handle token prior to ‘iat’ Authentication failed, unexpected value: Wrong number of segments Authentication failed, unexpected value: Invalid header encoding Authentication failed, unexpected value: Invalid claims encoding Authentication failed, unexpected value: Invalid signature encoding Authentication failed, unexpected value: Empty algorithm Authentication failed, unexpected value: Algorithm not supported Authentication failed, unexpected value: Algorithm not allowed Authentication failed, unexpected value: “Kid” invalid, unable to lookup correct key Authentication failed, unexpected value: “Kid” empty, unable to lookup correct key Authentication failed, domain error: Algorithm not supported Authentication failed, domain error: OpenSSL unable to sign data Authentication failed, domain error: OpenSSL error: xxxxx Authentication failed, domain error: Null result with non-null input Authentication failed, domain error: Maximum stack depth exceeded Authentication failed, domain error: Invalid or malformed JSON Authentication failed, domain error: Unexpected control character found Authentication failed, domain error: Syntax error, malformed JSON Authentication failed, domain error: Malformed UTF-8 characters	Authentication problem.
10	Access forbidden	Authorization failed due to insufficient permissions.
11	DHCP lease file read error Restore in progress	Service Unavailable.