Introduction

Presentation

----------------------------------------------------------------------------

Overview

First of all, if necessary, ALE can offer you a quote for a Mentoring Service Pack
which will help you with O2G deployment and the use of O2G APIs with the support of dedicated ALE experts.
Contact your ALE representative for more details.

This feature is only accessible by an O2G administrator.
(For some use cases, it is still possible to authenticate as a user to use some available methods,
but which are not recording methods).

This package is not embedded in OXE, and it is able to address the installed OXE(s).
This configuration is exclusively dedicated to the RECORDING feature, all types of OXE subscriber will be considered (including ANALOG).
In the opposite of the main O2G "All Services" configuration, each device to be recorded MUST be first monitored on demand on the right link.
Each device asked to be monitored is dynamically created in the O2G cache and is associated to a user.
Each resource can be accessed through the following kind of URL:
http(s)://<host>:<port>/api/rest/<version>/<resource _name>
Where:

<host> is the host name or IP address of the server
<port> is the port of the server
<version> is the resource version
<resource_name> is the name of the invoked resources

Third party application can get available API versions by performing a GET http request on the root URL
(Only GET operation is available on this resource, else 405 HTTP error "Method Not Allowed" in returned)
The structure of the returned body can be found in RoxeRestApiDescriptor.
http(s)://<host>:<port>/api/rest

Example of response :

{
	"serverInfo": {	
		"productName": "O2G Solution",
		"productType": "O2G",
		"productVersion": {
			"major": "2.7",
			"minor": "001.000"
			},
		"haMode": true	
		},
	"versions" : [{
		"id" : "1.0",
		"status" : "CURRENT",
		"publicUrl" : "https://public-server/api/rest/authenticate?version=1.0",
		"internalUrl" : "https://server/api/rest/authenticate?version=1.0"
		}]
}

Vocabulary

An application :

An application is a third party using the O2G system.
An application can create one or more O2G administrator sessions to interact with all users.
It can also have one or more O2G user sessions.

An installer :

The person who administers the O2G system.
This person will be able to manage the O2G system, by connecting via an SSH link, using the roxeAdm account with the credentials configured during installation.

An administrator :

It is an O2G user with administrator right.
The installer can create an administrator in O2G system, using the roxe-config.sh tool (or roxe-install.sh during installation).

A subscriber :

It is a subscriber of the OXE system.
The installer can manage a subscriber in OXE system, by using MGR tool by example.

A device :

It is a subscriber number of the OXE system or an external number.

A user :

It is an O2G user with no administrator right.
An O2G user is associated with one OXE subscriber, or more in the case of a multi-device OXE configuration.
An O2G user is automatically created by the O2G system if an OXE subscriber has the A4980 right or if OXE subscriber is managed on demand (depending on the O2G configuration).

An administrator account :

