Introduction
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 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"
}]
}
History
2.7.1
- modified feature 'Call control'
- added in representation 'CallData' :
2.7
- modified feature 'Session management'
- added in representation 'SessionInfo' :
- creationDate
- otherSessions
- modified feature 'User information'
- added in representation 'User' :
- modified feature 'Maintenance'
2.6
- modified feature 'Voice Recording'
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 login is:
- For a user, the QMCDU of the OXE subscriber prefixed by "oxe" (Ex: oxe70120)
- For an administrator, a login found (managed) in the configuration file
The password is:
- For a user, the secret code of the OXE subscriber
- For an administrator, a password found (managed) in the configuration file
The credentials (login and password) are first checked to see if they correspond to an O2G administrator or an OXE subscriber.
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
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"
}
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:
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).
Here is the Ws protocol map:
Example of request/response for authentication through WS protocol:
Example of request/response for subscription through WS protocol:
Example of event through WS protocol:
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 administrator 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 administrator 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 administrator 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).
HttpStatusint'int' is a 32-bit number (-2147483648 to 2147483647).
ProductVersionGive 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. |
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
} |
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. |
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. |
'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. |
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).
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 10 minutes 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
Resources
/subscriptions
Methods
Create a subscription for event notification.
Licenses
No O2G license required.
Request
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | The user framework session Identifier, received as a cookie. |
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.
request :POST https://server/api/rest/1.0/subscriptions
Content-Type: application/json
{
"filter":{"selectors":[
{"ids":["*"],"names":["telephony"],"families":[],"origins":[]}
},
"sessionId":"...2303639373638343","version":"1.0",
"timeout":60
}
}response : [+] : Create a subscription to system event package.
request :POST https://server/api/rest/1.0/subscriptions
Content-Type: application/json
{
"filter": {
"selectors": [
{"names": [ "system" ]}
]
},
"version":"1.0"
}response : [+] : Create a subscription to pilot and rsi event packages.
request :POST https://server/api/rest/1.0/subscriptions
Content-Type: application/json
{
"filter": {
"selectors": [
{"ids": [ "60141" ],"names": [ "pilot"]},
{"ids": [ "65000" ],"names": [ "rsi"]}
]
},
"version":"1.0"
}response : Associated notifications
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.
request :PUT https://server/api/rest/1.0/subscriptions
Content-Type: application/json
{
"selectors":[
{"ids":["userA","userB"],"names":["telephony"]},
{"ids":["userA","userB"],"names":["eventSummary"]}
]
}response :204 No Content
/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.
request :DELETE https://server/api/rest/1.0/subscriptions/...35373132393
response :204 No Content
Representations
FilterHigh level container of event selector.
| Name | Type | Cardinality | Description |
|---|
| selectors | Selector | [0..*] | List of selectors. |
[+] : JSON Example{
"selectors": [ {
"ids": [ "string" ],
"names": [ "string" ]
} ]
} |
Associated method :
'int' is a 32-bit number (-2147483648 to 2147483647).
SelectorA 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. |
'string' represents character strings.
SubscriptionContains 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 :
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 :
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
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
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 |
/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 |
/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
Representations
AcdCallDataDescribes 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 | ..."
}
} |
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' is a data type, having two values (true and false).
CallDescribes 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"
},
"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"
},
"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 :
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. |
| 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 | |
Describes data associated to a call.
| Name | Type | Cardinality | Description |
|---|
| initialCalled | PartyInfo | [0..1] | Initial user called for this call. |
| 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"
},
"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 ]
}
} |
Container for the calls.
| Name | Type | Cardinality | Description |
|---|
| calls | Call | [0..*] | List of call |
[+] : JSON Example{
"calls": [ {
"callRef": "string",
"callData": {
"initialCalled": {
"id": {
"loginName": "string",
"phoneNumber": "string"
},
"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"
},
"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 :
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. |
Describes a user's device state.
[+] : JSON Example{
"deviceId": "string",
"state": "IN_SERVICE | OUT_OF_SERVICE | UNKNOWN"
} |
Associated method :
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"
} ]
} |
Associated method :
Key information to help retrieving a participant.
| Name | Type | Cardinality | Description |
|---|
| loginName | string | [0..1] | Login name. |
| phoneNumber | string | [0..1] | Company phone number. |
'int' is a 32-bit number (-2147483648 to 2147483647).
LegDescribes 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
} |
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. |
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). |
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"
},
"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"
},
"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 :
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"
},
"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"
},
"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"
},
"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 :
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
} ]
} |
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"
} ]
} |
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"
},
"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"
},
"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 :
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 :
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. |
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"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"anonymous": boolean,
"undroppable": boolean,
"state": "RINGING_INCOMING | ACTIVE"
} |
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"
} |
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"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
} |
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 | |
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 | ..."
} |
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. |
Lists the different state when recording.
| Value | Description |
|---|
| PAUSED | Recording is paused. |
| RECORDING | Recording is in progress. |
'string' represents character strings.
TagDescribes 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. |
Snapshot of the user's telephonic state.
| Name | Type | Cardinality | Description |
|---|
| calls | Call | [0..*] | Gives the 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"
},
"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"
},
"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 :
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 ]
} |
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
Notification summary
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
request :GET https://server/api/rest/1.0/acd/agent/state
response :200 OK
{"mainState":"LOGGED_ON","subState":"IDLE", "proAcdDeviceNumber": "1002",
"pgGroupNumber": "5001"} [+] : Get the agent state of an agent loged off
request :GET https://server/api/rest/1.0/acd/agent/state
response :200 OK
{"mainState":"LOGGED_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
Representations
AgentMainStateMain 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 |
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 :
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 | |
| WRAPUP_EMAIL | |
| WRAPUP_EMAIL_INTERRUPTIBLE | |
| WRAPUP_OUTBOUND | |
| WRAPUP_CALLBACK | |
'boolean' is a data type, having two values (true and false).
int'int' is a 32-bit number (-2147483648 to 2147483647).
OnAgentStateChangedEvent 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 :
'string' represents character strings.
Voice Recording
Presentation
The Recording service allows a recorder application to record voice of OXE devices, either in IP or TDM mode.
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.
- 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": "PbxManagement",
"serviceVersion": "1.0",
"relativeUrl": "/pbxs"
},
{
"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
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.
request :GET https://server/api/rest/1.0/iprecord/7/link
response :200 OK
{
"drLinks":[
{
"identifier": "07000b03",
"nbRecordedDevices": 1,
"recordedDevices":[
{"number": "76001", "recordingResource": "135.118.230.179", "ip": true}
]
}
]
} 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.
request :POST https://server/api/rest/1.0/iprecord/7/link
{
"type": "OTHER"
}response :200 OK
{
"registrationId": "123456",
"secure": false
} [+] : Register a NICE recorder link on the pbx 7. The link is secure
request :POST https://server/api/rest/1.0/iprecord/7/link
{
"type": "NICE"
}response :200 OK
{
"registrationId": "123456",
"secure": true
} /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.
request :DELETE https://server/api/rest/1.0/iprecord/7/link/123456
response :204 No Content
/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
request :POST https://server/api/rest/1.0/iprecord/7/link/123456/beep
{
"deviceNumber" : "70120",
"tone" : "25",
"presenceDuration" : "50",
"silenceDuration" : "10"
}response :204 No Content
/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
request :DELETE https://server/api/rest/1.0/iprecord/7/link/123456/beep/70120
response :204 No Content
/iprecord/{nodeId}/link/{registerId}/monitor
Methods
Start the monitoring of a device on a drLink.
This action MUST be done prior to ask the recording of the device.
A user identifier is returned back, 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 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.
request :POST https://server/api/rest/1.0/iprecord/7/link/123456/monitor
{
"deviceNumber" : "70120"
}response :200 OK
{
"userId": "oxe70120"
} [+] : Start to monitor the tandem device 70124 of the main user 70123 on the node 7 through the recorder link 123456.
request :POST https://server/api/rest/1.0/iprecord/7/link/123456/monitor
{
"deviceNumber" : "70124"
}response :200 OK
{
"userId": "oxe70123"
} /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.
request :DELETE https://server/api/rest/1.0/iprecord/7/link/123456/monitor/70120
response :204 No content
/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.
request :POST https://server/api/rest/1.0/iprecord/7/link/123456/record
{
"deviceNumber" : "70120",
"ipRecorderAddr" : "aaa.bbb.ccc.ddd",
"sentFlowPort" : "xxxx",
"receivedFlowPort" : "yyyy"
}response :200 OK
{
} [+] : 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 enabled:A SRTP key/salt pair is returned.
request :POST https://server/api/rest/1.0/iprecord/7/link/123456/record
{
"deviceNumber" : "70120",
"ipRecorderAddr" : "aaa.bbb.ccc.ddd",
"sentFlowPort" : "xxxx",
"receivedFlowPort" : "yyyy"
}response :200 OK
{
"key": "7796134dbb60ef98df33fbf46d09c7c1ceb1",
"salt": "19272df3b057d235cdb8afa8b41a82c6"
} /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.
request :DELETE https://server/api/rest/1.0/iprecord/7/link/123456/record/70120
response :204 No Content
/iprecord/{nodeId}/link/{registerId}/tdmrecord
Methods
Start an TDM record of a device through a PCM link.
History
Since version 2.6
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.
request :POST https://server/api/rest/1.0/iprecord/7/link/123456/tdmrecord
{
"deviceNumber" : "70120",
"crystal" : "2",
"board" : "0",
"timeslot" : "10"
}response :204.doc No content
Representations
boolean'boolean' is a data type, having two values (true and false).
DeviceMonitoredIn 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"
| Name | Type | Cardinality | Description |
|---|
| userId | string | [1] | user identifier for telephony event subscription |
Associated method :
CSTA DR link.
| Name | Type | Cardinality | Description |
|---|
| identifier | string | [1] | DR link Registration identifier |
| nbRecordedDevices | int | [0..1] | number of recorded devices |
| recordedDevices | RecordedDevice | [0..*] | list of recorded devices |
[+] : JSON Example{
"identifier": "string",
"nbRecordedDevices": int,
"recordedDevices": [ {
"number": "string",
"recorded": boolean,
"recordingResource": "string",
"ip": boolean,
"sentFlowPort": int,
"receivedFlowPort": int
} ]
} |
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",
"nbRecordedDevices": int,
"recordedDevices": [ {
"number": "string",
"recorded": boolean,
"recordingResource": "string",
"ip": boolean,
"sentFlowPort": int,
"receivedFlowPort": int
} ]
} ]
} |
Associated method :
'int' is a 32-bit number (-2147483648 to 2147483647).
IPRecorderTypeType of IP recorder: NICE or other
| Value | Description |
|---|
| NICE | NICE recorder type |
| OTHER | other recorder type |
Request to start/stop the monitoring of a device on a drLink
| Name | Type | Cardinality | Description |
|---|
| deviceNumber | string | [1] | device number to monitor on the drLink for recording |
Associated method :
Recorded device identification with it recording resource
| Name | Type | Cardinality | Description |
|---|
| number | string | [0..1] | device number |
| 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) |
Contains the Secured RTP key and salt in response of the start IP record on an secured IP link.
| Name | Type | Cardinality | Description |
|---|
| key | string | [0..1] | key |
| salt | string | [0..1] | salt |
Associated method :
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 :
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 |
Associated method :
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 :
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 :
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 :
'string' represents character strings.