A O2G administrator account is a O2G session, associated to a O2G administrator.
To create an O2G administrator account, a third-party application must authenticate and log in (open a session).
A login and a password will be used to authenticate to the REST APIs.
(Method: GET https://server/api/rest/authenticate?version=1.0)
This administrator account will be able to use all REST APIs methods.
The login and password used are those administered in O2G by the installer.

A user account :

A O2G user account is a O2G session, associated to a O2G user.
To create an O2G user account, a third-party application must authenticate and log in (open a session).
A login and a password will be used to authenticate to the REST APIs.
(Method: GET https://server/api/rest/authenticate?version=1.0)
This user account will be able to use only user REST APIs methods.
The login and password used depend on the choice of authentication mechanism, chosen by the installer.
Several authentication mechanisms are possible :

The installer denies user authentication.
In this case, no user can authenticate (no user session).
Only an administrator account must use to perform an action for a user.

The installer authorizes user authentication by O2G.
In this case, the user authentication is checked by O2G (default mode).
It is a basic HTTPS authentication, based on a login/password.
The login is the QMCDU of the OXE subscriber prefixed by "oxe" (Ex: oxe70120).
The password is the Secret Code (4 digits), of the OXE subscriber.

The installer authorizes user authentication by OXE.
This configuration impacts all OXEs managed by O2G :
Each OXE must be configured with a local authentication or
with a LDAP authentication (only possible from OXE version N4.507.2).

For a local authentication :
The login is the Login of the subscriber.
The password is the Password of the subscriber.

For a LDAP authentication :
The login is the Login of the subscriber.
The password is the password of the user defined in the LDAP server.

A loginName :

This attribute is used in many O2G REST API methods.
It corresponds to the QMCDU of the OXE subscriber prefixed by "oxe" (Ex: oxe70120).
This is true regardless of the login used by the authentication mechanism.

History

2.7.4

modified feature 'Authentication'
- added in representation 'AuthenticationResponse' :
  - loginName
  - expired
modified feature 'Session management'
- added in representation 'SessionInfo' :
  - login
- added in representation 'SessionRequest' :
  - timeToLive
modified feature 'Call control'
- added in representation 'CallData' :
  - lastRedirecting

2.7.3

modified feature 'Call control'
- added in representation 'Identifier' :
  - multiLine
modified feature 'Maintenance'
- added in representation 'DRLink' :
  - initiator
- added in representation 'SystemStatus' :
  - recordingStatus
modified feature 'Voice Recording'
- added in representation 'DeviceMonitored' :
  - userDeviceIds
- added in representation 'DRLink' :
  - initiator
- added in representation 'MonitorRequest' :
  - deviceNumbers

2.7.2

modified feature 'Call control'
- added in representation 'DeviceState' :
  - cause
modified feature 'Voice Recording'
- added in representation 'RecordingSrtpKeys' :
  - cipherSuite

2.7.1

modified feature 'Call control'
- added in representation 'CallData' :
  - trunkIdentification

2.7

modified feature 'Session management'
- added in representation 'SessionInfo' :
  - creationDate
  - otherSessions
modified feature 'User information'
- added in representation 'User' :
  - externalLogin
modified feature 'Maintenance'
- added notifications :
  - OnServerStart

Change logs

Complete changes history can be found here.

Authentication mechanism

All resources are protected by the authentication mechanism.
A dedicated resource is provided to perform user/administrator authentication :
http(s)://<host>:<port>/api/rest/authenticate?version=1.0

The first action for an application is to authenticate on O2G.
Authentication is basic HTTPS authentication, based on a login and password.
The first action for an application is to authenticate on O2G.

Authentication for an administrator
Authentication is basic HTTPS authentication, based on a login/password.

The login is managed in the configuration file
The password is managed in the configuration file

The credentials (login and password) are first checked to see if they correspond to an O2G administrator.
JWT authentication is implemented to provide an identifier based on credentials.
This identifier must be passed in a cookie (AlcUserId) in all subsequent HTTPS requests, so that O2G can check their validity.

See below a sequence diagram for a Basic authentication.
No picture

Example:

  Request
	GET http://server/api/rest
  Response :
	200 OK
	Content-Type:  application/json
	{ 
		"versions" : [ {
		"id" : "1.0",
		"status" : "CURRENT",
		"publicUrl" : "https://public-server/api/rest/authenticate?version=1.0",
		"internalUrl" : "https://server/api/rest/authenticate?version=1.0"
		} ] 
	} 
  
  Request :
	GET https://server/api/rest/authenticate?version=1.0
	Authorization: Basic aW50ZXJuYWwyOTphbGNhdGVsMjk=

  Response :
  	200 OK  	
 
  	Set-Cookie: AlcUserId=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJpbnRlcm5...; Path=/
  	Content-Type:  application/json
  	{
   		"credential" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJpbnRlcm5...",
   		"publicUrl" : "https://public-server/api/rest/1.0/sessions",
   		"internalUrl" : "https://server/api/rest/1.0/sessions",
   		"expired" : "false",
   		"login": "oxe1000"
  	}

Authentication for an user : Secure Access
An installer can authorize or deny user authentication.Enable these options through O2G configuration (root account only).
Several options are possible.

An installer denies user authentication.

In this case, no user can authenticate (no user session).
Only an administrator account must use to perform an action for a user.

An installer authorizes user authentication by O2G.

In this case, the user authentication is checked by O2G (default mode).
It is a basic HTTPS authentication, based on a login/password.

The login is the QMCDU of the OXE subscriber prefixed by "oxe" (Ex: oxe70120).
The password is the Secret Code (4 digits), of the OXE subscriber.

See previous a sequence diagram for a Basic authentication.

An installer authorizes user authentication by OXE.

This configuration impacts all OXEs managed by O2G :
Each OXE must be configured with a local authentication or
with a LDAP authentication (only possible from OXE version N4.507.2).

For a local authentication :

The login is the Login of the subscriber.
The password is the Password of the subscriber.

For a LDAP authentication :

The login is the Login of the subscriber.
The password is the password of the user defined in the LDAP server.

Session creation

All services are invoked through a session (user or administrator one).
The resource to perform user/administrator session creation is:
http(s)://<host>:<port>/api/rest/1.0/sessions
The session creation request and all the subsequent requests must contain the Cookie AlcUserId with value equals to the one received in the Set-Cookie of the authentication response.
Important: all the sessions are created with an initial time-to-leave of 1800 seconds (30 minutes): To see how to maintain the session, refer to SESSION MANAGEMENT chapter. Example:

  Request
	POST /api/rest/1.0/sessions HTTP/1.1

Content-Type: application/json
Host: (server address)
Cookie: AlcUserId=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJpbnRlcm5...
...
{
[body] : refer to Session Management section
}

  Response :
	200 OK
	Server: Apache/2.4.23
	Set-Cookie: JSESSIONID=88C00EA2B3C482E19825F1184D0BB50E.tomcat; Path=/api
	Content-Type:  application/json
	{ 
		"timeToLive": 1800,
  		"publicBaseUrl": "http://public-server/api/rest/1.0",
  		"privateBaseUrl": "https://server/api/rest/1.0",
  		"services": [
    		{...

O2G Services Through Websocket

O2G REST service may be used through a websocket. This configuration could be interesting in a context where the security must be improved or if the opening of http ports on the local domain is considerd as an issue.
The solution is to use a reverse HTTP proxy over web socket. The aim is to provide a secure connection setup from the internal network to the external network in order to tunnel the API requests to internal O2G APIs from the external third party client.
A Web Socket agent run in the internal network (in front end of O2G API) establishes a single connection to a remote Web Socket server in secure mode. The Web socket agent is included in the O2G solution and may be configured thanks to the O2G configuration tool.
The web socket server side is not handled by O2G solution and it remains to the client to provide it.
A json formatted message protocol is used in the websocket to translate the http REST requests and responses.
In the same manner, the events the client has subcribed to are sent back by O2G through this socket towards the application. Moreover, an identifier may used as query parameter in the subscription request: in that manner, the events correponding to this susbscription will be automatically sent to the client through the web socket with this identifier (no need to open a chunk channel).
No picture

Here is the Ws protocol map: No picture

Example of request/response for authentication through WS protocol:
No picture

Example of request/response for subscription through WS protocol:
No picture

Example of event through WS protocol:
No picture

Error management

Management of errors returned by REST services invocation follows the common practise which consists of providing as much information as possible to the user.
The returned information structure contains several fields, targetting all possible users of the API: see RestErrorInfo

The complete list of REST API errors is the following:

type	code	helpMessage	canRetry
NOT_READY	1000	The server is not yet available. Please retry later if the initialization is not finished.	true
INVALID_SESSION	1001	No valid session found for the given identifier. Please logout and login with correct credentials.	true
NOT_ALLOWED	1002	The operation is not allowed, because of insufficient rights or bad credential. Please contact the installer to fix the problem.	false
NOT_FOUND	1003	Missing or bad parameter sent by a request on a service. Fix the problem and retry.	true
NOT_EXPECTED	1004	The request can not be performed due to current user's state.Check the state or fix your request before sending it back.	true
NOT_SUPPORTED	1005	This operation is not supported. Please check the documentation.	false
BAD_PARAMETER	1006	Request parameters are not correct. Please fix the problem and send the request back.	true
SERVER_PROBLEM	1007	Server general problem. Please contact the installer to fix the problem.	false

Example 1: The service in charge of executing the invoked request is not installed, or the server is not properly configured.

{
	"httpStatus":"SERVICE_UNAVAILABLE",
	"code":1007,
	"helpMessage":"Server general problem. Please contact the installer to fix the problem.",
	"type":"SERVER_PROBLEM",
	"innerMessage":"AlcChameleonException.PLUGIN_NOT_INSTALLED 'PLUGIN_NAME' plugin is not installed",
	"canRetry":false
}

Example 2: Invalid session. The application has to log out, if previously logged in, and retry to log in.

{
	"httpStatus":"FORBIDDEN",
	"code":1001,
	"helpMessage":"No valid session found for the given identifier. Please logout and login with correct credentials.",
	"type":"INVALID_SESSION",
	"innerMessage":"AlcChameleonException.BAD_FRAMEWORK_SESSION_IDENTIFIER No framework session in API with this ID : ...323437343",
	"canRetry":true
}

Representations

boolean

'boolean' is a data type, having two values (true and false).

HttpStatus

List of all HTTP status.

Value	Description
CONTINUE	100 Continue
SWITCHING_PROTOCOLS	101 Switching Protocols
PROCESSING	102 Processing
OK	200 OK
CREATED	201 Created
ACCEPTED	202 Accepted
NON_AUTHORITATIVE_INFORMATION	203 Non-Authoritative Information
NO_CONTENT	204 No Content
RESET_CONTENT	205 Reset Content
PARTIAL_CONTENT	206 Partial Content
MULTI_STATUS	207 Multi-Status
ALREADY_REPORTED	208 Already Reported
IM_USED	226 IM Used
MULTIPLE_CHOICES	300 Multiple Choices
MOVED_PERMANENTLY	301 Moved Permanently
FOUND	302 Found
MOVED_TEMPORARILY	302 Moved Temporarily
SEE_OTHER	303 See Other
NOT_MODIFIED	304 Not Modified
USE_PROXY	305 Use Proxy
TEMPORARY_REDIRECT	307 Temporary Redirect
BAD_REQUEST	400 Bad Request
UNAUTHORIZED	401 Unauthorized
PAYMENT_REQUIRED	402 Payment Required
FORBIDDEN	403 Forbidden
NOT_FOUND	404 Not Found
METHOD_NOT_ALLOWED	405 Method Not Allowed
NOT_ACCEPTABLE	406 Not Acceptable
PROXY_AUTHENTICATION_REQUIRED	407 Proxy Authentication Required
REQUEST_TIMEOUT	408 Request Timeout
CONFLICT	409 Conflict
GONE	410 Gone
LENGTH_REQUIRED	411 Length Required
PRECONDITION_FAILED	412 Precondition failed
REQUEST_ENTITY_TOO_LARGE	413 Request Entity Too Large
REQUEST_URI_TOO_LONG	414 Request-URI Too Long
UNSUPPORTED_MEDIA_TYPE	415 Unsupported Media Type
REQUESTED_RANGE_NOT_SATISFIABLE	416 Requested Range Not Satisfiable
EXPECTATION_FAILED	417 Expectation Failed
INSUFFICIENT_SPACE_ON_RESOURCE	419 Insufficient Space on Resource
METHOD_FAILURE	420 Method Failure
DESTINATION_LOCKED	421 Destination Locked
UNPROCESSABLE_ENTITY	422 Unprocessable Entity
LOCKED	423 Locked
FAILED_DEPENDENCY	424 Failed Dependency
UPGRADE_REQUIRED	426 Upgrade Required
TOO_MANY_REQUESTS
INTERNAL_SERVER_ERROR	500 Internal Server Error
NOT_IMPLEMENTED	501 Not Implemented
BAD_GATEWAY	502 Bad Gateway
SERVICE_UNAVAILABLE	503 Service Unavailable
GATEWAY_TIMEOUT	504 Gateway Timeout
HTTP_VERSION_NOT_SUPPORTED	505 HTTP Version Not Supported
VARIANT_ALSO_NEGOTIATES	506 Variant Also Negotiates
INSUFFICIENT_STORAGE	507 Insufficient Storage
LOOP_DETECTED	508 Loop Detected
NOT_EXTENDED	510 Not Extended

int

'int' is a 32-bit number (-2147483648 to 2147483647).

ProductVersion

Give information about the version installed on the server.

Name	Type	Cardinality	Description
major	string	[0..1]	Major version of the product. This field should help to identify the release of a product.
minor	string	[0..1]	Minor revision of the product. This field is for internal needs.

[+] : JSON Example

{
   "major": "string",
   "minor": "string"
}

RestErrorInfo

Contains all information from errors sent while invoking REST operations on resources.

Name	Type	Cardinality	Description
httpStatus	HttpStatus	[0..1]	The HTTP status.
code	int	[0..1]	A REST API error code, linked with the above type, to help the user's application to quickly differentiate possible errors.
helpMessage	string	[0..1]	A help message, associated with the above type and code, providing a more detailed cause of the error.
type	string	[0..1]	A REST API error type, which group all possible underlying errors in a finite number of possibilities.
innerMessage	string	[0..1]	This message contains relevant information to help an administrator or support team to find the cause of the problem.
canRetry	boolean	[0..1]	An indication for the developer of the application if the error can be solved by modifying the request, or if it is a problem on server side.

[+] : JSON Example

{
   "httpStatus": "CONTINUE | SWITCHING_PROTOCOLS | PROCESSING | OK | CREATED | ACCEPTED | ...",
   "code": int,
   "helpMessage": "string",
   "type": "string",
   "innerMessage": "string",
   "canRetry": boolean
}

RoxeRestApiDescriptor

High level information of the server and supported REST API versions.

Name	Type	Cardinality	Description
serverInfo	ServerInfo	[0..1]	Provide extra information about the server hosting the REST API.
versions	Version	[1..*]	List of the versions supported on the server.
custoFeatures	string	[0..*]	List of customized feature (informative) added on the server.

[+] : JSON Example

{
   "serverInfo": {
      "productName": "string",
      "productType": "string",
      "productVersion": {
         "major": "string",
         "minor": "string"
      },
      "haMode": boolean
   },
   "versions": [ {
      "id": "string",
      "status": "string",
      "publicUrl": "string",
      "internalUrl": "string"
   } ],
   "custoFeatures": [ "string" ]
}

ServerInfo

Provide information on the server.

Name	Type	Cardinality	Description
productName	string	[1]	Friendly description of the product.
productType	string	[1]	Short name of the product.
productVersion	ProductVersion	[0..1]	Version of the product.
haMode	boolean	[0..1]	Indicate if the server is in High Availability mode.

[+] : JSON Example

{
   "productName": "string",
   "productType": "string",
   "productVersion": {
      "major": "string",
      "minor": "string"
   },
   "haMode": boolean
}

string

'string' represents character strings.

Version

Name	Type	Cardinality	Description
id	string	[1]	Identifier of the version (e.g. '1.0').
status	string	[1]	Status of the given version. 'CURRENT' means this is the latest version on the server.
publicUrl	string	[1]	Authentication URL to use from public (i.e. internet) access.
internalUrl	string	[1]	Authentication URL to use from private (i.e. intranet) access.

[+] : JSON Example

{
   "id": "string",
   "status": "string",
   "publicUrl": "string",
   "internalUrl": "string"
}

Authentication

Presentation

The Authentication service allows a user or an administrator to authenticate on the O2G server. This is a prerequisite to create a session.
All resources are protected by the authentication mechanism.
A dedicated resource is provided to perform user/administrator authentication :
http(s)://<host>:<port>/api/rest/authenticate?version=1.0

The first action for an application is to authenticate on O2G.
Authentication is basic HTTPS authentication, based on a login and password.
The first action for an application is to authenticate on O2G.

Authentication is basic HTTPS authentication, based on a login/password.

Authentication for an administrator

The login is managed in the configuration file
The password is managed in the configuration file

Authentication for an user : Secure Access
An installer can authorize or deny user authentication.Enable these options through O2G configuration (root account only).
Several options are possible.

An installer denies user authentication.

In this case, no user can authenticate (no user session).
Only an administrator account must use to perform an action for a user.

An installer authorizes user authentication by O2G.

In this case, the user authentication is checked by O2G (default mode).
It is a basic HTTPS authentication, based on a login/password.

The login is the QMCDU of the OXE subscriber prefixed by "oxe" (Ex: oxe70120).
The password is the Secret Code (4 digits), of the OXE subscriber.

An installer authorizes user authentication by OXE.

The login is the Login of the subscriber.
The password is the Password of the subscriber.

For a LDAP authentication :

The login is the Login of the subscriber.
The password is the password of the user defined in the LDAP server.

The authentication request response provides two additional parameters :
First parameter is the O2G login for further request
Second parameter is a optional boolean which indicate if the OXE password is expired or not.
If this boolean is true, the password provided must be quickly changed using the proper API request
⚠ An expired password can quickly leads to authentication failure

Note : For OXE LDAP authentication, the login is the Login of the subscriber must be the same of the user defined in the LDAP server.
O2G checks the consistency between the LDAP login and the OXE subscriber login.

JWT authentication is implemented to provide an identifier based on credentials: it is returned in the Set-Cookie header as the AlcUserId:
Set-Cookie: AlcUserId=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJpbnRlcm5...;
This identifier must be passed in a in all subsequent HTTPS requests in the cookie header:
Cookie: AlcUserId=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJpbnRlcm5...;

Resource summary

Resource	Method	Description
/authenticate	GET	Ask request authentication.

Resource

/authenticate

Methods

Ask request authentication.

Licenses

No O2G license required.

Request

query parameters
parameter	type	description
version	string	: This parameter is mandatory and MUST be set with 1.0

Response

code	type	media types	description
200	AuthenticationResponse	application/json	OK
400		application/json	Bad Request
401		application/json	Unauthorized
403		application/json	Forbidden
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : Authentication of a user

Representations

AuthenticationResponse

The authentication response containing credential and URLs to access the Openness REST API.

Name	Type	Cardinality	Description
credential	string	[1]	The token returned by the authentication mechanism.
publicUrl	string	[1]	The public URL of the session resource(to be used in the case a reverse proxy has been set up).
internalUrl	string	[1]	The private URL of the session resource(to be used inside the company).
loginName	string	[0..1]	Since version 2.7.4 The login name needed to be used after authentication for O2G mechanism.
expired	boolean	[0..1]	Since version 2.7.4 The boolean which asses if the password filled for authentication is expired or not.

[+] : JSON Example

{
   "credential": "string",
   "publicUrl": "string",
   "internalUrl": "string",
   "loginName": "string",
   "expired": boolean
}

Associated method :

GET /authenticate

boolean

'boolean' is a data type, having two values (true and false).

string

'string' represents character strings.

Session management

Presentation

The Session service allows a user or an administrator to open a session on the O2G server. This is a prerequisite to any service usage and must happened after the authentication stage.
A session is created with an initial time-to-leave of 30 seconds: this short value is necessary to emulate "connected" application : the application is responsible to keep the session alive by posting /sessions/keepalive request or other requests before each expiration of the timer. The TTL of the session is re-initialized on each request. If the TTL expires, the session is closed by the server.

Resources summary

Resource	Method	Description
/sessions	GET	Gets information of the opened session.
	POST	Open a session for a user or an administrator.
	DELETE	Closes a Session.
/sessions/keepalive	POST	Restarts the session timer.

Resources

/sessions

Methods

Gets information of the opened session.

Licenses

No O2G license required.

Request

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	type	media types	description
200	SessionInfo	application/json	OK
400		application/json	Bad Request
403		application/json	Forbidden
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Open a session for a user or an administrator. This is the first thing to do before invoking any others resources. The user or the administrator session is identified by its authentication cookie. This one must be provided for the session creation request to the server. This authentication key is obtained after a successful authentication (See Authentication mechanism chapter)
A session can be opened only once (same authentication cookie), if the session is already open an error is returned (Forbidden). (With different authentication cookies, one user may open several sessions.
In each case, the obtained reference to the Session must be released using the logout operation (DELETE).
The Session is closed either after the reference has been released (after a call to the DELETE operation) or after the session timer ends.
3 types of Sessions exist:

User Session: The credential (cookie) used to open the session, is the one of a User. In case of success, this credential will be used to identify the Session and the User. This Session allows a User to use any other service.
Administrator Session: The credential (cookie) used to open the session, is the one of a Administrator. In case of success, this credential will be used to identify the Session and the Administrator. This Session allows a Administrator to use any other services.
Supervised Session: This kind of Session is opened thanks to the supervisor operation. This operation uses the credential of a Administrator (with supervisor role) and the identification of a User or another Administrator (login name, phone number or e-mail) to open the Session. In case of success, this credential will be used in all subsequent requests, to identify the Session, and the supervised User or Administrator. After the session opening, a Supervised Session can be used like a User Session or a Administrator Session (described above). In other words, this Session allows a Supervisor to use any other services as if it was opened by the User or Administrator.

Licenses

No O2G license required.

Request

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

body parameter
type	media types	description
SessionRequest	application/json	This element is used to open a Session.

Response

code	type	media types	description
200	SessionInfo	application/json	OK
400		application/json	Bad Request
403		application/json	Forbidden
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : Creation of a user session

[+] : Creation of an administrator session

[+] : Creation of a supervised user session

[+] : Creation of a session with a token

[+] : Creation of an administrator session, 2 other sessions already exist on this user: the result returns the identifiers of each.

Closes a Session.
When the Session is closed (following the call to this operation or due to a session time out),
all license references are released and all services sessions are closed.

Licenses

No O2G license required.

Request

header parameters
parameter	type	description
Authorization	string	For Private use ONLY: Identifier of the daughter Session

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	media types	description
204	application/json	No Content (The session is closed)
400	application/json	Bad Request
403	application/json	Forbidden (The session is already closed)
500	application/json	Internal Server Error (The session doesn't exist)
503	application/json	Service Unavailable

/sessions/keepalive

Methods

Restarts the session timer.
To keep the session open, if there is no request before session timeout.

Each Session is limited in time.
The initial duration of a session is fixed to 30 minutes(1800 secs).
Each time a Session is used(using this method or any one else), the session timer is automatically restarted.

Licenses

No O2G license required.

Request

header parameters
parameter	type	description
Authorization	string	For Private use ONLY: Identifier of the daughter Session

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	type	media types	description
200	SessionTokenInfo	application/json	OK (in case a secure token has been used to create the session)}
204		application/json	No Content (The session timer has been correctly refreshed)
400		application/json	Bad Request
403		application/json	Forbidden (The session doesn't exist)
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : KeepaLive of a session with a token

Representations

boolean

'boolean' is a data type, having two values (true and false).

int

'int' is a 32-bit number (-2147483648 to 2147483647).

Service

This value contains all available information about a local service.

Name	Type	Cardinality	Description
serviceName	string	[1]	This value contains the name of the service.
serviceVersion	string	[0..1]	This value contains the version of the service, which allows an application to check its compatibility with the service.
relativeUrl	string	[1]	This value contains the relative URL of the service, which allows a consumer to access it.

[+] : JSON Example

{
   "serviceName": "string",
   "serviceVersion": "string",
   "relativeUrl": "string"
}

SessionInfo

Session information.

Name	Type	Cardinality	Description
admin	boolean	[0..1]	Indicate if the session has been opened by an administrator.
login	string	[0..1]	Since version 2.7.4 the roxe login of the user.
timeToLive	int	[0..1]	The TTL time-out applied on the Session in seconds.
publicBaseUrl	string	[0..1]	This value contains the public base URL which must be used by a consumer to access services from the Internet.
privateBaseUrl	string	[1]	This value contains the private base URL of the service, which must be used by a consumer to access services from a local network.
services	Service	[0..*]	All information available about the local services provided by public API for the current user.
creationDate	string	[0..1]	Since version 2.7 when this session has been created
expirationDate	string	[0..1]	in case of secured token used to create the session, the expiration date of the token
otherSessions	UserSession	[0..*]	Since version 2.7 List of all previous sessions opened by this user and still alive.

[+] : JSON Example

{
   "admin": boolean,
   "login": "string",
   "timeToLive": int,
   "publicBaseUrl": "string",
   "privateBaseUrl": "string",
   "services": [ {
      "serviceName": "string",
      "serviceVersion": "string",
      "relativeUrl": "string"
   } ],
   "creationDate": "string",
   "expirationDate": "string",
   "otherSessions": [ {
      "sessionId": "string",
      "creationDate": "string",
      "timeToLive": int
   } ]
}

Associated methods :

GET /sessions
POST /sessions

SessionRequest

This element is used to open a Session.

Name	Type	Cardinality	Description
applicationName	string	[1]
applicationAddress	string	[0..1]	Application address.
supervisedAccount	SupervisedAccount	[0..1]	Identifier used to retrieve the supervised user (Administrator authentication but user session).
timeToLive	int	[0..1]	Since version 2.7.4 Time to live in seconds for this session: default value depends on O2G configuration

[+] : JSON Example

{
   "applicationName": "string",
   "applicationAddress": "string",
   "supervisedAccount": {
      "id": "string",
      "type": "LOGIN_NAME | PHONE_NUMBER"
   },
   "timeToLive": int
}

Associated method :

POST /sessions

SessionTokenInfo

Session information on Keep alive when a secured token is used

Name	Type	Cardinality	Description
expirationDate	string	[0..1]	in case of secured token used to create the session, the expiration date of the token

[+] : JSON Example

{
   "expirationDate": "string"
}

Associated method :

POST /sessions/keepalive

string

'string' represents character strings.

SupervisedAccount

The supervised user description.

Name	Type	Cardinality	Description
id	string	[1]	The identifier itself. The type of this value is given by the `SupervisedAccountType` attribute.
type	SupervisedAccountType	[1]	Gives the type of the identifier.

[+] : JSON Example

{
   "id": "string",
   "type": "LOGIN_NAME | PHONE_NUMBER"
}

SupervisedAccountType

The supervised account type values.

Value	Description
LOGIN_NAME	The identifier is a login name.
PHONE_NUMBER	The identifier is a phone number.

UserSession

User Session information.

Name	Type	Cardinality	Description
sessionId	string	[0..1]	The session identifier
creationDate	string	[0..1]	The creation date of this session
timeToLive	int	[0..1]	The residual TTL of the Session in seconds. The value 0 indicates that the session duration is finished and will be soon disappear, but the Thread which purges the sessions has not yet been triggered (It is triggered every 5 minutes).

[+] : JSON Example

{
   "sessionId": "string",
   "creationDate": "string",
   "timeToLive": int
}

User information

Presentation

The User service allows

an administrator to retrieve the list of O2G users.

The users must have been first monitored to be visible.

Resources summary

Resource	Method	Description
/logins	GET	An administrator can get the list of the users (login name).
/users	GET	Find information about a user from a company phone.
/users/{loginName}	GET	Gets information about a user account.
/users/{loginName}/password	PUT	Change user's password.

Notifications summary

Notification	Description
OnUserCreated	This event is sent on creation of an user (only for administrator).
OnUserDeleted	This event is sent when user is deleted (only for administrator).
OnUserInfoChanged	This event is sent on any change on the user's data.

Resources

/logins

Methods

An administrator can get the list of the users (login name).
For a user, only personal information (login name) is returned.

Licenses

No O2G license required.

Request

query parameters
parameter	type	description
nodeIds	string	This parameter is an optional search criterion which allows to select only the users belonging to the given pbx node(s). The given value must be one OXE nodeId or a comma separated list of nodeId. (Note: this parameter can only be used by an administrator).
onlyACD	boolean	This parameter is another optional search criterion which allows to select only the ACD operators (agents or supervisors). This parameter has no value. (Note: this parameter can only be used by an administrator).
onlyWithExtLogin	boolean	This parameter is another optional search criterion which allows to select only users with valid external login. This parameter has no value. (Note: this parameter can only be used by an administrator).

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	type	media types	description
200	LoginsResponse	application/json	OK
400		application/json	Bad Request
403		application/json	Forbidden
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : Get information with a user role. The session was opened by a user.

[+] : Get all user's logins with an administrator role. The session was opened by an administrator.

[+] : Get all user's logins belonging to OXE node 7 or 8. The session was opened by an administrator.

[+] : Get all user's logins corresponding to ACD operators (agents or supervisors) The session was opened by an administrator.

[+] : Get all user's logins belonging to OXE node 5 and 7 and corresponding to ACD operators (agents or supervisors) The session was opened by an administrator.

/users

Methods

Find information about a user from a company phone.
This operation provides useful information to the application:

Name and first name of the user
User's internal login name
User's phone number
User's voicemail information
User's list of devices
...

Remark: only one query parameter can be used at a time. If no query parameter a BAD_REQUEST error will be generated.

Licenses

No O2G license required.

Request

query parameters
parameter	type	description
companyPhone	string	Company phone of the user to retrieve the account description.

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

Returns the result code and, if the code is SUCCESS, information about the concerned user User

code	type	media types	description
200	User	application/json	Returns the result code and, if the code is SUCCESS, information about the concerned user User
400		application/json	Bad Request
403		application/json	Forbidden
404		application/json	Not Found
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : Get information about another user's account.

/users/{loginName}

Methods

Gets information about a user account.
This operation provides useful information to the application:

Name and first name of the user
User's internal login name
User's phone number
User's voicemail information
User's list of devices
...

An application should invoke this method just after the open session step to know the user's account description.
A server application which is interested by retrieving data of the user using this method must invoke it only when it is necessary and then cache the result.

Licenses

No O2G license required.

Request

path parameters
parameter	type	description
loginName	string	Login name of the user to retrieve the account description.

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

Returns the result code and, if the code is SUCCESS, information about the concerned user User

code	type	media types	description
200	User	application/json	OK
400		application/json	Bad Request
403		application/json	Forbidden
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : Get information about the user's account for which the session is opened.

Associated notifications

OnUserInfoChanged

/users/{loginName}/password

Methods

Change user's password.
This operation allows a user or an administrator to change its password.

Licenses

No O2G license required.

Request

path parameters
parameter	type	description
loginName	string	Login name of the user to change the password.

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

body parameter
type	media types	description
ChangePasswordRequest		containing the old and the new passwords

Response

Returns the result code and

code	media types	description
204	application/json	No Content
400	application/json	Bad Request
403	application/json	Forbidden
500	application/json	Internal Server Error
503	application/json	Service Unavailable

Representations

ChangePasswordRequest

Request to change password of the user

Name	Type	Cardinality	Description
oldPassword	string	[1]	Old password
newPassword	string	[1]	New password

[+] : JSON Example

{
   "oldPassword": "string",
   "newPassword": "string"
}

Associated method :

PUT /users/{loginName}/password

Device

Describe a device.

Name	Type	Cardinality	Description
type	DeviceType	[0..1]	Device's type.
id	string	[0..1]	Device identifier which is used to identify the device in telephony requests and events.
subType	string	[0..1]	Device's subtype : For a `DESKPHONE` type, we could have : `ANALOG, NOE_C_Color_IP, ...`

[+] : JSON Example

{
   "type": "DECT | DESKPHONE | MOBILE | SOFTPHONE",
   "id": "string",
   "subType": "string"
}

DeviceType

The device type values.

Value	Description
DECT	A wireless phone set used within the enterprise.
DESKPHONE	A phone set on an office's desk.
MOBILE	A mobile phone.
SOFTPHONE	A phone started from a computer with VOIP.

LoginsResponse

The get logins response.

Name	Type	Cardinality	Description
loginNames	string	[1..*]	List of logins matching the request.

[+] : JSON Example

{
   "loginNames": [ "string" ]
}

Associated method :

GET /logins

OnUserCreated

This event is sent on creation of an user (only for administrator).

There is no control on the 'ids' provided in the 'Selector' filter of the subscription filter (subscription done for all users).

Name	Type	Cardinality	Description
eventName	string	[1]	The name of the event : 'OnUserCreated'
user	User	[1]	The created user object.

[+] : JSON Example

{
   "eventName": "string",
   "user": {
      "companyPhone": "string",
      "firstName": "string",
      "lastName": "string",
      "loginName": "string",
      "voicemail": {
         "number": "string",
         "type": "VM_4635 | VM_4645 | EXTERNAL"
      },
      "devices": [ {
         "type": "DECT | DESKPHONE | MOBILE | SOFTPHONE",
         "id": "string",
         "subType": "string"
      } ],
      "nodeId": "string",
      "externalLogin": "string"
   }
}

OnUserDeleted

This event is sent when user is deleted (only for administrator).

There is no control on the 'ids' provided in the 'Selector' filter of the subscription filter (subscription done for all users).

Name	Type	Cardinality	Description
eventName	string	[1]	The name of the event : 'OnUserDeleted'
loginName	string	[1]	The login name of the deleted user.

[+] : JSON Example

{
   "eventName": "string",
   "loginName": "string"
}

OnUserInfoChanged

This event is sent on any change on the user's data.

Name	Type	Cardinality	Description
eventName	string	[1]	The name of the event : 'OnUserInfoChanged'
loginName	string	[0..1]	Login name of the user receiving the event.
user	User	[1]	The changed user object.

[+] : JSON Example

{
   "eventName": "string",
   "loginName": "string",
   "user": {
      "companyPhone": "string",
      "firstName": "string",
      "lastName": "string",
      "loginName": "string",
      "voicemail": {
         "number": "string",
         "type": "VM_4635 | VM_4645 | EXTERNAL"
      },
      "devices": [ {
         "type": "DECT | DESKPHONE | MOBILE | SOFTPHONE",
         "id": "string",
         "subType": "string"
      } ],
      "nodeId": "string",
      "externalLogin": "string"
   }
}

Associated method :

GET /users/{loginName}

string

'string' represents character strings.

User

The description of a user

Name	Type	Cardinality	*1	Description
companyPhone	string	[0..1]		User's company phone number.
firstName	string	[0..1]		First name of the User or Administrator owner of this Account. Note: Corresponds to the "UTF8_Phone_Book_First_Name" parameter. If this one is empty, it is the parameter "Annu_First_Name" which is taken into account.
lastName	string	[0..1]		Last name of the User or Administrator owner of this Account. Note: Corresponds to the "UTF8_Phone_Book_Name" parameter. If this one is empty, it is the parameter "Annu_Name" which is taken into account.
loginName	string	[0..1]		Login name which identifies the User Account.
voicemail	Voicemail	[0..1]		User's voicemail description.
devices	Device	[0..*]	X	User's devices.
nodeId	string	[0..1]		Node Id on which user is attached
externalLogin	string	[0..1]		Since version 2.7 External login of the user if set (only available with oxe > n1.271)

*1 : attribute only provided if the user is the session's owner or for an administrator session.

[+] : JSON Example

{
   "companyPhone": "string",
   "firstName": "string",
   "lastName": "string",
   "loginName": "string",
   "voicemail": {
      "number": "string",
      "type": "VM_4635 | VM_4645 | EXTERNAL"
   },
   "devices": [ {
      "type": "DECT | DESKPHONE | MOBILE | SOFTPHONE",
      "id": "string",
      "subType": "string"
   } ],
   "nodeId": "string",
   "externalLogin": "string"
}

Associated methods :

GET /users
GET /users/{loginName}

Voicemail

Describes user's voicemail.

Name	Type	Cardinality	Description
number	string	[1]	Voicemail number.
type	VoicemailType	[1]	Voicemail type.

[+] : JSON Example

{
   "number": "string",
   "type": "VM_4635 | VM_4645 | EXTERNAL"
}

VoicemailType

Voicemail type values

Value	Description
VM_4635	Integrated 46x5 voice mail system
VM_4645	Integrated 46x5 voice mail system
EXTERNAL	External voice mail systems

Subscription management

Presentation

Management of all subscription related resources. Once subscription to events is performed, client should instantiate the HTTP Chunk notification channel.

To be eligible to event notification, client must fulfill the following conditions:

Have an opened framework session.
Have subscribed to the set of events he wants to be notified on.
Have received an ACCEPTED subscription response from the server.
Have monitored the devices: the subscription with id ="*" is recommended in order to subscribe to any devices monitored later.

Subscription to event notification is done by declaring the exact names of the events the client wants to be notified on. Another possibility is to subscribe to a set of events, grouped per domain. These sets of events are also called event packages. Supported event packages for API Openness are:

telephony [OnCallCreated, OnCallModified, OnCallRemoved, OnUserStateModified, OnDeviceStateModified, OnTelephonyState, ]
agent [OnAgentStateChanged, ]
system [OnPbxLoaded,OnCtiLinkDown,OnCtiLinkUp]

To declare these events or packages in a subscription request, one or several selectors must be used (at least one per event package).

For the other packages, a selector MUST contain a list of "ids" (i.e. logins), and either a list of "names" corresponding to one or several event names of the same package or an event package name.

It is not possible to mix event names of different packages inside the same selector: different selectors must be used in such case.

It is possible for an administrator only to subscribe for event for all the users of the system. In this case, the id has to be replaced by the wildcard "*". It is highly recommended to use this method instead of giving a huge list of login names (which would penalize the internal system subscription map)

A subscription request includes other fields such as:

The version of the api (e.g. '1.0'). This is a mandatory parameter, which can be use, for instance, to subscribe to older versions of events.
An optional timeout parameter can be set by the client at subscription to indicate whether a timeout shall be established by the server or not.
A timeout is set by the server in following cases:
- timeout parameter is not provided by client. In that case the server sets a 10 minutes default timeout.
- timeout parameter is provided by client with a non-zero value (10 minutes minimum to one hour maximum). In that case the server sets a timeout corresponding to the value provided.
When a timeout value has been set and if no activity is detected during this timeout, the notification chunk (socket) is closed on server side.
It is then up to the client to renew its subscription and reopen the chunk notification channel.
The client can indicate to the server to not establish a timeout by providing a timeout parameter with timeout=0 as value.
In that case, the server establishes and maintains the chunk channel without setting a timeout.
The server sends a keep alive event on the chunk socket to the client every 1 minute (this value can be changed through web.xml) in case of no other activity.
The keep alive event sent by the server is of type: { "eventName": "OnChannelInformation", "text": "keepalive"}.
When webHookUrl is used, the timeout parameter is not applicable and will be ignored if present.
An optional webHookUrl (ex: "webHookUrl": "https://172.25.152.114:8091/webHookOTEvent") which specifies the http(s) webHook event call back URL: If specified, the events are sent on this URL. Each event will be sent through an Http(s) POST request including as Cookie header the subscriptionId and the body containing the event (encoded in JSON oject like in chunk mode).
NB1: the webHook subscription is exclusive with the http chunk mode which must not be used with the same subscription.
NB2: The previous timeout parameter is not applicable in case of webhook: the webHook URL will be considered as valid as long as the subscription is alive.

A subscription response will provide following information to the user:

Notification mode and format, as a reminder of the request parameters.
The subscription status, containing the result of the subscription: ACCEPTED if all events or event packages subscription have been accepted, REFUSED if no subscription can be performed.
An error message as a hint for refused subscriptions.
The subscription Id as a key to access the subscription.
The private and public polling URL for instantiating the HTTP Chunk mode on client side. If public polling URL is specified, it has to be used (access through reverse proxies).

The following remarks must be taken in consideration while designing a REST client using Http chunk mode:

Since the subscription and the notification are not sharing the same channel, events are queued if they occur between subscription and opening of chunk notification channel.
The client can set a timeout value at the subscription by giving a non zero value (10 minutes minimum to one hour maximum, if no attribute parameter is given, a 10 minutes default value is set): If no activity is detected during this timeout, the notification chunk (socket) is closed on server side.
It is up to the client to renew its subscription and reopen the chunk notification channel: if the chunk channel is not reopened after one minute, then the subscription is closed.
If the client chooses to not have a timeout by giving explicitely a timeout=0 parameter, a keep-alive event will be sent by the server every minute on the chunk socket in case of no other activity, in order to detect socket closure.
In any cases (timeout or not), the subscription will be closed after the socket has been detected as closed for one minute.
When webHookUrl is used, the timeout parameter is not applicable and will be ignored if present.

Resources summary

Resource	Method	Description
/subscriptions	POST	Create a subscription for event notification.
/subscriptions	PUT	Update an existing subscription for event notification.
/subscriptions/{subscriptionId}	DELETE	Remove a subscription.

Resources

/subscriptions

Methods

Create a subscription for event notification.

Licenses

No O2G license required.

Request

header parameters
parameter	type	description
Authorization	string	For Private use ONLY: Identifier of the daughter Session

cookie parameters
parameter	type	description
AlcUserId	string	The user framework session Identifier, received as a cookie.

body parameter
type	media types	description
SubscriptionRequest	application/json

Response

Returns the subscription response (which contains the subscription state).

code	type	media types	description
200	Subscription	application/json	OK
400		application/json	Bad Request
403		application/json	Forbidden
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : Create a subscription to telephony event packages, for all users of the system.

[+] : Create a subscription to system event package.

Associated notifications

OnCallCreated, OnCallModified, OnUserStateModified

Update an existing subscription for event notification.
Only the filter part Filter of a subscription can be updated. The other parameters of a previously created subscription will be left untouched (notificationMode, notificationFormat,timeout, ...).

Licenses

No O2G license required.

Request

cookie parameters
parameter	type	description
AlcUserId	string	The user framework session Identifier, received as a cookie.

body parameter
type	media types	description
Filter	application/json	The filter to update. Filter

Response

code	media types	description
204	application/json	No Content
400	application/json	Bad Request
403	application/json	Forbidden
500	application/json	Internal Server Error
503	application/json	Service Unavailable

Examples

[+] : Update a subscription for all events of the telephony, eventSummary event packages, for user userA and userB.

/subscriptions/{subscriptionId}

Methods

Remove a subscription. If the notification of events has started for this subscription (HTTP chunk initiated), the socket will be closed, and all queued events deleted.

Licenses

No O2G license required.

Request

path parameters
parameter	type	description
subscriptionId	string	The identifier of the subscription.

cookie parameters
parameter	type	description
AlcUserId	string	The user framework session Identifier, received as a cookie.

Response

The result code.

code	media types	description
204	application/json	No Content
400	application/json	Bad Request
403	application/json	Forbidden
500	application/json	Internal Server Error

Examples

[+] : Delete an existing subscription. Associated notification channel will be closed, if already opened.

Representations

Filter

High level container of event selector.

Name	Type	Cardinality	Description
selectors	Selector	[0..*]	List of selectors.

[+] : JSON Example

{
   "selectors": [ {
      "ids": [ "string" ],
      "names": [ "string" ]
   } ]
}

Associated method :

PUT /subscriptions

int

'int' is a 32-bit number (-2147483648 to 2147483647).

Selector

A selector is a filter applied to an event. The attributes of an event must match all the criteria of the selector to be sent to the subscriber.

Name	Type	Cardinality	Description
ids	string	[0..*]	The selector specifies that all events must contain one of these identifier. This parameter is not mandatory for a user session, but it is mandatory for an administrator session (at least one identifier must be provided).
names	string	[1..*]	The selector specifies that all events must match this attribute. The content of this field must match the name of events or one of the event packages, as listed in Subscription overview. The `name` can't be empty.

[+] : JSON Example

{
   "ids": [ "string" ],
   "names": [ "string" ]
}

string

'string' represents character strings.

Subscription

Contains the status returned by the server on a subscription request.

Name	Type	Cardinality	Description
subscriptionId	string	[0..1]	The identifier of the subscription, if this one has been accepted.
message	string	[0..1]	Contains a relevant message, especially in case of error or failure.
publicPollingUrl	string	[0..1]	This value contains the public URL to be used in case of HTTP CHUNK notification mode. If set, public URL must be used because it takes into account access through a reverse proxy (Internet access).
privatePollingUrl	string	[0..1]	This value contains the private URL to be used in case of HTTP CHUNK notification mode. This allows access from local network (Intranet access).
status	SubscriptionState	[1]	Status of the subscription returned by the server.

[+] : JSON Example

{
   "subscriptionId": "string",
   "message": "string",
   "publicPollingUrl": "string",
   "privatePollingUrl": "string",
   "status": "UNKNOWN | ACCEPTED | REFUSED"
}

Associated method :

POST /subscriptions

SubscriptionRequest

Contains all information needed for subscription to event notification.

Name	Type	Cardinality	Default	Description
filter	Filter	[0..1]		List of selector used to filter events.
sessionId	string	[0..1]		Reserved: DO NOT USE.
version	string	[1]		The version of the events the user wants to subscribe to.
timeout	int	[0..1]	10	Default lifetime of the channel opened between the server and the client. After that time, in minutes, the server It is up to the client to reconnect. Allowed values are 2 minutes and 60 minutes, with an exception for the value 0. For this special case, the lifetime of the notification channel is not maintained by the given timeout, but depends on the lifetime of the user's session.
webHookUrl	string	[0..1]		If specified, the events corresponding to this subscription will be sent on this URL by callback

[+] : JSON Example

{
   "filter": {
      "selectors": [ {
         "ids": [ "string" ],
         "names": [ "string" ]
      } ]
   },
   "sessionId": "string",
   "version": "string",
   "timeout": int,
   "webHookUrl": "string"
}

Associated method :

POST /subscriptions

SubscriptionState

Defines the response status of the server on a subscription request.

Value	Description
UNKNOWN	Subscription state is unknown.
ACCEPTED	Full subscription has been accepted.
REFUSED	The subscription has been refused.

Call control

Presentation

The Telephony service allows a user to initiate a call and to activate pbx telephony services:

Most of the services concerning the monitored calls are available through /telephony/calls url or telephony/basicCall url.
Some services are invoked on a device: /telephony/devices
Some various services for hunting groups, callbacks, miniMessages, pilots.

The service is rejected if :

the device number is invalid (invalid csta device identifier)
the device is out of service or its equipment number is out of range (resource out of service)
the device is not monitored (requesting incompatible with object)
the device is an analog set in the state : line lock-lout (invalid object state)

For Recording Only configuration, only a restricted part of the Telephony resource operations is available on the devices which have been monitored: Only the operations to consult the existing calls or states.

Resources summary

Resource	Method	Description
/telephony/calls	GET	Get information on all the calls in progress.
/telephony/calls/{callRef}	GET	Returns a description of a call.
/telephony/devices	GET	Gets states of all user devices
/telephony/devices/{deviceId}	GET	Gets a user device state
/telephony/state	GET	Asks for the user telephonic state and capabilities.
/telephony/state/snapshot	POST	Ask a snapshot event on user call state.

Notifications summary

Notification	Description
OnCallCreated	This notification indicates that a new call has been created.
OnCallModified	This notification indicates that an existing call has been modified.
OnCallRemoved	This notification indicates that a call has been removed (hang up, transfer...).
OnDeviceStateModified	This notification indicates that device's state has been modified.
OnTelephonyState	This notification indicates the telephonic state (calls[] and deviceCapabilities[]) of a user
OnUserStateModified	This notification indicates that user's state has been modified (FREE, BUSY ...).

Resources

/telephony/calls

Methods

Get information on all the calls in progress.

Licenses

No O2G license required.

Request

query parameters
parameter	type	description
loginName	string	Login name of the user for whom the request is invoked. This parameter is ignored if the Session identifier matches a user account, but if it matches an administrator account, it MUST be specified.

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	type	media types	description
200	Calls	application/json	OK
400		application/json	Bad Request
401		application/json	Unauthorized
403		application/json	Forbidden
500		application/json	Internal Server Error
503		application/json	Service Unavailable

/telephony/calls/{callRef}

Methods

Returns a description of a call.

Licenses

No O2G license required.

Request

path parameters
parameter	type	description
callRef	string	Call reference.

query parameters
parameter	type	description
loginName	string	Login name of the user for whom the request is invoked. This parameter is ignored if the Session identifier matches a user account, but if it matches an administrator account, it MUST be specified.

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	type	media types	description
200	Call	application/json	OK
400		application/json	Bad Request
401		application/json	Unauthorized
403		application/json	Forbidden
404		application/json	Not Found
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : Get the details of the call 0ba25a675f050700 of user oxe70121 from an admin session

/telephony/devices

Methods

Gets states of all user devices

Licenses

No O2G license required.

Request

query parameters
parameter	type	description
loginName	string	Login name of the user for whom the request is invoked. This parameter is ignored if the Session identifier matches a user account, but if it matches an administrator account, it MUST be specified.

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	type	media types	description
200	DeviceStates	application/json	OK
400		application/json	Bad Request
403		application/json	Forbidden
404		application/json	Not Found
500		application/json	Internal Server Error
503		application/json	Service Unavailable

/telephony/devices/{deviceId}

Methods

Gets a user device state

Licenses

No O2G license required.

Request

path parameters
parameter	type	description
deviceId	string	Device phone number for which the operation is invoked. If the session is opened by a Framework User, the device phone number must be one of the user.

query parameters
parameter	type	description
loginName	string	Login name of the user for whom the request is invoked. This parameter is ignored if the Session identifier matches a user account, but if it matches an administrator account, it MUST be specified.

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	type	media types	description
200	DeviceState	application/json	OK
400		application/json	Bad Request
403		application/json	Forbidden
404		application/json	Not Found
500		application/json	Internal Server Error
503		application/json	Service Unavailable

/telephony/state

Methods

Asks for the user telephonic state and capabilities.

Licenses

No O2G license required.

Request

query parameters
parameter	type	description
loginName	string	Login name of the user for whom the request is invoked. This parameter is ignored if the Session identifier matches a user account, but if it matches an administrator account, it MUST be specified.

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	type	media types	description
200	TelephonicState	application/json	OK
400		application/json	Bad Request
403		application/json	Forbidden
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : Get the user oxe70121 telephony state from an admin session

/telephony/state/snapshot

Methods

Ask a snapshot event on user call state. The event OnTelephonyState will contain the TelephonicState (calls[] and deviceCapabilities[]) If this request is made by an administrator and no loginName is provided, the snapshot is asked for all the users If a second request is asked since the previous one is still in progress, it has no effect.

Licenses

No O2G license required.

Request

query parameters
parameter	type	description
loginName	string	Login name of the user for whom the request is invoked. This parameter is ignored if the Session identifier matches a user account. For an administrator session, the loginName must either correspond to an existing user or be null: in this last case, the snapshot event request is done for all the users. CAUTION!: this request is immediately acknowledged but the processing may take a long time if the number of users is huge.

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	media types	description
204	application/json	No Content
400	application/json	Bad Request
401	application/json	Unauthorized
403	application/json	Forbidden
404	application/json	Not Found
500	application/json	Internal Server Error
503	application/json	Service Unavailable

Associated notifications

OnTelephonyState

Representations

AcdCallData

Describes data related to an ACD call.

Name	Type	Cardinality	Description
callInfo	AcdCallInfo	[0..1]	info related to the call
queueData	QueueData	[0..1]	state of the queue
pilotNumber	string	[0..1]	pilot number if it is an acd call
rsiNumber	string	[0..1]	rsi number if it is an rsi call
supervisedTransfer	boolean	[0..1]	if the transfer from the pilot has been supervised or not
pilotTransferInfo	PilotTransferInfo	[0..1]	in case of enquiry call only, information related to the transfer of the call to the pilot

[+] : JSON Example

{
   "callInfo": {
      "queueWaitingTime": int,
      "globalWaitingTime": int,
      "agentGroup": "string",
      "local": boolean
   },
   "queueData": {
      "waitingTime": int,
      "saturated": boolean
   },
   "pilotNumber": "string",
   "rsiNumber": "string",
   "supervisedTransfer": boolean,
   "pilotTransferInfo": {
      "transferPossible": boolean,
      "pilotStatus": "OPEN | BLOCKED | BLOCKED_ON_RULE | BLOCKED_ON_BLOCKED_RULE | GENERAL_FORWARDING | ..."
   }
}

AcdCallInfo

Describes data related to the distributed ACD call.

Name	Type	Cardinality	Description
queueWaitingTime	int	[0..1]	waiting time in the queue
globalWaitingTime	int	[0..1]	global waiting time in the distribution
agentGroup	string	[0..1]	agent group
local	boolean	[0..1]	if the acd call is local or not

[+] : JSON Example

{
   "queueWaitingTime": int,
   "globalWaitingTime": int,
   "agentGroup": "string",
   "local": boolean
}

boolean

'boolean' is a data type, having two values (true and false).

Call

Describes an user's call.

Name	Type	Cardinality	Description
callRef	string	[1]	Reference of the call.
callData	CallData	[0..1]	Call data.
legs	Leg	[0..*]	User's devices.
participants	Participant	[0..*]	Participants.

[+] : JSON Example

{
   "callRef": "string",
   "callData": {
      "initialCalled": {
         "id": {
            "loginName": "string",
            "phoneNumber": "string",
            "multiLine": boolean
         },
         "firstName": "string",
         "lastName": "string",
         "displayName": "string",
         "type": {
            "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
            "subType": "string"
         }
      },
      "lastRedirecting": {
         "id": {
            "loginName": "string",
            "phoneNumber": "string",
            "multiLine": boolean
         },
         "firstName": "string",
         "lastName": "string",
         "displayName": "string",
         "type": {
            "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
            "subType": "string"
         }
      },
      "deviceCall": boolean,
      "anonymous": boolean,
      "callUUID": "string",
      "state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
      "recordState": "PAUSED | RECORDING",
      "tags": [ {
         "name": "string",
         "value": "string",
         "visibilities": [ "string" ]
      } ],
      "associateData": "string",
      "hexaBinaryAssociatedData": "string",
      "accountInfo": "string",
      "acdCallData": {
         "callInfo": {
            "queueWaitingTime": int,
            "globalWaitingTime": int,
            "agentGroup": "string",
            "local": boolean
         },
         "queueData": {
            "waitingTime": int,
            "saturated": boolean
         },
         "pilotNumber": "string",
         "rsiNumber": "string",
         "supervisedTransfer": boolean,
         "pilotTransferInfo": {
            "transferPossible": boolean,
            "pilotStatus": "OPEN | BLOCKED | BLOCKED_ON_RULE | BLOCKED_ON_BLOCKED_RULE | GENERAL_FORWARDING | ..."
         }
      },
      "trunkIdentification": {
         "networkTimeslot": int,
         "trunkNeqt": [ int ]
      }
   },
   "legs": [ {
      "deviceId": "string",
      "state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
      "ringingRemote": boolean
   } ],
   "participants": [ {
      "participantId": "string",
      "identity": {
         "id": {
            "loginName": "string",
            "phoneNumber": "string",
            "multiLine": boolean
         },
         "firstName": "string",
         "lastName": "string",
         "displayName": "string",
         "type": {
            "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
            "subType": "string"
         }
      },
      "anonymous": boolean,
      "undroppable": boolean,
      "state": "RINGING_INCOMING | ACTIVE"
   } ]
}

Associated method :

GET /telephony/calls/{callRef}

CallCause

Lists the different call causes.

Value	Description
ABANDONED	Caller in a two-party call has disconnected before the call was answered.
ALL_TRUNK_BUSY	The call is receiving the network congestion tone.
BUSY	The call is receiving the busy tone.
CLEARED	One party in a two-party call has disconnected after the call was answered.
PARTICIPANT_LEFT	One party has left the conference call.
CONFERENCED	This is a multi-party call.
INVALID_NUMBER	The call is receiving the invalid number tone.
DESTINATION_NOT_OBTAINABLE	The destination cannot be reached.
DO_NOT_DISTURB	The device is in DND.
FORWARDED	The call has been forwarded.
NOT_ANSWERED	The call has been hanged up before answer.
PICKED_UP	The call has been picked up.
PARKED	The call has been parked.
REDIRECTED	The call has been redirected.
OVERFLOWN	The call goes on overflow destination.
TRANSFERRED	This is a transferred call.
CAMP_ON	The call has been put in wait.
UNKNOWN	Unknown cause.
PICKED_UP_TANDEM	Picked up tandem.
CALL_BACK	The call is a call back.
RECALL	The call is recall (e.g. on HELD call indicates that device rings back).
DISTRIBUTED	CCD context: call distribution
ACD_ENTER_DISTRIBUTION	CCD context: call enters in distribution
RESOURCES_NOT_AVAILABLE	CCD context: pilot is not open
SUPERVISOR_LISTENING
SUPERVISOR_INTRUSION
SUPERVISOR_RESTRICT_INTRUSION
NO_AVAILABLE_AGENT
LOCKOUT

CallData

Describes data associated to a call.

Name	Type	Cardinality	Description
initialCalled	PartyInfo	[0..1]	Initial user called for this call.
lastRedirecting	PartyInfo	[0..1]	Since version 2.7.4 Last device which redirects the call, if it is different from the initialCalled.
deviceCall	boolean	[0..1]	If `true` it's a device call else if not specified or `false` it's a user call.
anonymous	boolean	[0..1]	If `true` it's a anonymous call.
callUUID	string	[0..1]	CallUUID associated to this call (used to correlate RTSM events with SIP events for multimedia users only).
state	MediaState	[0..1]	Call state (computed from media state).
recordState	RecordState	[0..1]	Record state (only if recording is active).
tags	Tag	[0..*]	Tags associated to this call.
associateData	string	[0..1]	Associated data (or Correlator data).
hexaBinaryAssociatedData	string	[0..1]	Hexa binary array format for Associated data (or Correlator data).
accountInfo	string	[0..1]	Account info associated to the call.
acdCallData	AcdCallData	[0..1]	ACD info associated to the call.
trunkIdentification	TrunkIdentification	[0..1]	Since version 2.7.1 TrunkIdentification if external call

[+] : JSON Example

{
   "initialCalled": {
      "id": {
         "loginName": "string",
         "phoneNumber": "string",
         "multiLine": boolean
      },
      "firstName": "string",
      "lastName": "string",
      "displayName": "string",
      "type": {
         "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
         "subType": "string"
      }
   },
   "lastRedirecting": {
      "id": {
         "loginName": "string",
         "phoneNumber": "string",
         "multiLine": boolean
      },
      "firstName": "string",
      "lastName": "string",
      "displayName": "string",
      "type": {
         "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
         "subType": "string"
      }
   },
   "deviceCall": boolean,
   "anonymous": boolean,
   "callUUID": "string",
   "state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
   "recordState": "PAUSED | RECORDING",
   "tags": [ {
      "name": "string",
      "value": "string",
      "visibilities": [ "string" ]
   } ],
   "associateData": "string",
   "hexaBinaryAssociatedData": "string",
   "accountInfo": "string",
   "acdCallData": {
      "callInfo": {
         "queueWaitingTime": int,
         "globalWaitingTime": int,
         "agentGroup": "string",
         "local": boolean
      },
      "queueData": {
         "waitingTime": int,
         "saturated": boolean
      },
      "pilotNumber": "string",
      "rsiNumber": "string",
      "supervisedTransfer": boolean,
      "pilotTransferInfo": {
         "transferPossible": boolean,
         "pilotStatus": "OPEN | BLOCKED | BLOCKED_ON_RULE | BLOCKED_ON_BLOCKED_RULE | GENERAL_FORWARDING | ..."
      }
   },
   "trunkIdentification": {
      "networkTimeslot": int,
      "trunkNeqt": [ int ]
   }
}

Calls

Container for the calls.

Name	Type	Cardinality	Description
calls	Call	[0..*]	List of calls

[+] : JSON Example

{
   "calls": [ {
      "callRef": "string",
      "callData": {
         "initialCalled": {
            "id": {
               "loginName": "string",
               "phoneNumber": "string",
               "multiLine": boolean
            },
            "firstName": "string",
            "lastName": "string",
            "displayName": "string",
            "type": {
               "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
               "subType": "string"
            }
         },
         "lastRedirecting": {
            "id": {
               "loginName": "string",
               "phoneNumber": "string",
               "multiLine": boolean
            },
            "firstName": "string",
            "lastName": "string",
            "displayName": "string",
            "type": {
               "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
               "subType": "string"
            }
         },
         "deviceCall": boolean,
         "anonymous": boolean,
         "callUUID": "string",
         "state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
         "recordState": "PAUSED | RECORDING",
         "tags": [ {
            "name": "string",
            "value": "string",
            "visibilities": [ "string" ]
         } ],
         "associateData": "string",
         "hexaBinaryAssociatedData": "string",
         "accountInfo": "string",
         "acdCallData": {
            "callInfo": {
               "queueWaitingTime": int,
               "globalWaitingTime": int,
               "agentGroup": "string",
               "local": boolean
            },
            "queueData": {
               "waitingTime": int,
               "saturated": boolean
            },
            "pilotNumber": "string",
            "rsiNumber": "string",
            "supervisedTransfer": boolean,
            "pilotTransferInfo": {
               "transferPossible": boolean,
               "pilotStatus": "OPEN | BLOCKED | BLOCKED_ON_RULE | BLOCKED_ON_BLOCKED_RULE | GENERAL_FORWARDING | ..."
            }
         },
         "trunkIdentification": {
            "networkTimeslot": int,
            "trunkNeqt": [ int ]
         }
      },
      "legs": [ {
         "deviceId": "string",
         "state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
         "ringingRemote": boolean
      } ],
      "participants": [ {
         "participantId": "string",
         "identity": {
            "id": {
               "loginName": "string",
               "phoneNumber": "string",
               "multiLine": boolean
            },
            "firstName": "string",
            "lastName": "string",
            "displayName": "string",
            "type": {
               "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
               "subType": "string"
            }
         },
         "anonymous": boolean,
         "undroppable": boolean,
         "state": "RINGING_INCOMING | ACTIVE"
      } ]
   } ]
}

Associated method :

GET /telephony/calls

DeviceCapabilities

Describes an user's device capabilities.

Name	Type	Cardinality	Description
deviceId	string	[1]	Device phone number.
makeCall	boolean	[0..1]	Specifies whether a new call can be initiated.
makeBusinessCall	boolean	[0..1]	Specifies whether a business call can be initiated.
makePrivateCall	boolean	[0..1]	Specifies whether a personal call can be initiated.
unParkCall	boolean	[0..1]	Specifies whether a call can be an unparked call.

[+] : JSON Example

{
   "deviceId": "string",
   "makeCall": boolean,
   "makeBusinessCall": boolean,
   "makePrivateCall": boolean,
   "unParkCall": boolean
}

DeviceState

Describes a user's device state.

Name	Type	Cardinality	Description
deviceId	string	[1]	Device phone number.
state	OperationalState	[1]	Device state.
cause	CallCause	[0..1]	Since version 2.7.2 Cause associated with state change.

[+] : JSON Example

{
   "deviceId": "string",
   "state": "IN_SERVICE | OUT_OF_SERVICE | UNKNOWN",
   "cause": "ABANDONED | ALL_TRUNK_BUSY | BUSY | CLEARED | PARTICIPANT_LEFT | CONFERENCED | ..."
}

Associated method :

GET /telephony/devices/{deviceId}

DeviceStates

Container for device state.

Name	Type	Cardinality	Description
deviceStates	DeviceState	[0..*]	List of DeviceState

[+] : JSON Example

{
   "deviceStates": [ {
      "deviceId": "string",
      "state": "IN_SERVICE | OUT_OF_SERVICE | UNKNOWN",
      "cause": "ABANDONED | ALL_TRUNK_BUSY | BUSY | CLEARED | PARTICIPANT_LEFT | CONFERENCED | ..."
   } ]
}

Associated method :

GET /telephony/devices

Identifier

Key information to help retrieving a participant.

Name	Type	Cardinality	Description
loginName	string	[0..1]	Login name.
phoneNumber	string	[0..1]	Company phone number.
multiLine	boolean	[0..1]	Since version 2.7.3 Is this phone number one of the multiline number of the device.

[+] : JSON Example

{
   "loginName": "string",
   "phoneNumber": "string",
   "multiLine": boolean
}

int

'int' is a 32-bit number (-2147483648 to 2147483647).

Leg

Describes a leg. A leg represents the user's device involved in a call for a dedicated media (audio or video).

Name	Type	Cardinality	Description
deviceId	string	[1]	Device phone number.
state	MediaState	[0..1]	Media state.
ringingRemote	boolean	[0..1]	boolean set to true when the leg is in RINGING_OUTGOING state and if the remote party is ringing (ie has been alerted).

[+] : JSON Example

{
   "deviceId": "string",
   "state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
   "ringingRemote": boolean
}

MainType

Main participant type

Value	Description
USER	The participant is a user of the system.
DEVICE	The participant is a device of the system.
SERVICE	The participant is a service of the system.
EXTERNAL	The participant is not a user of the system.
UNKNOWN	The main participant type is unknown.

MediaState

Lists the different media states.

Value	Description
UNKNOWN	Unknown media state.
OFF_HOOK	the OFF_HOOK state is used when the device is busy for other reasons than a call: typically during service activation
IDLE	Call is in idle state.
RELEASING	Call release is in progress.
DIALING	An attempt to make a call is in progress.
HELD	The call has been placed on hold.
RINGING_INCOMING	The incoming call is ringing.
RINGING_OUTGOING	The outgoing call is ringing.
ACTIVE	The call is active (means in conversation).

OnCallCreated

This notification indicates that a new call has been created.

Name	Type	Cardinality	Description
eventName	string	[1]	The name of the event : 'OnCallCreated'
loginName	string	[1]	Login name of the user (identifier which can be used for filtering).
callRef	string	[1]	Reference of the call.
cause	CallCause	[0..1]	Cause of the event.
callData	CallData	[0..1]	Call data.
initiator	string	[0..1]	Initiator of the call : correspond to one participant of the call, the matching can be done with the `participantId` value of the participants.
legs	Leg	[0..*]	Legs associated to this call.
participants	Participant	[0..*]	Participants associated to this call.
deviceCapabilities	DeviceCapabilities	[0..*]	Devices capabilities (if not specified, it means there is no modification).

[+] : JSON Example

{
   "eventName": "string",
   "loginName": "string",
   "callRef": "string",
   "cause": "ABANDONED | ALL_TRUNK_BUSY | BUSY | CLEARED | PARTICIPANT_LEFT | CONFERENCED | ...",
   "callData": {
      "initialCalled": {
         "id": {
            "loginName": "string",
            "phoneNumber": "string",
            "multiLine": boolean
         },
         "firstName": "string",
         "lastName": "string",
         "displayName": "string",
         "type": {
            "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
            "subType": "string"
         }
      },
      "lastRedirecting": {
         "id": {
            "loginName": "string",
            "phoneNumber": "string",
            "multiLine": boolean
         },
         "firstName": "string",
         "lastName": "string",
         "displayName": "string",
         "type": {
            "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
            "subType": "string"
         }
      },
      "deviceCall": boolean,
      "anonymous": boolean,
      "callUUID": "string",
      "state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
      "recordState": "PAUSED | RECORDING",
      "tags": [ {
         "name": "string",
         "value": "string",
         "visibilities": [ "string" ]
      } ],
      "associateData": "string",
      "hexaBinaryAssociatedData": "string",
      "accountInfo": "string",
      "acdCallData": {
         "callInfo": {
            "queueWaitingTime": int,
            "globalWaitingTime": int,
            "agentGroup": "string",
            "local": boolean
         },
         "queueData": {
            "waitingTime": int,
            "saturated": boolean
         },
         "pilotNumber": "string",
         "rsiNumber": "string",
         "supervisedTransfer": boolean,
         "pilotTransferInfo": {
            "transferPossible": boolean,
            "pilotStatus": "OPEN | BLOCKED | BLOCKED_ON_RULE | BLOCKED_ON_BLOCKED_RULE | GENERAL_FORWARDING | ..."
         }
      },
      "trunkIdentification": {
         "networkTimeslot": int,
         "trunkNeqt": [ int ]
      }
   },
   "initiator": "string",
   "legs": [ {
      "deviceId": "string",
      "state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
      "ringingRemote": boolean
   } ],
   "participants": [ {
      "participantId": "string",
      "identity": {
         "id": {
            "loginName": "string",
            "phoneNumber": "string",
            "multiLine": boolean
         },
         "firstName": "string",
         "lastName": "string",
         "displayName": "string",
         "type": {
            "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
            "subType": "string"
         }
      },
      "anonymous": boolean,
      "undroppable": boolean,
      "state": "RINGING_INCOMING | ACTIVE"
   } ],
   "deviceCapabilities": [ {
      "deviceId": "string",
      "makeCall": boolean,
      "makeBusinessCall": boolean,
      "makePrivateCall": boolean,
      "unParkCall": boolean
   } ]
}

Associated method :

POST /subscriptions

OnCallModified

This notification indicates that an existing call has been modified.

Modification of a call can be triggered for various reason: changes on legs, on participants, changes on states, ...

Name	Type	Cardinality	Description
eventName	string	[1]	The name of the event : 'OnCallModified'
loginName	string	[1]	Login name of the user (identifier which can be used for filtering).
callRef	string	[1]	Reference of the call.
cause	CallCause	[0..1]	Cause of the event.
previousCallRef	string	[0..1]	If specified, this call reference indicates that the "`callRef`" replace "`previousCallRef`". This also indicates that "`previousCallRef`" has been removed (call removed event is not generated)
replacedByCallRef	string	[0..1]	This call reference appears when a call is released, the `replacedByCallRef` if present indicates that the "`callRef`" is replaced by this one.
callData	CallData	[0..1]	Call data modified (if not specified, it means there is no modification).
modifiedLegs	Leg	[0..*]	Legs modified (if not specified, it means there is no modification).
addedLegs	Leg	[0..*]	Legs added (if not specified, it means there is no added leg).
removedLegs	Leg	[0..*]	Legs removed (if not specified, it means there is no removed leg).
modifiedParticipants	Participant	[0..*]	Participants modified (if not specified, it means there is no modification).
addedParticipants	Participant	[0..*]	Participants added (if not specified, it means there is no added participant).
removedParticipantIds	string	[0..*]	Participants removed (if not specified, it means there is no removed participant).
deviceCapabilities	DeviceCapabilities	[0..*]	Devices capabilities modified (if not specified, it means there is no modification).

[+] : JSON Example

{
   "eventName": "string",
   "loginName": "string",
   "callRef": "string",
   "cause": "ABANDONED | ALL_TRUNK_BUSY | BUSY | CLEARED | PARTICIPANT_LEFT | CONFERENCED | ...",
   "previousCallRef": "string",
   "replacedByCallRef": "string",
   "callData": {
      "initialCalled": {
         "id": {
            "loginName": "string",
            "phoneNumber": "string",
            "multiLine": boolean
         },
         "firstName": "string",
         "lastName": "string",
         "displayName": "string",
         "type": {
            "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
            "subType": "string"
         }
      },
      "lastRedirecting": {
         "id": {
            "loginName": "string",
            "phoneNumber": "string",
            "multiLine": boolean
         },
         "firstName": "string",
         "lastName": "string",
         "displayName": "string",
         "type": {
            "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
            "subType": "string"
         }
      },
      "deviceCall": boolean,
      "anonymous": boolean,
      "callUUID": "string",
      "state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
      "recordState": "PAUSED | RECORDING",
      "tags": [ {
         "name": "string",
         "value": "string",
         "visibilities": [ "string" ]
      } ],
      "associateData": "string",
      "hexaBinaryAssociatedData": "string",
      "accountInfo": "string",
      "acdCallData": {
         "callInfo": {
            "queueWaitingTime": int,
            "globalWaitingTime": int,
            "agentGroup": "string",
            "local": boolean
         },
         "queueData": {
            "waitingTime": int,
            "saturated": boolean
         },
         "pilotNumber": "string",
         "rsiNumber": "string",
         "supervisedTransfer": boolean,
         "pilotTransferInfo": {
            "transferPossible": boolean,
            "pilotStatus": "OPEN | BLOCKED | BLOCKED_ON_RULE | BLOCKED_ON_BLOCKED_RULE | GENERAL_FORWARDING | ..."
         }
      },
      "trunkIdentification": {
         "networkTimeslot": int,
         "trunkNeqt": [ int ]
      }
   },
   "modifiedLegs": [ {
      "deviceId": "string",
      "state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
      "ringingRemote": boolean
   } ],
   "addedLegs": [ {
      "deviceId": "string",
      "state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
      "ringingRemote": boolean
   } ],
   "removedLegs": [ {
      "deviceId": "string",
      "state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
      "ringingRemote": boolean
   } ],
   "modifiedParticipants": [ {
      "participantId": "string",
      "identity": {
         "id": {
            "loginName": "string",
            "phoneNumber": "string",
            "multiLine": boolean
         },
         "firstName": "string",
         "lastName": "string",
         "displayName": "string",
         "type": {
            "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
            "subType": "string"
         }
      },
      "anonymous": boolean,
      "undroppable": boolean,
      "state": "RINGING_INCOMING | ACTIVE"
   } ],
   "addedParticipants": [ {
      "participantId": "string",
      "identity": {
         "id": {
            "loginName": "string",
            "phoneNumber": "string",
            "multiLine": boolean
         },
         "firstName": "string",
         "lastName": "string",
         "displayName": "string",
         "type": {
            "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
            "subType": "string"
         }
      },
      "anonymous": boolean,
      "undroppable": boolean,
      "state": "RINGING_INCOMING | ACTIVE"
   } ],
   "removedParticipantIds": [ "string" ],
   "deviceCapabilities": [ {
      "deviceId": "string",
      "makeCall": boolean,
      "makeBusinessCall": boolean,
      "makePrivateCall": boolean,
      "unParkCall": boolean
   } ]
}

Associated method :

POST /subscriptions

OnCallRemoved

This notification indicates that a call has been removed (hang up, transfer...).

Name	Type	Cardinality	Description
eventName	string	[1]	The name of the event : 'OnCallRemoved'
loginName	string	[1]	Login name of the user (identifier which can be used for filtering).
callRef	string	[1]	Reference of the call.
cause	CallCause	[0..1]	Cause of the event.
newDestination	string	[0..1]	If the call is forwarded or redirected, this field indicate the new destination number. This number is a user phone number if the destination is a device associated to an user, else the number is the number provided by the system.
deviceCapabilities	DeviceCapabilities	[0..*]	Devices capabilities (if not specified, it means there is no modification).

[+] : JSON Example

{
   "eventName": "string",
   "loginName": "string",
   "callRef": "string",
   "cause": "ABANDONED | ALL_TRUNK_BUSY | BUSY | CLEARED | PARTICIPANT_LEFT | CONFERENCED | ...",
   "newDestination": "string",
   "deviceCapabilities": [ {
      "deviceId": "string",
      "makeCall": boolean,
      "makeBusinessCall": boolean,
      "makePrivateCall": boolean,
      "unParkCall": boolean
   } ]
}

OnDeviceStateModified

This notification indicates that device's state has been modified.

Name	Type	Cardinality	Description
eventName	string	[1]	The name of the event : 'OnDeviceStateModified'
loginName	string	[1]	Login name of the user (identifier which can be used for filtering).
deviceStates	DeviceState	[1..*]	Device state modified.

[+] : JSON Example

{
   "eventName": "string",
   "loginName": "string",
   "deviceStates": [ {
      "deviceId": "string",
      "state": "IN_SERVICE | OUT_OF_SERVICE | UNKNOWN",
      "cause": "ABANDONED | ALL_TRUNK_BUSY | BUSY | CLEARED | PARTICIPANT_LEFT | CONFERENCED | ..."
   } ]
}

OnTelephonyState

This notification indicates the telephonic state (calls[] and deviceCapabilities[]) of a user

Name	Type	Cardinality	Description
eventName	string	[1]	The name of the event : 'OnTelephonyState'
loginName	string	[1]	Login name of the user (identifier which can be used for filtering).
state	TelephonicState	[0..1]	telephonic state of the user.

[+] : JSON Example

{
   "eventName": "string",
   "loginName": "string",
   "state": {
      "calls": [ {
         "callRef": "string",
         "callData": {
            "initialCalled": {
               "id": {
                  "loginName": "string",
                  "phoneNumber": "string",
                  "multiLine": boolean
               },
               "firstName": "string",
               "lastName": "string",
               "displayName": "string",
               "type": {
                  "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
                  "subType": "string"
               }
            },
            "lastRedirecting": {
               "id": {
                  "loginName": "string",
                  "phoneNumber": "string",
                  "multiLine": boolean
               },
               "firstName": "string",
               "lastName": "string",
               "displayName": "string",
               "type": {
                  "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
                  "subType": "string"
               }
            },
            "deviceCall": boolean,
            "anonymous": boolean,
            "callUUID": "string",
            "state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
            "recordState": "PAUSED | RECORDING",
            "tags": [ {
               "name": "string",
               "value": "string",
               "visibilities": [ "string" ]
            } ],
            "associateData": "string",
            "hexaBinaryAssociatedData": "string",
            "accountInfo": "string",
            "acdCallData": {
               "callInfo": {
                  "queueWaitingTime": int,
                  "globalWaitingTime": int,
                  "agentGroup": "string",
                  "local": boolean
               },
               "queueData": {
                  "waitingTime": int,
                  "saturated": boolean
               },
               "pilotNumber": "string",
               "rsiNumber": "string",
               "supervisedTransfer": boolean,
               "pilotTransferInfo": {
                  "transferPossible": boolean,
                  "pilotStatus": "OPEN | BLOCKED | BLOCKED_ON_RULE | BLOCKED_ON_BLOCKED_RULE | GENERAL_FORWARDING | ..."
               }
            },
            "trunkIdentification": {
               "networkTimeslot": int,
               "trunkNeqt": [ int ]
            }
         },
         "legs": [ {
            "deviceId": "string",
            "state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
            "ringingRemote": boolean
         } ],
         "participants": [ {
            "participantId": "string",
            "identity": {
               "id": {
                  "loginName": "string",
                  "phoneNumber": "string",
                  "multiLine": boolean
               },
               "firstName": "string",
               "lastName": "string",
               "displayName": "string",
               "type": {
                  "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
                  "subType": "string"
               }
            },
            "anonymous": boolean,
            "undroppable": boolean,
            "state": "RINGING_INCOMING | ACTIVE"
         } ]
      } ],
      "deviceCapabilities": [ {
         "deviceId": "string",
         "makeCall": boolean,
         "makeBusinessCall": boolean,
         "makePrivateCall": boolean,
         "unParkCall": boolean
      } ],
      "userState": "FREE | BUSY | UNKNOWN"
   }
}

Associated method :

POST /telephony/state/snapshot

OnUserStateModified

This notification indicates that user's state has been modified (FREE, BUSY ...).

Name	Type	Cardinality	Description
eventName	string	[1]	The name of the event : 'OnUserStateModified'
loginName	string	[1]	Login name of the user (identifier which can be used for filtering).
state	UserState	[1]	User state.

[+] : JSON Example

{
   "eventName": "string",
   "loginName": "string",
   "state": "FREE | BUSY | UNKNOWN"
}

Associated method :

POST /subscriptions

OperationalState

List the different operational states.

Value	Description
IN_SERVICE	Operational state is in service.
OUT_OF_SERVICE	Operational state is out of service.
UNKNOWN	Operational state is unknown.

Participant

Detail about a kind of participant.

Name	Type	Cardinality	Description
participantId	string	[1]	Participant identifier (Should not be displayed).
identity	PartyInfo	[0..1]	Participant identity card.
anonymous	boolean	[0..1]	Participant identity is secret
undroppable	boolean	[0..1]	If true this participant can not be dropped.
state	MediaState	[0..1]	Participant state. This field is only filled in multi-party call (>=3 participants) and only when the Participant mediaState is changed to RINGING_INCOMING or from RINGING_INCOMING to ACTIVE.

[+] : JSON Example

{
   "participantId": "string",
   "identity": {
      "id": {
         "loginName": "string",
         "phoneNumber": "string",
         "multiLine": boolean
      },
      "firstName": "string",
      "lastName": "string",
      "displayName": "string",
      "type": {
         "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
         "subType": "string"
      }
   },
   "anonymous": boolean,
   "undroppable": boolean,
   "state": "RINGING_INCOMING | ACTIVE"
}

ParticipantType

Participant type description

Name	Type	Cardinality	Description
main	MainType	[1]	Gives the main type of the participant: "user", "device", ...
subType	string	[0..1]	The subType string gives a supplementary information and can contain "pbx", "public", "pre-off-hook", telephony-services", "voicemail", "voice-homepage", "voice-it", "sip"...

[+] : JSON Example

{
   "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
   "subType": "string"
}

PartyInfo

Full description of a party involved in a call log record.

Name	Type	Cardinality	Description
id	Identifier	[1]	Identifier of the party.
firstName	string	[0..1]	First name.
lastName	string	[0..1]	Last name.
displayName	string	[0..1]	Display name (display names are used in SIP URIs). Notice: if previous fields lastname/firstname are filled then displayName field will be empty
type	ParticipantType	[0..1]	Type of participant.

[+] : JSON Example

{
   "id": {
      "loginName": "string",
      "phoneNumber": "string",
      "multiLine": boolean
   },
   "firstName": "string",
   "lastName": "string",
   "displayName": "string",
   "type": {
      "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
      "subType": "string"
   }
}

PilotStatus

Lists the different ACD pilot status.

Value	Description
OPEN
BLOCKED
BLOCKED_ON_RULE
BLOCKED_ON_BLOCKED_RULE
GENERAL_FORWARDING
GENERAL_FORWARDING_ON_RULE
BLOCKED_ON_GENERAL_FORWARDING_RULE
OTHER

PilotTransferInfo

Describes data relative to an ACD Queue Pilot.

Name	Type	Cardinality	Description
transferPossible	boolean	[0..1]	`true` means the transfer to pilot or RSI is possible.
pilotStatus	PilotStatus	[0..1]	Status of the pilot.

[+] : JSON Example

{
   "transferPossible": boolean,
   "pilotStatus": "OPEN | BLOCKED | BLOCKED_ON_RULE | BLOCKED_ON_BLOCKED_RULE | GENERAL_FORWARDING | ..."
}

QueueData

Describes data relative to an ACD Queue Pilot.

Name	Type	Cardinality	Description
waitingTime	int	[0..1]	estimated waiting time in the queue(in seconds).
saturated	boolean	[0..1]	`true` means the queue is saturated.

[+] : JSON Example

{
   "waitingTime": int,
   "saturated": boolean
}

RecordState

Lists the different state when recording.

Value	Description
PAUSED	Recording is paused.
RECORDING	Recording is in progress.

string

'string' represents character strings.

Tag

Describes a Tag (a defined name and a value).

Name	Type	Cardinality	Description
name	string	[1]	Tag name.
value	string	[0..1]	Tag value.
visibilities	string	[0..*]	Visibility of this tag : list of login name.

[+] : JSON Example

{
   "name": "string",
   "value": "string",
   "visibilities": [ "string" ]
}

TelephonicState

Snapshot of the user's telephonic state.

Name	Type	Cardinality	Description
calls	Call	[0..*]	List of current calls.
deviceCapabilities	DeviceCapabilities	[0..*]	Gives the list of device's capabilities.
userState	UserState	[0..1]	state of the user: is only used in case the user is busy unknown at monitoring

[+] : JSON Example

{
   "calls": [ {
      "callRef": "string",
      "callData": {
         "initialCalled": {
            "id": {
               "loginName": "string",
               "phoneNumber": "string",
               "multiLine": boolean
            },
            "firstName": "string",
            "lastName": "string",
            "displayName": "string",
            "type": {
               "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
               "subType": "string"
            }
         },
         "lastRedirecting": {
            "id": {
               "loginName": "string",
               "phoneNumber": "string",
               "multiLine": boolean
            },
            "firstName": "string",
            "lastName": "string",
            "displayName": "string",
            "type": {
               "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
               "subType": "string"
            }
         },
         "deviceCall": boolean,
         "anonymous": boolean,
         "callUUID": "string",
         "state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
         "recordState": "PAUSED | RECORDING",
         "tags": [ {
            "name": "string",
            "value": "string",
            "visibilities": [ "string" ]
         } ],
         "associateData": "string",
         "hexaBinaryAssociatedData": "string",
         "accountInfo": "string",
         "acdCallData": {
            "callInfo": {
               "queueWaitingTime": int,
               "globalWaitingTime": int,
               "agentGroup": "string",
               "local": boolean
            },
            "queueData": {
               "waitingTime": int,
               "saturated": boolean
            },
            "pilotNumber": "string",
            "rsiNumber": "string",
            "supervisedTransfer": boolean,
            "pilotTransferInfo": {
               "transferPossible": boolean,
               "pilotStatus": "OPEN | BLOCKED | BLOCKED_ON_RULE | BLOCKED_ON_BLOCKED_RULE | GENERAL_FORWARDING | ..."
            }
         },
         "trunkIdentification": {
            "networkTimeslot": int,
            "trunkNeqt": [ int ]
         }
      },
      "legs": [ {
         "deviceId": "string",
         "state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
         "ringingRemote": boolean
      } ],
      "participants": [ {
         "participantId": "string",
         "identity": {
            "id": {
               "loginName": "string",
               "phoneNumber": "string",
               "multiLine": boolean
            },
            "firstName": "string",
            "lastName": "string",
            "displayName": "string",
            "type": {
               "main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
               "subType": "string"
            }
         },
         "anonymous": boolean,
         "undroppable": boolean,
         "state": "RINGING_INCOMING | ACTIVE"
      } ]
   } ],
   "deviceCapabilities": [ {
      "deviceId": "string",
      "makeCall": boolean,
      "makeBusinessCall": boolean,
      "makePrivateCall": boolean,
      "unParkCall": boolean
   } ],
   "userState": "FREE | BUSY | UNKNOWN"
}

Associated method :

GET /telephony/state

TrunkIdentification

For external call, provide information on network timeslot and trunk eqt number

Name	Type	Cardinality	Description
networkTimeslot	int	[0..1]	the network time slot.
trunkNeqt	int	[0..*]	trunk equipment number (Could be 2 nbrs in case of conference with 2 different external trunks.

[+] : JSON Example

{
   "networkTimeslot": int,
   "trunkNeqt": [ int ]
}

UserState

Lists the different types of user state.

Value	Description
FREE	User is free.
BUSY	User is busy.
UNKNOWN	The user state is unknown.

Call Center Agent

Presentation

Terminology:

ACD, CCD: Automatic Call Distribution, Call Center Distribution.

ACD agent: ACD operator.

ACD Supervisor: ACD operator with special prerogatives (supervision, help) of agents.

proACD : device onto the agent logon.

pilot : first step of the ACD distribution: an incoming call arrives on the pilot corresponding to the called number.

waiting queue : second step of the ACD distribution: from the pilot, the call is then routed to the best waiting queue.

processing group (PG) : third step of the ACD distribution: from the queue, the call is then directed to a processing group. The call is finally distributed to an agent

For Recording Only configuration, the Contact Center service provides only a restricted part of the resource operations on the devices which have been monitored

to ask for agent state or to ask for a snapshot event on agent state

Resources summary

Resource	Method	Description
/acd/agent/state	GET	Get the ACD agent state.
/acd/agent/state/snapshot	POST	Ask a snapshot event on agent state.

Notification summary

Notification	Description
OnAgentStateChanged	Event sent when ACD agent state is modified

Resources

/acd/agent/state

Methods

Get the ACD agent state.

Licenses

No O2G license required.

Request

query parameters
parameter	type	description
loginName	string	Login name of the user for whom the request is invoked. This parameter is ignored if the Session identifier matches a user account, but if it matches an administrator account, it MUST be specified.

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	type	media types	description
200	AgentState	application/json
400		application/json	Bad Request
401		application/json	Unauthorized
403		application/json	Forbidden
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : Get the agent state of an agent loged in idle state

[+] : Get the agent state of an agent loged off

/acd/agent/state/snapshot

Methods

Ask a snapshot event on agent state. This request has result to send an OnAgentStateChanged event on the concerned agent. If this request is made by an administrator and no loginName is provided, the snapshot is asked for all the agents. If a second request is asked since the previous one is still in progress, it has no effect. CAUTION!: this request is immediately acknowledged but the processing may take a long time if the number of users is huge.

Licenses

No O2G license required.

Request

query parameters
parameter	type	description
loginName	string	Login name of the user for whom the request is invoked. This parameter is ignored if the Session identifier matches a user account. For an administrator session, the loginName must either correspond to an existing user or be null: in this last case, the snapshot event request is done for all the agents.

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	media types	description
204	application/json	No Content
400	application/json	Bad Request
401	application/json	Unauthorized
403	application/json	Forbidden
404	application/json	Not Found
500	application/json	Internal Server Error
503	application/json	Service Unavailable

Associated notifications

OnAgentStateChanged

Representations

AgentMainState

Main agent state (loggedOn/loggedOff)

Value	Description
UNKNOWN	the state of the agent is unknown
LOG_ON	The agent is logged on a pro-acd device
LOG_OFF	The agent is not logged
ERROR	Error status

AgentState

Agent State.

Name	Type	Cardinality	Description
mainState	AgentMainState	[1]	Main state of the agent (logged on or logged off).
subState	AgentSubState	[0..1]	Sub state of the agent when it is logged.
proAcdDeviceNumber	string	[0..1]	Pro-acd Device phone number on which the operation is invoked.
pgNumber	string	[0..1]	Processing group number.
withdrawReason	int	[0..1]	The withdraw reason number in case of state withdraw. The list of withdraw reasons corresponding to the processing group should have been retrieved through a GET .../agent/withdrawReasons
withdrawn	boolean	[0..1]	The withdrawn Boolean is present and true if the agent initial state is withdrawn

[+] : JSON Example

{
   "mainState": "UNKNOWN | LOG_ON | LOG_OFF | ERROR",
   "subState": "READY | OUT_OF_PG | BUSY | TRANSACTION_CODE_INPUT | WRAPUP | PAUSE | WITHDRAW | ...",
   "proAcdDeviceNumber": "string",
   "pgNumber": "string",
   "withdrawReason": int,
   "withdrawn": boolean
}

Associated method :

GET /acd/agent/state

AgentSubState

Agent state when logged on

Value	Description
READY	The agent is ready
OUT_OF_PG	The agent is logged on, but outside its pre-affected processing group
BUSY	The agent is busy
TRANSACTION_CODE_INPUT	The agent is in transaction code input step
WRAPUP	The agent is in wrap up
PAUSE	The agent is in pause
WITHDRAW	The agent is in withdraw
WRAPUP_IM	The agent is in wrap up IM
WRAPUP_EMAIL	The agent is in wrap up email
WRAPUP_EMAIL_INTERRUPTIBLE	The agent is in wrap up email interruptible
WRAPUP_OUTBOUND	The agent is in wrap up outbound
WRAPUP_CALLBACK	The agent is in wrap up Callback

boolean

'boolean' is a data type, having two values (true and false).

int

'int' is a 32-bit number (-2147483648 to 2147483647).

OnAgentStateChanged

Event sent when ACD agent state is modified

Name	Type	Cardinality	Description
eventName	string	[1]	The name of the event : 'OnAgentStateChanged'
loginName	string	[1]	Login name of the user receiving the event.
state	AgentState	[1]	ACD state.

[+] : JSON Example

{
   "eventName": "string",
   "loginName": "string",
   "state": {
      "mainState": "UNKNOWN | LOG_ON | LOG_OFF | ERROR",
      "subState": "READY | OUT_OF_PG | BUSY | TRANSACTION_CODE_INPUT | WRAPUP | PAUSE | WITHDRAW | ...",
      "proAcdDeviceNumber": "string",
      "pgNumber": "string",
      "withdrawReason": int,
      "withdrawn": boolean
   }
}

Associated method :

POST /acd/agent/state/snapshot

string

'string' represents character strings.

Maintenance

Presentation

Only for administrator. The system information resource is used to retrieve information about the system state, in particular information on the pbx nodes and their connection state.

Informations about license are also provided per item: total allocated licenses, numbers of current used and expiration date.

Resources summary

Resource	Method	Description
/system/status	GET	Get information about system status.

Notifications summary

Notification	Description
OnCtiLinkDown	Notification sent when CTI link is down.
OnCtiLinkUp	Notification sent when CTI link is up
OnServerStart	Notification sent when O2G is ready (all oxe nodes are connected and loaded).

Resources

/system/status

Methods

Get information about system status.
This operation provides information about the system state , and the total number of each license type available for the system. <\b>This operation is restricted to an admin session only.

Licenses

No O2G license required.

Request

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

Returns the result code and, if the code is SUCCESS, system information corresponding to the concerned user SystemStatus

code	type	media types	description
200	SystemStatus	application/json	OK
400		application/json	Bad Request
403		application/json	Forbidden
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : Get information about the system status

Representations

boolean

'boolean' is a data type, having two values (true and false).

ConfigurationTypeDTO

Type of O2G configuration

Value	Description
PBX_MANAGEMENT	Pbx management only
RECORDING	RECORDING only
FULL_SERVICES	Pbx management + all services

CTILinkState

Lists the different OXE CTI link state

Value	Description
CONNECTED_MAIN	connected to main Call server
CONNECTED_SECONDARY	connected to secondary Call server
DISCONNECTED	not connected

dateTime

'dateTime' is an UTC datetime whose format (ISO 8601 compatible) is yyyy-MM-ddTHH:mm:ss.SSSZ (example: 2013-05-16T18:17:15.489Z).

DRLink

CSTA DR link.

Name	Type	Cardinality	Description
identifier	string	[1]	DR link Registration identifier
initiator	string	[1]	Since version 2.7.3 DR link initiator identifier (application name)
nbRecordedDevices	int	[0..1]	number of recorded devices
recordedDevices	RecordedDevice	[0..*]	list of recorded devices

[+] : JSON Example

{
   "identifier": "string",
   "initiator": "string",
   "nbRecordedDevices": int,
   "recordedDevices": [ {
      "number": "string",
      "user": "string",
      "crid": "string",
      "recorded": boolean,
      "recordingResource": "string",
      "ip": boolean,
      "sentFlowPort": int,
      "receivedFlowPort": int,
      "encrypted": boolean
   } ]
}

int

'int' is a 32-bit number (-2147483648 to 2147483647).

License

Name	Type	Cardinality	Description
name	string	[0..1]	Name
total	int	[0..1]	Total number
currentUsed	int	[0..1]	Current used number. For the ROXE_API_MANAGEMENT particular case, it corresponds to the total network OXE Subscriber number
expiration	string	[0..1]
application	boolean	[0..1]	Not used (Already true)

[+] : JSON Example

{
   "name": "string",
   "total": int,
   "currentUsed": int,
   "expiration": "string",
   "application": boolean
}

LicenseStatus

License status

Name	Type	Cardinality	Description
type	string	[0..1]	FLEXLM (mode CAPEX) or LMS (mode OPEX)
context	string	[0..1]	Only for LMS : infrastructure used (PROD, QA or INT)
currentServer	string	[0..1]	Server address
status	string	[0..1]	Only for LMS : RTR status (NORMAL, GRACE PERIOD, PANIC MODE)
statusMessage	string	[0..1]	Only for LMS : Debug message, associated to the status
lics	License	[0..*]	Licenses information

[+] : JSON Example

{
   "type": "string",
   "context": "string",
   "currentServer": "string",
   "status": "string",
   "statusMessage": "string",
   "lics": [ {
      "name": "string",
      "total": int,
      "currentUsed": int,
      "expiration": "string",
      "application": boolean
   } ]
}

OnCtiLinkDown

Notification sent when CTI link is down. This event is sent with a 30 s minimum and 60 s maximum delay

Name	Type	Cardinality	Description
eventName	string	[1]	The name of the event : 'OnCtiLinkDown'
nodeId	string	[1]	the nodeId which CTI link is down
recorderId	string	[0..1]	If CTI link is a drLink, identifier of the recorder

[+] : JSON Example

{
   "eventName": "string",
   "nodeId": "string",
   "recorderId": "string"
}

OnCtiLinkUp

Notification sent when CTI link is up

Name	Type	Cardinality	Description
eventName	string	[1]	The name of the event : 'OnCtiLinkUp'
nodeId	string	[1]	the nodeId which CTI link is back to normal

[+] : JSON Example

{
   "eventName": "string",
   "nodeId": "string"
}

OnServerStart

Notification sent when O2G is ready (all oxe nodes are connected and loaded).
To be received, this event needs a webhook url to be configured.

Name	Type	Cardinality	Description
eventName	string	[1]	The name of the event : 'OnServerStart'
serverId	string	[1]	the IP of the server which starts

[+] : JSON Example

{
   "eventName": "string",
   "serverId": "string"
}

OXRConfig

OmniPCX Record description

Name	Type	Cardinality	Description
hostName	string	[0..1]	OXR host name
ipAddress	string	[0..1]	OXR ip address
siteId	string	[0..1]	OXR site identifier
secured	boolean	[0..1]	is secured access
connected	boolean	[0..1]	is connected
devices	string	[0..*]	list of devices number which may be recorded by this recorder

[+] : JSON Example

{
   "hostName": "string",
   "ipAddress": "string",
   "siteId": "string",
   "secured": boolean,
   "connected": boolean,
   "devices": [ "string" ]
}

OXRRecordedDevice

Description of a recorded device (by one or more OXR recorder)

Name	Type	Cardinality	Description
number	string	[0..1]	Device Number
recordable	boolean	[0..1]	Is device recordable on demand.
startCapabilities	StartType	[0..*]	Start mode capability of the device. Not present if device is not recordable on demand.
recorders	string	[0..*]	list of recorder identifiers which manage the device

[+] : JSON Example

{
   "number": "string",
   "recordable": boolean,
   "startCapabilities": [ "RECORD_FROM_NOW | RECORD_ENTIRE_CALL" ],
   "recorders": [ "string" ]
}

OXRRecordingStatus

OXR recording service status

Name	Type	Cardinality	Description
oxrs	OXRConfig	[0..*]	List of OXR recorders
devices	OXRRecordedDevice	[0..*]	List of OXR recorded devices

[+] : JSON Example

{
   "oxrs": [ {
      "hostName": "string",
      "ipAddress": "string",
      "siteId": "string",
      "secured": boolean,
      "connected": boolean,
      "devices": [ "string" ]
   } ],
   "devices": [ {
      "number": "string",
      "recordable": boolean,
      "startCapabilities": [ "RECORD_FROM_NOW | RECORD_ENTIRE_CALL" ],
      "recorders": [ "string" ]
   } ]
}

PbxStatus

Pbx description

Name	Type	Cardinality	Description
name	string	[0..1]	PBX name
nodeId	int	[0..1]	PBX nodeId
mainAddress	ServerAddress	[0..1]	PBX address
secondaryAddress	ServerAddress	[0..1]	PBX address
version	string	[0..1]	PBX version
connected	boolean	[0..1]	PBX CMIS connection state
loaded	boolean	[0..1]
ctiLinkState	CTILinkState	[0..1]
secured	boolean	[0..1]	is PBX secured connection
monitoredUserNumber	int	[0..1]	Number of monitored PBX Users
lmsConnectionStatus	boolean	[0..1]	Lms connection status
drLinks	DRLink	[0..*]	In case of IP recording, list of drLinks

[+] : JSON Example

{
   "name": "string",
   "nodeId": int,
   "mainAddress": {
      "fqdn": "string",
      "ip": "string"
   },
   "secondaryAddress": {
      "fqdn": "string",
      "ip": "string"
   },
   "version": "string",
   "connected": boolean,
   "loaded": boolean,
   "ctiLinkState": "CONNECTED_MAIN | CONNECTED_SECONDARY | DISCONNECTED",
   "secured": boolean,
   "monitoredUserNumber": int,
   "lmsConnectionStatus": boolean,
   "drLinks": [ {
      "identifier": "string",
      "initiator": "string",
      "nbRecordedDevices": int,
      "recordedDevices": [ {
         "number": "string",
         "user": "string",
         "crid": "string",
         "recorded": boolean,
         "recordingResource": "string",
         "ip": boolean,
         "sentFlowPort": int,
         "receivedFlowPort": int,
         "encrypted": boolean
      } ]
   } ]
}

RecordedDevice

Recorded device identification with it recording resource

Name	Type	Cardinality	Description
number	string	[0..1]	device number
user	string	[0..1]	device user
crid	string	[0..1]	device csta crid
recorded	boolean	[0..1]	has the recording been asked
recordingResource	string	[0..1]	recorder IP address or TDM time slot
ip	boolean	[0..1]	Is an IP recording
sentFlowPort	int	[0..1]	In case of IP recording, the recorder port where is sent the sent RTP flow(from the local recorded device to the remote)
receivedFlowPort	int	[0..1]	In case of IP recording, the recorder port where is sent the received RTP flow(from the remote to the local recorded device)
encrypted	boolean	[0..1]	In case of IP recording, if it is encrypted)

[+] : JSON Example

{
   "number": "string",
   "user": "string",
   "crid": "string",
   "recorded": boolean,
   "recordingResource": "string",
   "ip": boolean,
   "sentFlowPort": int,
   "receivedFlowPort": int,
   "encrypted": boolean
}

ServerAddress

Address of a server

Name	Type	Cardinality	Description
fqdn	string	[0..1]	FQDN
ip	string	[0..1]	IP

[+] : JSON Example

{
   "fqdn": "string",
   "ip": "string"
}

ServicesStatus

Address of a server

Name	Type	Cardinality	Description
name	string	[0..1]	Name
status	string	[0..1]	Status Started/Stopped
mode	string	[0..1]	Mode Active/Standby

[+] : JSON Example

{
   "name": "string",
   "status": "string",
   "mode": "string"
}

StartType

How the record start can be activated: entire call or from now

Value	Description
RECORD_FROM_NOW	Record from now.
RECORD_ENTIRE_CALL	Record from Beginning.

string

'string' represents character strings.

SubscriberFilterDTO

How does O2G automatically create user from OXE subscriber

Value	Description
A4980	Oxe subscriber are automatically loaded according to A4980 attribute
ALL	Oxe subscribers are all automatically loaded
NONE	None Oxe subscriber automatically loaded

SystemServicesStatusDTO

System description Management package

Name	Type	Cardinality	Description
services	ServicesStatus	[0..*]	Services information
globalIPAdress	string	[0..1]	if System is in HA mode, status og global IP address
drbd	string	[0..1]	if System is in HA mode, status of drbd

[+] : JSON Example

{
   "services": [ {
      "name": "string",
      "status": "string",
      "mode": "string"
   } ],
   "globalIPAdress": "string",
   "drbd": "string"
}

SystemStatus

System description Management package

Name	Type	Cardinality	Description
logicalAddress	ServerAddress	[0..1]	System logical address
startDate	dateTime	[0..1]	Start date (UTC).
ha	boolean	[0..1]	is System in HA mode
primary	string	[0..1]	if System is in HA mode, fqdn of the current active system
primaryVersion	string	[0..1]	version of the current active system
primaryServicesStatus	SystemServicesStatusDTO	[0..1]	Primary server services status
secondary	string	[0..1]	if System is in HA mode, fqdn of the backup system
secondaryVersion	string	[0..1]	version of the backup system
secondaryServicesStatus	SystemServicesStatusDTO	[0..1]	Secondary server services status
pbxs	PbxStatus	[0..*]	PBXs information
recordingStatus	OXRRecordingStatus	[0..1]	Since version 2.7.3 OXRecorders information
license	LicenseStatus	[0..1]	The total number of each license type available for the system
configurationType	ConfigurationTypeDTO	[0..1]	Type of configuration
applicationId	string	[0..1]	O2G server identifier
subscriberFilter	SubscriberFilterDTO	[0..1]	Oxe subscriber load filter type

[+] : JSON Example

{
   "logicalAddress": {
      "fqdn": "string",
      "ip": "string"
   },
   "startDate": "dateTime",
   "ha": boolean,
   "primary": "string",
   "primaryVersion": "string",
   "primaryServicesStatus": {
      "services": [ {
         "name": "string",
         "status": "string",
         "mode": "string"
      } ],
      "globalIPAdress": "string",
      "drbd": "string"
   },
   "secondary": "string",
   "secondaryVersion": "string",
   "secondaryServicesStatus": {
      "services": [ {
         "name": "string",
         "status": "string",
         "mode": "string"
      } ],
      "globalIPAdress": "string",
      "drbd": "string"
   },
   "pbxs": [ {
      "name": "string",
      "nodeId": int,
      "mainAddress": {
         "fqdn": "string",
         "ip": "string"
      },
      "secondaryAddress": {
         "fqdn": "string",
         "ip": "string"
      },
      "version": "string",
      "connected": boolean,
      "loaded": boolean,
      "ctiLinkState": "CONNECTED_MAIN | CONNECTED_SECONDARY | DISCONNECTED",
      "secured": boolean,
      "monitoredUserNumber": int,
      "lmsConnectionStatus": boolean,
      "drLinks": [ {
         "identifier": "string",
         "initiator": "string",
         "nbRecordedDevices": int,
         "recordedDevices": [ {
            "number": "string",
            "user": "string",
            "crid": "string",
            "recorded": boolean,
            "recordingResource": "string",
            "ip": boolean,
            "sentFlowPort": int,
            "receivedFlowPort": int,
            "encrypted": boolean
         } ]
      } ]
   } ],
   "recordingStatus": {
      "oxrs": [ {
         "hostName": "string",
         "ipAddress": "string",
         "siteId": "string",
         "secured": boolean,
         "connected": boolean,
         "devices": [ "string" ]
      } ],
      "devices": [ {
         "number": "string",
         "recordable": boolean,
         "startCapabilities": [ "RECORD_FROM_NOW | RECORD_ENTIRE_CALL" ],
         "recorders": [ "string" ]
      } ]
   },
   "license": {
      "type": "string",
      "context": "string",
      "currentServer": "string",
      "status": "string",
      "statusMessage": "string",
      "lics": [ {
         "name": "string",
         "total": int,
         "currentUsed": int,
         "expiration": "string",
         "application": boolean
      } ]
   },
   "configurationType": "PBX_MANAGEMENT | RECORDING | FULL_SERVICES",
   "applicationId": "string",
   "subscriberFilter": "A4980 | ALL | NONE"
}

Associated method :

GET /system/status

Voice Recording

Presentation

The Recording service allows a recorder application to record voice of OXE devices, either in IP or TDM mode.
(Only for an O2G administrator.)
The devices may be all kinds of OXE Subscriber.
Prior to start records, the recorder MUST:

register on the OXE node, creating a dedicated CTI record link.
start monitor each device on the CTI record link.

The service also allows to send a beep tone on a device on which the recording has been previously asked.
IP recording is the suitable way to record IP devices on OXE IP PBX. However, the legacy TDM recording using PCM links is also supported by this service.
Prerequisites:

the application must know the oxe node numbers (given by the /system/status service), and the OXE tone numbers to use.
for IP recording, the oxe must be configured with Applications / CSTA / "DR-Link on IP supported."
for IP recording, the oxe must be configured with "recording IP logger" address.
the recorded oxe devices must have "record authorization" right phone facility.
Software lock 130 MUST be in: 1(1 NICE DR link)/2(1 other DR link)/3(several NICE DR links)/4(several other DR links).
for IP recording secure mode, Secured RTP voice flow between the recorded IP device and the recorder must be activated on OXE.
- The global system parameter "Enable Native Encryption" is enabled
- The recorded IP set parameter "Native Encryption" is enabled
- The dedicated CSTA link is secured by TLS

Specifications of the service

Several record links may be created on the same node (OXE rejects the request when the limit is exceeded).
In IP recording mode, an application can ask to record the same device on two different links at a time, using 2 physical recorders (2 IP addresses).
If an application asks a new IP record on the same device and on the same link, using a different IP physical recorder, the previous record is stopped on the first recorder and started on the new one.
The operation of start/stop record can be asked on a device regardless of its telephony state(idle/in conversation/out-of-service). However, the telephony events generated thanks to the monitoring allow to wait for the communication establishment.
The IP recording may be secured or not: If secured, the IP recorder service registration returns a secure CSTA connection and the startRecord return the SRTP keys.
If IP native encryption is used, the SRTP keys necessary for the recorder to connect the recorded device are sent back in the start record response. The response also contains the cipher suite. If the cipher suite is absent, AES-CM-128-NULL-AUTH is the default ciphersuite used by OXE. "XXX-YY-ZZ-NULL_AUTH" is not an official cypher name but "...-NULL_AUTH" means encryption is done without authentication:
AES-CM-128-NULL-AUTH corresponds to AES-CM-128-HMAC-SHA1-80 cypher suite without authentication and
AES_256_CM_NULL_AUTH corresponds to AES-256-CM-HMAC-SHA1-80 cypher suite without authentication
TDM recording through PCM link may be used as the main and unique recording mode, or can be asked in parallel with IP recording (on different devices)
in TDM mode, a device can only be recorded by only one recorder at a time.
If a beep tone is asked on a recorded device, the tone will be sent in IP or TDM mode depending the mode of recording.
Limitation: In TDM mode, asking a beep tone is only accepted if the device is in communication.
If oxe recording configuration is secured, but the register application doesn't support this mode, then it must explicitly specified "secured=false" in the Register Service.

The typical sequential of the operations of the service is:

create an administrator session.
make a subscription to telephony event package("*" for all). If the application prefers to target the subscriptions to a defined list, the subscription must be performed after the monitoring of the devices.
establish an event chunk channel or open the http web-hook listener
register the recorder service on the OXE node to create a dedicated CTI record link.
start monitor each device on the CTI record link: the corresponding user appears in the /logins or /users list
start record a device on the CTI record link (considering or regardless its telephony state)
start beep generation device may be invoked (in TDM, only if the device is already in com)
stop record a device on the CTI record link (considering or regardless its telephony state)

(Stop monitor may never be used by the application)

Here is a following example to illustrate:

GET https://myserver/api/rest/authenticate?version=1.0
200
{
"credential" : "eyJhb...",
"publicUrl" : "https://myserver/api/rest/1.0/sessions",
"internalUrl" : "https://myserver/api/rest/1.0/sessions"
}

POST https://myserver/api/rest/1.0/sessions
{"applicationName": "MyRecordingApplication"}
200
{
"admin": true,
"timeToLive": 1800,
"publicBaseUrl": "https://myserver/api/rest/1.0",
"privateBaseUrl": "https://myserver/api/rest/1.0",
"services": [
{ "serviceName": "Logins", "serviceVersion": "1.0", "relativeUrl": "/logins"},
{ "serviceName": "Users", "serviceVersion": "1.0", "relativeUrl": "/users" },
{ "serviceName": "Telephony", "serviceVersion": "1.0", "relativeUrl": "/telephony"},
{ "serviceName": "Subscriptions", "serviceVersion": "1.0", "relativeUrl": "/subscriptions"},
{ "serviceName": "Maintenance", "serviceVersion": "1.0", "relativeUrl": "/system"},
{ "serviceName": "UsersManagement","serviceVersion": "1.0", "relativeUrl": "/users"},
{ "serviceName": "Analytics", "serviceVersion": "1.0", "relativeUrl": "/usages"},
{ "serviceName": "VoiceRecording", "serviceVersion": "1.0", "relativeUrl": "/iprecord"}
],
"creationDate": "2024-06-24T14:10:12Z"
}

POST https://myserver/api/rest/1.0/subscriptions
{ "filter": {"selectors": [ { "ids": [ "*"], "names": ["telephony"]}]},
"version": "1.0",
"timeout": 0
}
200
{
"subscriptionId": "eyJhb...",
"publicPollingUrl": "https://myserver:8016/OTEvents?subscriptionId=eyJhb...",
"privatePollingUrl": "https://myserver:8016/OTEvents?subscriptionId=eyJhb...",
"status": "ACCEPTED"
}

... open chunk channel to https://myserver:8016/OTEvents?subscriptionId=eyJhb... ...

GET https://myserver/api/rest/1.0/iprecord/2/link {}
200
{}

POST https://myserver/api/rest/1.0/iprecord/2/link
{"type": "NICE"}
200
{"registrationId":"02000b02","secure":true}

POST https://myserver/api/rest/1.0/iprecord/2/link/02000b02/monitor
{"deviceNumber": "2004"}
200
{"userId":"oxe2004"}

POST https://myserver/api/rest/1.0/iprecord/2/link/02000b02/record
{"receivedFlowPort": 54321, "deviceNumber": "2004", "sentFlowPort": 12345, "ipRecorderAddr": "192.168.30.250"}
200
{}

POST https://myserver/api/rest/1.0/iprecord/2/link/02000b02/beep
{"deviceNumber": "2004", "silenceDuration": 3, "tone": 1, "presenceDuration": 100} - 204

DELETE https://myserver/api/rest/1.0/iprecord/2/link/02000b02/beep/2004 {} - 204

DELETE https://myserver/api/rest/1.0/iprecord/2/link/02000b02/record/2004 {} - 204

DELETE https://myserver/api/rest/1.0/iprecord/2/link/02000b02/monitor/2004 {} - 204

DELETE https://myserver/api/rest/1.0/iprecord/2/link/02000b02 {} - 204

DELETE https://myserver/api/rest/1.0/subscriptions/eyJhb...{} - 204

DELETE https://myserver/api/rest/1.0/sessions {} - 204

Resources summary

Resource	Method	Description
/iprecord/{nodeId}/link	GET	Get the list of existing recorder links on a pbx.
/iprecord/{nodeId}/link	POST	Register a recorder link on a pbx.
/iprecord/{nodeId}/link/{registerId}	DELETE	Cancel the registration of a recorder link on a pbx.
/iprecord/{nodeId}/link/{registerId}/beep	POST	Start beep generation on an device.
/iprecord/{nodeId}/link/{registerId}/beep/{deviceNumber}	DELETE	Stop beep generation on an IP device.
/iprecord/{nodeId}/link/{registerId}/monitor	POST	Start the monitoring of one or several devices on a drLink.
/iprecord/{nodeId}/link/{registerId}/monitor/{deviceNumber}	DELETE	Stop the monitoring of a device on a drLink.
/iprecord/{nodeId}/link/{registerId}/record	POST	Start an IP record of an IP device.
/iprecord/{nodeId}/link/{registerId}/record/{deviceNumber}	DELETE	Stop the IP or TDM recording of a device.
/iprecord/{nodeId}/link/{registerId}/tdmrecord	POST	Start an TDM record of a device through a PCM link.

Resources

/iprecord/{nodeId}/link

Methods

Get the list of existing recorder links on a pbx.

Licenses

No O2G license required.

Request

path parameters
parameter	type	description
nodeId	int	the oxe node number where are registered the recorder

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	type	media types	description
200	DRLinks	application/json
400		application/json	Bad Request
403		application/json	Forbidden
404		application/json	Not Found
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : Get the registered a recorder links on the pbx 7.

Register a recorder link on a pbx. To be able to invoke the other methods(IP or TDM voice recording), an recorder must at first register on a pbx.
A registration identifier of the link is returned back, to be used on each of the other methods.

Licenses

No O2G license required.

Request

path parameters
parameter	type	description
nodeId	int	the oxe node number where to register the recorder

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

body parameter
type	media types	description
RegisterServiceRequest		(mandatory) to specify the type of recorder: NICE or standard recorder

Response

code	type	media types	description
200	ServiceRegistered	application/json
400		application/json	Bad Request
403		application/json	Forbidden
404		application/json	Not Found
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : Register a standard recorder link on the pbx 7.

[+] : Register a NICE recorder link on the pbx 7. The link is secure

/iprecord/{nodeId}/link/{registerId}

Methods

Cancel the registration of a recorder link on a pbx.

Licenses

No O2G license required.

Request

path parameters
parameter	type	description
nodeId	int	the oxe node number where to unregister the link
registerId	string	the DR link identifier to unregister

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	media types	description
204	application/json	No content
400	application/json	Bad Request
403	application/json	Forbidden
404	application/json	Not Found
500	application/json	Internal Server Error
503	application/json	Service Unavailable

Examples

[+] : Unregister the current recorder link (registrationId = "123456") on the pbx 7.

/iprecord/{nodeId}/link/{registerId}/beep

Methods

Start beep generation on an device.
The mode IP or TDM used to send the beep depends on the mode of recording.

Licenses

No O2G license required.

Request

path parameters
parameter	type	description
nodeId	int	the oxe pbx node
registerId	string	the DR link identifier

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

body parameter
type	media types	description
StartBeepRequest		specifies the device number on which to send beep to, the tone, the presence and silence duration

Response

code	media types	description
204	application/json	No content
400	application/json	Bad Request
403	application/json	Forbidden
404	application/json	Not Found
500	application/json	Internal Server Error
503	application/json	Service Unavailable

Examples

[+] : Start generate tone 25 on the device 70120 on the node 7 through the IP record link 123456

/iprecord/{nodeId}/link/{registerId}/beep/{deviceNumber}

Methods

Stop beep generation on an IP device.

Licenses

No O2G license required.

Request

path parameters
parameter	type	description
nodeId	int	the oxe pbx node
registerId	string	the ip DR link identifier
deviceNumber	string	the device number

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	media types	description
204	application/json	No content
400	application/json	Bad Request
403	application/json	Forbidden
404	application/json	Not Found
500	application/json	Internal Server Error
503	application/json	Service Unavailable

Examples

[+] : Stop generate tone on the device 70120 on the node 7 through the IP record link 123456

/iprecord/{nodeId}/link/{registerId}/monitor

Methods

Start the monitoring of one or several devices on a drLink.
This action MUST be done prior to ask the recording of the devices. A user identifier is returned back for each device, to be used for telephony event subscription

Licenses

No O2G license required.

Request

path parameters
parameter	type	description
nodeId	int	the oxe pbx node
registerId	string	the ip DR link identifier

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

body parameter
type	media types	description
MonitorRequest		specifies the device number(s) to monitor

Response

code	type	media types	description
200	DeviceMonitored	application/json
400		application/json	Bad Request
403		application/json	Forbidden
404		application/json	Not Found
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : Start to monitor the device 70120 on the node 7 through the recorder link 123456.

[+] : Start to monitor the tandem device 70124 of the main user 70123 on the node 7 through the recorder link 123456.

[+] : Start to monitor the devices 70001,70002 and 70003 on the node 7 through the recorder link 123456.

/iprecord/{nodeId}/link/{registerId}/monitor/{deviceNumber}

Methods

Stop the monitoring of a device on a drLink.

Licenses

No O2G license required.

Request

path parameters
parameter	type	description
nodeId	int	the oxe pbx node
registerId	string	the ip DR link identifier
deviceNumber	string	specifies the device number to stop the monitoring

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	media types	description
204	application/json	No content
400	application/json	Bad Request
403	application/json	Forbidden
404	application/json	Not Found
500	application/json	Internal Server Error
503	application/json	Service Unavailable

Examples

[+] : Stop to monitor the device 70120 on the node 7 through the recorder link 123456.

/iprecord/{nodeId}/link/{registerId}/record

Methods

Start an IP record of an IP device.
In case native encryption is enabled by OXE, the SRTP keys (key/salt) created by OXE are returned in order to encrypt the voice flow between the IP set and the recorder.

Licenses

No O2G license required.

Request

path parameters
parameter	type	description
nodeId	int	the oxe pbx node
registerId	string	the ip DR link identifier

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

body parameter
type	media types	description
StartRecordRequest		specifies the device number to record, the recorder IP address and the IP call flow ports to record

Response

code	type	media types	description
200	RecordingSrtpKeys	application/json
400		application/json	Bad Request
403		application/json	Forbidden
404		application/json	Not Found
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : Start an IP record of the device 70120 on the node 7 through the recorder link 123456 on the ports xxxx and yyyy with IP recorder address aaa.bbb.ccc.ddd. The native encryption is not enabled: No SRTP key is returned.

/iprecord/{nodeId}/link/{registerId}/record/{deviceNumber}

Methods

Stop the IP or TDM recording of a device.

Licenses

No O2G license required.

Request

path parameters
parameter	type	description
nodeId	int	the oxe pbx node
registerId	string	the DR link identifier
deviceNumber	string	the recorded device number

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	media types	description
204	application/json	No content
400	application/json	Bad Request
403	application/json	Forbidden
404	application/json	Not Found
500	application/json	Internal Server Error
503	application/json	Service Unavailable

Examples

[+] : Stop the current record of the device 70120 on the node 7 through the recorder link 123456.

/iprecord/{nodeId}/link/{registerId}/tdmrecord

Methods

Start an TDM record of a device through a PCM link.

Licenses

No O2G license required.

Request

path parameters
parameter	type	description
nodeId	int	the oxe pbx node
registerId	string	the DR link identifier

cookie parameters
parameter	type	description
AlcUserId	string	Identifier of the Session

body parameter
type	media types	description
StartTDMRecordRequest		specifies the device number to record, the PCM resource used (crystal number/ board number/ time slot between 1..30)

Response

code	media types	description
204	application/json	No content
400	application/json	Bad Request
403	application/json	Forbidden
404	application/json	Not Found
500	application/json	Internal Server Error
503	application/json	Service Unavailable

Examples

[+] : Start an TDM record of the device 70120 on the node 7 through the recorder link 123456 on the PCM time slot 2/0/10.

Representations

boolean

'boolean' is a data type, having two values (true and false).

DeviceMonitored

In response of the monitor start request of a device, contains the user selector identifier to use for the telephony event subscription.

If the device (for example number = "5000") is the main device of the oxe subscriber (or if the subscriber is mono device), the userId will be "oxe5000"
If the device (for example number = "5001") is one of the secondary devices of a multi-device oxe subscriber (number = "5000"), the userId will be "oxe5000"
If several devices have been monitored in the same time, the response contains the userDeviceIds list of response.

Name	Type	Cardinality	Description
userId	string	[0..1]	user identifier for telephony event subscription
userDeviceIds	UserDevice	[0..*]	Since version 2.7.3 When several devices are monitored at a time: List of pair result. userId and userDeviceIds are exclusive

[+] : JSON Example

{
   "userId": "string",
   "userDeviceIds": [ {
      "userId": "string",
      "deviceId": "string"
   } ]
}

Associated method :

POST /iprecord/{nodeId}/link/{registerId}/monitor

DRLink

CSTA DR link.

Name	Type	Cardinality	Description
identifier	string	[1]	DR link Registration identifier
initiator	string	[1]	Since version 2.7.3 DR link initiator identifier (application name)
nbRecordedDevices	int	[0..1]	number of recorded devices
recordedDevices	RecordedDevice	[0..*]	list of recorded devices

[+] : JSON Example

{
   "identifier": "string",
   "initiator": "string",
   "nbRecordedDevices": int,
   "recordedDevices": [ {
      "number": "string",
      "user": "string",
      "crid": "string",
      "recorded": boolean,
      "recordingResource": "string",
      "ip": boolean,
      "sentFlowPort": int,
      "receivedFlowPort": int,
      "encrypted": boolean
   } ]
}

DRLinks

List of existing DRLinks for a pbx

Name	Type	Cardinality	Description
drLinks	DRLink	[0..*]	In case of IP recording, list of drLinks

[+] : JSON Example

{
   "drLinks": [ {
      "identifier": "string",
      "initiator": "string",
      "nbRecordedDevices": int,
      "recordedDevices": [ {
         "number": "string",
         "user": "string",
         "crid": "string",
         "recorded": boolean,
         "recordingResource": "string",
         "ip": boolean,
         "sentFlowPort": int,
         "receivedFlowPort": int,
         "encrypted": boolean
      } ]
   } ]
}

Associated method :

GET /iprecord/{nodeId}/link

int

'int' is a 32-bit number (-2147483648 to 2147483647).

IPRecorderType

Type of IP recorder: NICE or other

Value	Description
NICE	NICE recorder type
OTHER	other recorder type

MonitorRequest

Request to start/stop the monitoring of a device on a drLink

Name	Type	Cardinality	Description
deviceNumber	string	[0..1]	device number to be monitored on the drLink for recording
deviceNumbers	string	[0..*]	Since version 2.7.3 Several devices may be monitored at a time: List of numbers to be monitored. All the devices must exist else the request will fail. If the parameter deviceNumbers is not null, the parameter deviceNumber is ignored

[+] : JSON Example

{
   "deviceNumber": "string",
   "deviceNumbers": [ "string" ]
}

Associated method :

POST /iprecord/{nodeId}/link/{registerId}/monitor

RecordedDevice

Recorded device identification with it recording resource

Name	Type	Cardinality	Description
number	string	[0..1]	device number
user	string	[0..1]	device user
crid	string	[0..1]	device csta crid
recorded	boolean	[0..1]	has the recording been asked
recordingResource	string	[0..1]	recorder IP address or TDM time slot
ip	boolean	[0..1]	Is an IP recording
sentFlowPort	int	[0..1]	In case of IP recording, the recorder port where is sent the sent RTP flow(from the local recorded device to the remote)
receivedFlowPort	int	[0..1]	In case of IP recording, the recorder port where is sent the received RTP flow(from the remote to the local recorded device)
encrypted	boolean	[0..1]	In case of IP recording, if it is encrypted)

[+] : JSON Example

{
   "number": "string",
   "user": "string",
   "crid": "string",
   "recorded": boolean,
   "recordingResource": "string",
   "ip": boolean,
   "sentFlowPort": int,
   "receivedFlowPort": int,
   "encrypted": boolean
}

RecordingSrtpKeys

Contains the Secured RTP key, salt key and ciphersuite in response of the start IP record on an secured IP link.

Name	Type	Cardinality	Description
key	string	[0..1]	the Master key recorder
salt	string	[0..1]	the Master salt key recorder
cipherSuite	string	[0..1]	Since version 2.7.2 the cipher suite (if absent, default compatibility is AES-CM-128-HMAC-SHA1-80 without authentication)

[+] : JSON Example

{
   "key": "string",
   "salt": "string",
   "cipherSuite": "string"
}

Associated method :

POST /iprecord/{nodeId}/link/{registerId}/record

RegisterServiceRequest

Request of register an IP recorder on a pbx node.
The type of recorder may be specified: NICE or other (default).
The recorder may ask to work in secured or unsecured mode:

default mode is according to oxe recording configuration.
typically, if oxe recording configuration is secured, but the register application doesn't support this mode, then it must explicitly specified "secured=false".
if oxe recording configuration is not secured but if the register application explicitly asks "secured=true", the request will be accepted but the response will return "secured=false".

Name	Type	Cardinality	Description
type	IPRecorderType	[0..1]	type of the recorder: (default is "other than NICE")
secured	boolean	[0..1]	optional secured mode(default=according to oxe): should be explicitely used ("secured=false") to disable the secured mode on the drlink if not supported by the recorder. If the parameter is absent, it will follow the OXE configuration.

[+] : JSON Example

{
   "type": "NICE | OTHER",
   "secured": boolean
}

Associated method :

POST /iprecord/{nodeId}/link

ServiceRegistered

Contains the identifier of the recorder registration on the pbx node, to be used to unregister the service. Also specifies whether the connection is secure or not

Name	Type	Cardinality	Description
registrationId	string	[1]	registration identifier
secure	boolean	[0..1]	is the connection secure

[+] : JSON Example

{
   "registrationId": "string",
   "secure": boolean
}

Associated method :

POST /iprecord/{nodeId}/link

StartBeepRequest

Request to generate a beep tone on a device

Name	Type	Cardinality	Description
deviceNumber	string	[1]	device number
tone	int	[1]	tone or frequency to connect: this parameter identifies the time slot number defined in the OXE tones table, which is specific for each country; in practice, only values 21 to 30 are usable
presenceDuration	int	[1]	presence duration of the pulse : 0 to 255 (value must be specified in step of 10ms, from 10 millisecondes to 2,5 secondes)
silenceDuration	int	[1]	silence duration between two pulses : 0 to 255 (value must be specified in step of 1s, from 1 seconde to 255 secondes)

[+] : JSON Example

{
   "deviceNumber": "string",
   "tone": int,
   "presenceDuration": int,
   "silenceDuration": int
}

Associated method :

POST /iprecord/{nodeId}/link/{registerId}/beep

StartRecordRequest

Request to start an IP record of a device

Name	Type	Cardinality	Description
deviceNumber	string	[1]	device number to record (must correspond to an O2G monitored user)
ipRecorderAddr	string	[1]	IP V4 address of the recorder (aaa.bbb.ccc.ddd)
sentFlowPort	int	[1]	The recorder port where to send the sent RTP flow(from the local recorded device to the remote)
receivedFlowPort	int	[1]	The recorder port where to send the received RTP flow(from the remote to the local recorded device)

[+] : JSON Example

{
   "deviceNumber": "string",
   "ipRecorderAddr": "string",
   "sentFlowPort": int,
   "receivedFlowPort": int
}

Associated method :

POST /iprecord/{nodeId}/link/{registerId}/record

StartTDMRecordRequest

Request to start an TDM record of a device

Name	Type	Cardinality	Description
deviceNumber	string	[1]	device number to record (must correspond to an O2G monitored user)
crystal	int	[1]	PCM crystal number
board	int	[1]	PCM board number
timeslot	int	[1]	PCM timeslot number

[+] : JSON Example

{
   "deviceNumber": "string",
   "crystal": int,
   "board": int,
   "timeslot": int
}

Associated method :

POST /iprecord/{nodeId}/link/{registerId}/tdmrecord

string

'string' represents character strings.

UserDevice

Name	Type	Cardinality	Description
userId	string	[0..1]
deviceId	string	[0..1]

[+] : JSON Example

{
   "userId": "string",
   "deviceId": "string"
}

O2G 2.7.4RECORDING REST API

Introduction

Presentation

Overview

Vocabulary

History

Change logs

Authentication mechanism

Authentication for an administrator

Authentication for an user : Secure Access

Session creation

O2G Services Through Websocket

Error management

Representations

Authentication

Presentation

Authentication for an administrator

Authentication for an user : Secure Access

Resource summary

Resource

/authenticate

Methods

Licenses

Request

Response

Examples

Representations

Session management

Presentation

Resources summary

Resources

/sessions

Methods

Licenses

Request

Response

Licenses

Request

Response

Examples

Licenses

Request

Response

/sessions/keepalive

Methods

Licenses

Request

Response

Examples

Representations

User information

Presentation

Resources summary

Notifications summary

Resources

/logins

Methods

Licenses

Request

Response

Examples

/users

Methods

Licenses

Request

Response

Examples

/users/{loginName}

Methods

Licenses

Request

Response

Examples

Associated notifications

/users/{loginName}/password

Methods

Licenses

Request

Response

Representations

O2G 2.7.4
RECORDING REST API