Introduction
Overview
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
OTRestApiDescriptor.
http(s)://<host>:<port>/api/rest
Example of response :
{
"serverInfo": {
"productName": "OpenTouch Multimedia Solution",
"productType": "OTMS",
"productVersion": {
"major": "2.2",
"minor": "000.041"
},
"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.6
- modified feature 'Directory search'
- added methods :
- Retrieves the list of the available attributes
- Gets the properties of a specified attribute
- added in representation 'Attribute' :
- FULLNAME
- MOBILEPHONE
- attribute1
- attribute2
- attribute3
- attribute4
- attribute5
- IMPP
- OTNODE
- VCARD
- PHOTO
- UNKNOWN
- added in representation 'PartyInfo' :
- photo
- fullName
- attribute1
- attribute2
- attribute3
- attribute4
- attribute5
- mobilePhone
- otNode
- added in representation 'SearchRequest' :
- mandatoryAttributes
- attributes
2.5
- modified feature 'User information'
- added in representation 'User' :
- salutation
- site
- department
- customAttributes
- added in representation 'UserPreferences' :
- modified feature 'Call control'
- added methods :
- Activate/deactivate ringing of a device
- added notifications :
- OnCallAppeared
- OnCallbackRequestAdded
- OnDeviceMuteFailed
- OnDeviceMuteSuccess
- added in representation 'DeviceState' :
- modified feature 'Communication log'
- added in representation 'Participant' :
2.4
- modified feature 'Groups'
- added notifications :
- added in representation 'GroupMemberRole' :
- added in representation 'GroupType' :
2.3.1
- modified feature 'Subscription management'
- added in representation 'SubscriptionRequest' :
- modified feature 'Communication log'
- added in notification 'OnComRecordCreated' :
- modified feature 'Messaging'
- added in notification 'OnMessageAdded' :
2.3
- modified feature 'Communication log'
2.2.1
- modified feature 'User information'
- added methods :
- Find information about a user
- Change user's password
- modified feature 'Call control'
- added methods :
- modified methods :
- Make a call
- added parameter 'loginName'
- added in representation 'CallCause' :
- modified feature 'Messaging'
- added methods :
- Forward an existing message
2.2
- modified feature 'User information'
- added in representation 'User' :
- vcardPath
- applicationRights
- sipUri
- added in representation 'Voicemail' :
- modified feature 'Subscription management'
- added in representation 'NotificationMode' :
- modified feature 'Call control'
- added in representation 'PartyInfo' :
- modified feature 'Directory search'
- added in representation 'PartyInfo' :
- modified feature 'Presence'
- added methods :
- Get the user's calendar presence
- Set the user's calendar presence
- added in representation 'Presence' :
- added feature 'Conference'
2.1.1
- modified feature 'User information'
- modified methods :
- Get user(s) logins
- added parameter 'types'
- added parameter 'apiRights'
- added notifications :
- OnUserCreated
- OnUserDeleted
- added in representation 'UserRight' :
- added in representation 'User' :
- modified feature 'Call control'
- added methods :
- Returns the whole list of callback requests
- Delete all callback requests
- Delete a specific callback request
- Request for call back
- modified feature 'Communication log'
- modified methods :
- Get records
- added parameter 'optimized'
- added feature 'Instant Messaging'
- added feature 'Presence'
- added feature 'Groups'
2.1
- modified feature 'Introduction'
- added in representation 'OTRestApiDescriptor' :
- modified feature 'Session management'
- added in representation 'SessionInfo' :
- modified feature 'User information'
- added methods :
- Get user's telephony preferences
- Set user's telephony preferences
- added notifications :
- added in representation 'TelephonyPreferences' :
- added in representation 'User' :
- added in representation 'UserPreferences' :
- modified feature 'Subscription management'
- added in representation 'SubscriptionRequest' :
- modified feature 'Call control'
- added methods :
- Make a canonical phone number
- Make a dialable phone number
- added in representation 'Participant' :
- modified feature 'Routing management'
- added in representation 'DestinationType' :
- added in representation 'ApplyProfileRoutesRequest' :
- added in representation 'ForwardRoute' :
- added in representation 'RoutingState' :
- appliedProfile
- activableProfiles
- currentDeviceId
- added in representation 'SetOverflowRoutesRequest' :
- added in representation 'SetRoutesRequest' :
2.0.2
- modified feature 'Directory search'
- added in representation 'SearchRequest' :
2.0.1
- added feature 'Communication log'
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
Several types of authentication are available on the OpenTouch platform :
- Internal
- Ldap
- Radius
- Kerberos
- Cas
When authentication is successful the third party application gets a token in the HTTP response (A cookie named
"AlcUserId").
Caution: This token must be put in each request to API resources to identify the user/administrator involved.
This token will be passed in the dedicated cookie named
"AlcUserId".
If the token is not present or is not valid an HTTP response 403 (Forbidden) will be returned.
Note: The OpenTouch server can be configured to use Kerberos or Cas authentication.
If your application doesn't support this type of authentication, a dedicated ressource is provided to perform
a basic authentication using username and password:
http(s)://<host>:<port>/api/rest/authenticatenosso?version=1.0
In that case, authentication will be done against the OpenTouch system itself (Internal account), an external LDAP server or an external RADIUS server according to the OpenTouch configuration.
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
Response :
401 UNAUTHORIZED
Request :
GET https://server/authenticationbasic/login?AlcApplicationUrl=/api/rest/authenticate?version=1.0
Response :
200 OK
Content-Type: application/json
{
"credential" : "...7363838302538383139383434353137303538353934363",
"publicUrl" : "https://public-server/api/rest/1.0/sessions",
"internalUrl" : "https://server/api/rest/1.0/sessions"
}
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
}
HA : High Availability
Introduction
The HA solution is based on the redundancy of the server in a Primary/Secondary server pair.
The OTMC operates in association with an OmniPCX Enterprise, which can itself be redundant.
The redundant server pair must be deployed on the same subnetwork.
Switch over is triggered by the following events:
- Software failure
- Operating system crash
- Server hardware failure
- Network disconnection (split brain)
Services FQDNs are used so that application can join OT services through the same FQDN, regardless of which server is active.
Service continuity
After a switching, a call in progress is not broken, but all the signaling associated with this telephonic context is lost.
The application must to make a new login in as soon as OpenTouch services are available, to create a new session in the active server.
Caution, it takes a few minutes, after a switching for the new server to be active.
Here the reference of the official documentations : 8AL90123USAC (OTMC) and 8AL90123USAC (OTMS)
Client code samples
Representations
boolean'boolean' is a data type, having two values (true and false).
HttpStatusint'int' is a 32-bit number (-2147483648 to 2147483647).
OTRestApiDescriptorHigh level information of the server and supported REST API versions.
| Name | Type | Cardinality | Description |
|---|
| serverInfo | ServerInfo | [0..1] | Since version 2.1 Provide extra information about the server hosting the REST API. |
| versions | Version | [1..*] | List of the versions supported on the server. |
Give information about the version installed on the server.
| Name | Type | Cardinality | Description |
|---|
| major | string | [0..1] | Major version of the product.
This field should help to identify the release of a product. |
| minor | string | [0..1] | Minor revision of the product.
This field is for internal needs. |
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
} |
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. |
Session management
Resources summary
Resources
/sessions
Methods
Gets information of the opened session.
Licenses
No license required.
Request
query parameters| parameter | type | description |
|---|
| applicationName | string | |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
| code | type | media types | description |
|---|
| 200 | SessionInfo | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Open a session for a user or an administrator. This is the first thing to do
before invoking any others resources. The user or the administrator is identified by its authentication token.
This one must be provided as a cookie for each request to the server. This token is obtained after a successful authentication
(See
Authentication mechanism chapter)
A session can be opened only once (same authentication token), if the session is already open an error is returned (Forbidden).
In each case, the obtained reference to the Session must be
released using the logout operation (DELETE).
The Session is closed either after the reference has been released (after
a call to the DELETE operation) or after the session timer ends.
The session timer can be managed through this service (HEAD operation).
It conveys this token as a cookie which will be used to
identify the previously authenticated user.
3 types of Sessions exist:
User Session
The credential (cookie) used to open the session, is the one of a
User. In case of success, this credential will be used to
identify the Session and the User. This Session allows a User to use any
other service
(according the User's rights)
.
Administrator Session
The credential (cookie) used to open the session, is the one of a
Administrator. In case of success, this credential will be used
to identify the Session and the Administrator. This
Session allows a Administrator to use any other services
(according the Administrator's rights)
.
A Administrator Session can also be used by an
Application (as an Application account) to supervise several Users in a same Session.
Such a session allows an Application to use the User oriented services
(according to the supervised user's rights)
.
Supervised Session
This kind of Session is opened thanks to the supervisor
operation. This operation uses the credential of a Administrator
(with supervisor role) and the identification of a User or another
Administrator (login name, phone number or e-mail) to open the Session.
In case of success, this credential will be used in all subsequent requests,
to identify the Session, and the supervised User or Administrator.
After the session opening, a Supervised Session can be used like a
User Session or a Administrator Session (described
above). In other words, this Session allows a Supervisor to use
any other services
(according the supervised User's rights)
as if it was opened by the User or Administrator
Licenses
No license required.
Request
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
body parameter| type | media types | description |
|---|
| SessionRequest | application/json
| This element is used to open a Session. |
Response
| code | type | media types | description |
|---|
| 200 | SessionInfo | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Examples
[+] : Creation of a user session
request :POST https://server/api/rest/1.0/sessions
Content-Type: application/json
{
"applicationName":"TESTS_API"
}response :200 OK
Content-Type: application/json
{
"timeToLive": 1800,
"publicBaseUrl": "http://public-server/api/rest/1.0",
"privateBaseUrl": "https://server/api/rest/1.0",
"services": [
{
"serviceName": "Users",
"serviceVersion": "1.0",
"relativeUrl": "/users"
},
{
"serviceName": "Telephony",
"serviceVersion": "1.0",
"relativeUrl": "/telephony/calls"
},
{
"serviceName": "Logins",
"serviceVersion": "1.0",
"relativeUrl": "/logins"
},
{
"serviceName": "Devices",
"serviceVersion": "1.0",
"relativeUrl": "/telephony/devices"
},
{
"serviceName": "State",
"serviceVersion": "1.0",
"relativeUrl": "/telephony/state"
},
{
"serviceName": "Directory",
"serviceVersion": "1.0",
"relativeUrl": "/directory"
},
{
"serviceName": "EventSummary",
"serviceVersion": "1.0",
"relativeUrl": "/eventSummary"
},
{
"serviceName": "Routing",
"serviceVersion": "1.0",
"relativeUrl": "/routing"
},
{
"serviceName": "Subscriptions",
"serviceVersion": "1.0",
"relativeUrl": "/subscriptions"
},
{
"serviceName": "Comlog",
"serviceVersion": "1.0",
"relativeUrl": "/comlog/records"
}
],
"capabilities": [
"BASIC_TELEPHONY",
"ADVANCED_TELEPHONY"
]
} [+] : Creation of an administrator session
request :POST https://server/api/rest/1.0/sessions
Content-Type: application/json
{
"applicationName":"TESTS_API"
}response :200 OK
Content-Type: application/json
{
"timeToLive":"1800",
"publicBaseUrl":"https://public-server/api/rest/1.0",
"privateBaseUrl":"https://server/api/rest/1.0",
"Services":
[
{
"serviceName":"Users",
"serviceVersion":"1.0",
"relativeUrl":"/logins"
},
.....
{
"serviceName":"Telephony",
"serviceVersion":"1.0",
"relativeUrl":"/telephony/calls"
}
],
"Capabilities":
[
"BASIC_TELEPHONY",
"ADVANCED_TELEPHONY"
]
} [+] : Creation of a supervised user session
request :POST https://server/api/rest/1.0/sessions
Content-Type: application/json
{
"applicationName":"TESTS_API",
"supervisedAccount":
{
"id":"icm32539",
"type":"LOGIN_NAME"
}
}response :200 OK
Content-Type: application/json
{
"timeToLive":"1800",
"publicBaseUrl":"https://public-server/api/rest/1.0",
"privateBaseUrl":"https://server/api/rest/1.0",
"Services":
[
{
"serviceName":"Users",
"serviceVersion":"1.0",
"relativeUrl":"/logins"
},
.....
{
"serviceName":"Telephony",
"serviceVersion":"1.0",
"relativeUrl":"/telephony/calls"
}
],
"Capabilities":
[
"BASIC_TELEPHONY",
"ADVANCED_TELEPHONY"
]
} Closes a Session.
When the Session is closed (following the call to this operation or due to a session time out),
all license references are released and all services sessions are closed.
Licenses
No license required.
Request
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
| code | media types | description |
|---|
| 204 | application/json
| No Content (The session is closed) |
| 400 | application/json
| Bad Request |
| 403 | application/json
| Forbidden (The session is already closed) |
| 500 | application/json
| Internal Server Error (The session doesn't exist) |
| 503 | application/json
| Service Unavailable |
/sessions/keepalive
Methods
Restarts the session timer.
To keep the session open, if there is no request before session timeout.
Each Session is limited in time.
By default, the duration of a Session is the one defined in administration.
Each time a Session is used the session timer is automatically restarted.
Licenses
No license required.
Request
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
| code | media types | description |
|---|
| 204 | application/json
| No Content (The session timer has been correctly refreshed) |
| 400 | application/json
| Bad Request |
| 403 | application/json
| Forbidden (The session doesn't exist) |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
/sessions/release
Methods
Allows current session to be released. It means that the session can be acquired by another user.
Applicable for applications with only single simultaneous session allowed.
Licenses
No license required.
Request
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | |
body parameter| type | media types | description |
|---|
| string | text/plain
| |
Response
| code | media types | description |
|---|
| 200 | application/json
| OK |
| 400 | application/json
| Bad Request |
| 403 | application/json
| Forbidden |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Examples
[+] : Allow current session to be released.
request :POST https://server/api/rest/1.0/sessions/release
Content-Type: raw
Body-content: true
response :200 OK
Representations
boolean'boolean' is a data type, having two values (true and false).
int'int' is a 32-bit number (-2147483648 to 2147483647).
ServiceThis value contains all available information about a local service.
| Name | Type | Cardinality | Description |
|---|
| serviceName | string | [1] | This value contains the name of the service. |
| serviceVersion | string | [0..1] | This value contains the version of the service, which allows an application to check its compatibility with the service. |
| relativeUrl | string | [1] | This value contains the relative URL of the service, which allows a consumer to access it. |
Session information.
| Name | Type | Cardinality | Description |
|---|
| admin | boolean | [0..1] | Since version 2.1 Indicate if the session has been opened by an administrator. |
| timeToLive | int | [0..1] | The duration of the Session in seconds. |
| publicBaseUrl | string | [0..1] | This value contains the public base URL which must be used by a consumer to access services from the Internet. |
| privateBaseUrl | string | [1] | This value contains the private base URL of the service, which must be used by a consumer to access services from a local network. |
| services | Service | [0..*] | All information available about the local services provided by public API for the current user. |
| capabilities | string | [0..*] | The capabilities of the current user : licenses, rights). |
Associated methods :
This element is used to open a
Session.
| Name | Type | Cardinality | Description |
|---|
| applicationName | string | [1] | Application name to check the rights or to take a particular license. |
| applicationAddress | string | [0..1] | Application address. |
| supervisedAccount | SupervisedAccount | [0..1] | Identifier used to retrieve the supervised user (Administrator authentication but user session). |
[+] : JSON Example{
"applicationName": "string",
"applicationAddress": "string",
"supervisedAccount": {
"id": "string",
"type": "LOGIN_NAME | PHONE_NUMBER | EMAIL | INSTANT_MESSAGING_ID"
}
} |
Associated method :
'string' represents character strings.
SupervisedAccountThe supervised user description.
| Name | Type | Cardinality | Description |
|---|
| id | string | [1] | The identifier itself. The type of this value is given by the SupervisedAccountType attribute. |
| type | SupervisedAccountType | [1] | Gives the type of the identifier. |
[+] : JSON Example{
"id": "string",
"type": "LOGIN_NAME | PHONE_NUMBER | EMAIL | INSTANT_MESSAGING_ID"
} |
The supervised account type values.
| Value | Description |
|---|
| LOGIN_NAME | The identifier is a login name. |
| PHONE_NUMBER | The identifier is a phone number. |
| EMAIL | The identifier is an email. |
| INSTANT_MESSAGING_ID | The identifier is an instant messaging id. |
User information
Resources summary
Notifications summary
| Notification | Description |
|---|
| OnPreferencesChanged | This event is sent on any change on the user's preferences. |
| OnUserCreated |
This event is sent on creation of an user (only for administrator). |
| OnUserDeleted |
This event is sent when user is deleted (only for administrator). |
| OnUserInfoChanged | This event is sent on any change on the user's data. |
Resources
/logins
Methods
An administrator can get the list of the users (login name).
For a user, only personal information (login name) is returned.
Licenses
No license required.
Request
query parameters| parameter | type | description |
|---|
| types | string | Since version 2.1.1 This parameter is optional (Note: this parameter can be only used by an administrator).
This is a search criterion, 2 values are available: STANDARD and MULTIMEDIA. |
| apiRights | string | Since version 2.1.1 This parameter is optional (Note: this parameter can be only used by an administrator).
This is a search criterion, 3 values are available: TELEPHONY_BASIC, TELEPHONY_ADVANCED and MESSAGING. |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
| code | type | media types | description |
|---|
| 200 | LoginsResponse | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Examples
[+] : Get information with a user role.
The session was opened by a user.
request :GET https://server/api/rest/1.0/logins
response :200 OK
Content-Type: application/json
{
{"loginNames":["icm32539"]}
} [+] : Get all user's logins with an administrator role.
The session was opened by a administrator.
request :GET https://server/api/rest/1.0/logins
response :200 OK
Content-Type: application/json
{
{"loginNames":["icm32539","icm32540","icm32541","icm32542","icm32543","oxe70020","oxe70021","oxe70022"]}
} [+] : Get STANDARD user's logins.
The session was opened by a administrator.
request :GET https://server/api/rest/1.0/logins?types=STANDARD
response :200 OK
Content-Type: application/json
{
{"loginNames":["oxe70020","oxe70021","oxe70022"]}
} [+] : Retrieve logins of MULTIMEDIA user's who have TELEPHONY_BASIC or TELEPHONY_ADVANCED rights.
The session was opened by a administrator.
request :GET https://server/api/rest/1.0/logins?types=MULTIMEDIA&apiRights=TELEPHONY_BASIC,TELEPHONY_ADVANCED
response :200 OK
Content-Type: application/json
{
{"loginNames":["icm32539","icm32540"]}
} /users
Methods
Find information about a user from its login name, company email, company phone or instant messaging identifier.
This operation provides useful information to the application:
- Name and first name of the user
- User's internal login name
- User's phone number
- User's voicemail information
- User's list of devices
- ...
Remark: only one query parameter can be used at a time. If no query parameter a BAD_REQUEST error will be generated.
History
Since version 2.2.1
Licenses
No license required.
Request
query parameters| parameter | type | description |
|---|
| loginName | string | Login name of the user to retrieve the account description. |
| companyEmail | string | Since version 2.2.1 Company email of the user to retrieve the account description. |
| instantMessagingId | string | Since version 2.2.1 Instant messaging identifier of the user to retrieve the account description. |
| companyPhone | string | Company phone of the user to retrieve the account description. |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
Returns a redirect response to /users/{loginName} resource if a matching user is found.
| code | media types | description |
|---|
| 307 | application/json
| Redirect |
| 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 |
/users/{loginName}
Methods
Gets information about a user account.
This operation provides useful information to the application:
- Name and first name of the user
- User's internal login name
- User's phone number
- User's voicemail information
- User's list of devices
- ...
An application should invoke this method just after the open session step to know the user's account description.
A server application which is interested by retrieving data of the user using this method must invoke it only when it is necessary and then cache the result.
Licenses
No license required.
Request
path parameters| parameter | type | description |
|---|
| loginName | string | Login name of the user to retrieve the account description. |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
Returns the result code and, if the code is SUCCESS, information about the concerned user
User| code | type | media types | description |
|---|
| 200 | User | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Examples
[+] : Get information about the user's account for which the session is opened.
request :GET https://server/api/rest/1.0/users/icm32539
response :200 OK
Content-Type: application/json
{
"companyPhone":"32539",
"firstName":"F32539",
"lastName":"L32539_146",
"companyEmail":"icm32539@bstlabrd.fr.alcatel-lucent.com",
"loginName":"icm32539",
"instantMessagingId":"icm32539@bstlabrd.fr.alcatel-lucent.com",
"type":"MULTIMEDIA"
} [+] : Get information about the CT user's account for which the session is opened.
request :GET https://server/api/rest/1.0/users/user
response :200 OK
Content-Type: application/json
{
"companyPhone":"14005",
"firstName":"user",
"lastName":"user",
"companyEmail":"user@bstlabrd.fr.alcatel-lucent.com",
"loginName":"user",
"instantMessagingId":"user@bstlabrd.fr.alcatel-lucent.com",
"type":"STANDARD",
"vcardPath":"/udas/vcards/user.vcf?cf5d3e93f4efb659c5e41dee1b4ac60a",
"voicemail":
{
"number":"14200",
"voicemailtype":"VM_UM"
},
"devices":
[
{
"type":"DESKPHONE",
"id":"14005",
"subType":"NOE_C_COLOR_IP_8068",
"role": "MAIN"
},
{
"type":"DESKPHONE",
"id":"14021",
"label":"OXESync",
"subType":"NOE_C_Color_IP",
"role": "SECONDARY"
}
],
"dialingRule": {
"countryCode":"FR",
"externalPrefix":"0",
"addPfxForNbLength":6,
"areaCode":"",
"exceptionRules":[]
},
"apiRights":
[
"TELEPHONY_BASIC",
"TELEPHONY_ADVANCED"
],
"applicationRights": [
"BUSINESS_COMMUNICATIONS",
"CONFERENCING",
"DESKTOP",
"VOICE_MAIL"
],
"customAttributes":
{
"global":
{
"customFeatureEnabled": "false"
}
"user":
{
"customFeatureEnabled": "true",
"customFeatureAttribute": "userSpecificValue"
}
}
} [+] : Get manager/assistant configuration associated to a CT user for which the session is opened (the user is a manager).
request :GET https://server/api/rest/1.0/users/manager1
response :200 OK
Content-Type: application/json
{
"companyPhone":"11111",
"salutation":"MR",
"firstName":"manager1",
"lastName":"manager1",
"companyEmail":"manager1@mail.com",
"loginName":"manager1",
"type":"STANDARD",
"devices": [ {
"type":"DESKPHONE",
"id":"11111",
"subType":"NOE_C_COLOR_IP_8068",
"role": "MAIN" }
],
"configManagerAssistant": {
"assistants": [
{
"id": {
"loginName":"assistant1",
"phoneNumber":"22222",
"instantMessagingId":"assistant1@mail.com",
"companyEmail":"assistant1@mail.com"
},
"firstName":"assistant1",
"lastName":"assistant1",
"displayName":"assistant1",
"key": 7 }
],
"filters": [
{
"key":5,
"type":"SCREENING",
"label":"filter1" },
{
"key":3,
"type":"UNSCREENING",
"label":"filter2" }
]
}
} [+] : Get manager/assistant configuration associated to a CT user for which the session is opened (the user is an assistant).
request :GET https://server/api/rest/1.0/users/assistant1
response :200 OK
Content-Type: application/json
{
"companyPhone":"22222",
"salutation":"MR",
"firstName":"assistant1",
"lastName":"assistant1",
"companyEmail":"assistant1@mail.com",
"loginName":"assistant1",
"type":"STANDARD",
"devices": [ {
"type":"DESKPHONE",
"id":"22222",
"subType":"NOE_C_COLOR_IP_8068",
"role": "MAIN" }
],
"configManagerAssistant":
{
"managers": [
{
"id": {
"loginName":"manager1",
"phoneNumber":"11111",
"instantMessagingId":"manager1@mail.com",
"companyEmail":"manager1@mail.com"
},
"firstName":"manager1",
"lastName":"manager1",
"displayName":"manager1",
"key":8,
"supervisedFilters":
[ {
"key":4,
"type":"SCREENING",
"label":"filter1" },
{
"key":2,
"type":"UNSCREENING",
"label":"filter2" }
]
}
]
}
} Associated notifications
/users/{loginName}/password
Methods
Change user's password.
This operation allows a user or an administrator to change its password
History
Since version 2.2.1
Licenses
No license required.
Request
path parameters| parameter | type | description |
|---|
| loginName | string | Login name of the user to change the password. |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
Returns the result code and
| code | media types | description |
|---|
| 204 | application/json
| No Content |
| 400 | application/json
| Bad Request |
| 403 | application/json
| Forbidden |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
/users/{loginName}/preferences
Methods
Gets information about user's preferences.
This operation provides useful information to the application:
- User's GUI language
- User's personal mobile phone number
- User's home phone number
- User's CLIR mode
- ...
Licenses
No license required.
Request
path parameters| parameter | type | description |
|---|
| loginName | string | Login name of the user to retrieve the preferences. |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
Returns the result code and, if the code is SUCCESS, preferences about the concerned user
UserPreferences| code | type | media types | description |
|---|
| 200 | UserPreferences | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Examples
[+] : Get user's preferences for which the session is opened.
request :GET https://server/api/rest/1.0/users/alice/preferences
response :200 OK
Content-Type: application/json
{
"guiLanguage":"en_GB",
"personalMobile":"+1-646-111-2222",
"personalPhone":"+1-555-222-3333",
"telephony": {
"clirMode":"ACTIVE"}
} Updates information about user's preferences.
This operation provides useful information to the application:
- User's GUI language
- User's personal mobile phone number
- User's home phone number
- User's CLIR mode
- ...
Licenses
No license required.
Request
path 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
Returns 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 |
| 503 | application/json
| Service Unavailable |
Examples
[+] : set user's preferences for which the session is opened.
request :POST https://server/api/rest/1.0/users/alice/preferences
Content-Type: application/json
{
"guiLanguage":"en_GB",
"telephony": {
"clirMode":"ACTIVE"}
}response :204 No Content
Associated notifications
/users/{loginName}/preferences/telephony
Methods
Gets information about user's telephony preferences:
History
Since version 2.1
Licenses
No license required.
Request
path parameters| parameter | type | description |
|---|
| loginName | string | Login name of the user to retrieve the telephony preferences. |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
Returns the result code and, if the code is SUCCESS, telephony preferences about the concerned user
TelephonyPreferences| code | type | media types | description |
|---|
| 200 | TelephonyPreferences | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Examples
[+] : Get user's telephony preferences for which the session is opened.
request :GET https://server/api/rest/1.0/users/alice/preferences/telephony
response :200 OK
Content-Type: application/json
{
"clirMode":"ACTIVE"}
} Updates information about user's telephony preferences:
History
Since version 2.1
Licenses
No license required.
Request
path 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
Returns 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 |
| 503 | application/json
| Service Unavailable |
Examples
[+] : set user's telephony preferences for which the session is opened.
request :POST https://server/api/rest/1.0/users/alice/preferences/telephony
Content-Type: application/json
{
"clirMode":"ACTIVE"}
}response :204 No Content
Associated notifications
Representations
ApplicationRightApplication right values.
| Value | Description |
|---|
| BUSINESS_COMMUNICATIONS | User has BUSINESS_COMMUNICATIONS right. |
| CONFERENCING | User has CONFERENCING right. |
| DESKTOP | User has DESKTOP right. |
| NOMADIC | User has NOMADIC right (only for MULTIMEDIA users). |
| NOMADIC_SIP | User has NOMADIC_SIP right (only for STANDARD users). |
| NOMADIC_GSM | User has NOMADIC_GSM right (only for STANDARD users). |
| MOBILE | User has OFF_SITE_MOBILITY right (ie right to use a mobile phone). |
| TABLET | User has TABLET right. |
| VOICE_MAIL | User has VOICE_MAIL right. |
| FLEX_OFFICE | User has FLEX_OFFICE right. |
Request to change password of the user
| Name | Type | Cardinality | Description |
|---|
| oldPassword | string | [1] | Old password |
| newPassword | string | [1] | New password |
Associated method :
CLIR state values
| Value | Description |
|---|
| UNKNOWN | CLIR mode can not be determined. |
| NOT_SUPPORTED | CLIR mode is not supported. |
| INACTIVE | CLIR is inactive |
| ACTIVE | CLIR is active |
| INACTIVE_NOT_UPDATABLE | CLIR is inactive but can't be modified |
| ACTIVE_NOT_UPDATABLE | CLIR is active but can't be modified |
Describes custom attributes associated to a user.
| Name | Type | Cardinality | Description |
|---|
| global | { string , string } | [0..*] | Global custom attributes. |
| user | { string , string } | [0..*] | User custom attributes. |
Describe a device.
| Name | Type | Cardinality | Description |
|---|
| type | DeviceType | [0..1] | Device's type. |
| id | string | [0..1] | Device identifier which is used to identify the device in telephony requests and events. |
| label | string | [0..1] | Label which allows a user to name his device.
An application should use this string first when the device has to be displayed.
If no label exists, the type can be used to display a localized display name on application side. |
| subType | string | [0..1] | Device's subtype :
- For a Multimedia user and a
DESKPHONE type, we could have : SIP_4008, SIP_4018, VHE8082, VHE8088, SIP_8001, SIP_8002, SIP_8012, SIP_8038, SIP_8068 ...
- For a Standard user and a
DESKPHONE type, we could have : ANALOG, NOE_C_Color_IP, ...
- For a
MOBILE type, we could have : MOBILE, MOBILE_ANDROID, MOBILE_BLACKBERRY, MOBILE_IPHONE, MOBILE_NOKIA, MOBILE_WINDOWS, ...
- For a
SOFTPHONE type, we could have : MYICSIP, OTC_TABLET, THIRD_PARTY_VIDEO, ...
- For a
NOMADIC type, we could have : NOMADIC_HOME, NOMADIC_OTHER, ...
|
| associatedNumber | string | [0..1] | If the device type is MOBILE this parameter defines the real number of the mobile. |
| configId | string | [0..1] | Reserved: DO NOT USE.
|
[+] : JSON Example{
"type": "DECT | DESKPHONE | MOBILE | NOMADIC | SOFTPHONE",
"id": "string",
"label": "string",
"subType": "string",
"associatedNumber": "string",
"configId": "string"
} |
The device type values.
| Value | Description |
|---|
| DECT | A wireless phone set used within the enterprise. |
| DESKPHONE | A phone set on an office's desk. |
| MOBILE | A mobile phone. |
| NOMADIC | Allows to temporarily use an external phone. |
| SOFTPHONE | A phone started from a computer with VOIP. |
Describes user's dialing rule.
A dialing rule is used to define the rules for the automated generation of phone numbers.
These numbering rules are defined by:
- an international country code (ISO 3166 alpha-2)
- an external prefix
- a phone number length above which we must add the external prefix
- possibly a list of exceptions to the previous rule (length for external prefix addition)
| Name | Type | Cardinality | Description |
|---|
| countryCode | string | [1] | Country code. |
| externalPrefix | string | [1] | External prefix. |
| addPfxForNbLength | int | [1] | Phone number length above which we must add the external prefix. |
| areaCode | string | [0..1] | Area code. |
| exceptionRules | ExceptionRule | [0..*] | Exception rules. |
[+] : JSON Example{
"countryCode": "string",
"externalPrefix": "string",
"addPfxForNbLength": int,
"areaCode": "string",
"exceptionRules": [ {
"lengthException": int,
"beginPatternException": "string"
} ]
} |
Describes user's dialing rule exception for the external prefix management.
In some cases it may be useful to distinguish internal phone numbers which look like external ones.
Thus an exception to the previous rule can be done for phone numbers of Y digits beginning with a particular pattern.
Y is specified by #lengthException and the beginning pattern is specified by #beginPatternException.
To do so, for each number which length is equal to the one defined by #lengthException, the system controls whether the phone number starts with a specific pattern.
When the beginning of the phone number matches this pattern, the system knows that it doesn't have to dial the external prefix
Note that if the value of #lengthException is equal to zero then the pattern control is done for any size of phone number.
| Name | Type | Cardinality | Description |
|---|
| lengthException | int | [1] | Specifies the particular phone number length for which the system has to control whether the phone number starts by a particular pattern specified by #beginPatternException. |
| beginPatternException | string | [1] | Specifies the pattern for which, when present at the beginning of a phone number, we do not dial the external prefix. |
[+] : JSON Example{
"lengthException": int,
"beginPatternException": "string"
} |
'int' is a 32-bit number (-2147483648 to 2147483647).
LoginsResponseThe get logins response.
| Name | Type | Cardinality | Description |
|---|
| loginNames | string | [1..*] | List of logins matching the request. |
[+] : JSON Example{
"loginNames": [ "string" ]
} |
Associated method :
This event is sent on any change on the user's preferences.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnPreferencesChanged' |
| loginName | string | [1] | The login name of the user. |
| preferences | UserPreferences | [1] | The changed user preferences object. |
[+] : JSON Example{
"eventName": "string",
"loginName": "string",
"preferences": {
"guiLanguage": "string",
"tuiLanguage": "string",
"personalMobile": "string",
"professionalMobile": "string",
"personalPhone": "string",
"telephony": {
"clirMode": "UNKNOWN | NOT_SUPPORTED | INACTIVE | ACTIVE | INACTIVE_NOT_UPDATABLE | ..."
},
"colleague": "string"
}
} |
Associated methods :
This event is sent on creation of an user (only for administrator).
There is no control on the 'ids' provided in the 'Selector' filter of the subscription filter (subscription done for all users).
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnUserCreated' |
| user | User | [1] | The created user object. |
[+] : JSON Example{
"eventName": "string",
"user": {
"companyPhone": "string",
"salutation": "MR | MRS | MISS",
"firstName": "string",
"lastName": "string",
"companyEmail": "string",
"loginName": "string",
"instantMessagingId": "string",
"type": "STANDARD | MULTIMEDIA",
"site": "string",
"department": "string",
"vcardPath": "string",
"voicemail": {
"number": "string",
"type": "VM_4635 | VM_4645 | VM_UM | VM_LOCAL_STORAGE | EXTERNAL"
},
"devices": [ {
"type": "DECT | DESKPHONE | MOBILE | NOMADIC | SOFTPHONE",
"id": "string",
"label": "string",
"subType": "string",
"associatedNumber": "string",
"configId": "string"
} ],
"dialingRule": {
"countryCode": "string",
"externalPrefix": "string",
"addPfxForNbLength": int,
"areaCode": "string",
"exceptionRules": [ {
"lengthException": int,
"beginPatternException": "string"
} ]
},
"apiRights": [ "TELEPHONY_BASIC | TELEPHONY_ADVANCED | MESSAGING | CONFERENCING" ],
"applicationRights": [ "BUSINESS_COMMUNICATIONS | CONFERENCING | DESKTOP | NOMADIC | NOMADIC_SIP | ..." ],
"sipUri": "string",
"customAttributes": {
"global": { "string" : "string" },
"user": { "string" : "string" }
}
}
} |
This event is sent when user is deleted (only for administrator).
There is no control on the 'ids' provided in the 'Selector' filter of the subscription filter (subscription done for all users).
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnUserDeleted' |
| loginName | string | [1] | The login name of the deleted user. |
This event is sent on any change on the user's data.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnUserInfoChanged' |
| user | User | [1] | The changed user object. |
[+] : JSON Example{
"eventName": "string",
"user": {
"companyPhone": "string",
"salutation": "MR | MRS | MISS",
"firstName": "string",
"lastName": "string",
"companyEmail": "string",
"loginName": "string",
"instantMessagingId": "string",
"type": "STANDARD | MULTIMEDIA",
"site": "string",
"department": "string",
"vcardPath": "string",
"voicemail": {
"number": "string",
"type": "VM_4635 | VM_4645 | VM_UM | VM_LOCAL_STORAGE | EXTERNAL"
},
"devices": [ {
"type": "DECT | DESKPHONE | MOBILE | NOMADIC | SOFTPHONE",
"id": "string",
"label": "string",
"subType": "string",
"associatedNumber": "string",
"configId": "string"
} ],
"dialingRule": {
"countryCode": "string",
"externalPrefix": "string",
"addPfxForNbLength": int,
"areaCode": "string",
"exceptionRules": [ {
"lengthException": int,
"beginPatternException": "string"
} ]
},
"apiRights": [ "TELEPHONY_BASIC | TELEPHONY_ADVANCED | MESSAGING | CONFERENCING" ],
"applicationRights": [ "BUSINESS_COMMUNICATIONS | CONFERENCING | DESKTOP | NOMADIC | NOMADIC_SIP | ..." ],
"sipUri": "string",
"customAttributes": {
"global": { "string" : "string" },
"user": { "string" : "string" }
}
}
} |
Associated method :
| Value | Description |
|---|
| MR | Mister title |
| MRS | Madam title |
| MISS | Miss title |
'string' represents character strings.
TelephonyPreferencesDescribes user's telephony preferences.
| Name | Type | Cardinality | Description |
|---|
| clirMode | ClirMode | [0..1] | Since version 2.1 User's telephony preferences |
[+] : JSON Example{
"clirMode": "UNKNOWN | NOT_SUPPORTED | INACTIVE | ACTIVE | INACTIVE_NOT_UPDATABLE | ..."
} |
Associated methods :
The description of a user
| Name | Type | Cardinality | *1 | Description |
|---|
| companyPhone | string | [0..1] | | User's company phone number. |
| salutation | Salutation | [1] | | Since version 2.5 User's salutation. |
| firstName | string | [0..1] | | First name of the User or Administrator owner of this Account. |
| lastName | string | [0..1] | | Last name of the User or Administrator owner of this Account. |
| companyEmail | string | [0..1] | | Company e-mail of the User or the Administrator. |
| loginName | string | [0..1] | | Login name which identifies the User Account. |
| instantMessagingId | string | [0..1] | | Instant messaging identifier of the User. |
| type | UserType | [0..1] | X | User's type. |
| site | string | [0..1] | X | Since version 2.5 Name of the site. |
| department | string | [0..1] | X | Since version 2.5 Name of the department. |
| vcardPath | string | [0..1] | | Since version 2.2 User's vCard relative URL.
Note: To build an absolute URL, this relative path value have to be concatenated with the VCARD base URL.
This VCARD base URL can be retrieved using "Location information" service:
GET http(s)://<server>/api/rest/locator/services?names=VCARD
|
| voicemail | Voicemail | [0..1] | | User's voicemail description. |
| devices | Device | [0..*] | X | User's devices. |
| dialingRule | DialingRule | [0..1] | X | Since version 2.1 User's dialing rule description. |
| apiRights | UserRight | [0..*] | X | Since version 2.1.1 User's API rights. |
| applicationRights | ApplicationRight | [0..*] | X | Since version 2.2 User's application rights.
The valid rights ApplicationRight are added in this list. |
| sipUri | string | [0..1] | | Since version 2.2 User's SIP URI. |
| customAttributes | CustomAttributes | [0..1] | X | Since version 2.5 Custom attributes. |
*1 : attribute only provided if the user is the session's owner or for an administrator session.
[+] : JSON Example{
"companyPhone": "string",
"salutation": "MR | MRS | MISS",
"firstName": "string",
"lastName": "string",
"companyEmail": "string",
"loginName": "string",
"instantMessagingId": "string",
"type": "STANDARD | MULTIMEDIA",
"site": "string",
"department": "string",
"vcardPath": "string",
"voicemail": {
"number": "string",
"type": "VM_4635 | VM_4645 | VM_UM | VM_LOCAL_STORAGE | EXTERNAL"
},
"devices": [ {
"type": "DECT | DESKPHONE | MOBILE | NOMADIC | SOFTPHONE",
"id": "string",
"label": "string",
"subType": "string",
"associatedNumber": "string",
"configId": "string"
} ],
"dialingRule": {
"countryCode": "string",
"externalPrefix": "string",
"addPfxForNbLength": int,
"areaCode": "string",
"exceptionRules": [ {
"lengthException": int,
"beginPatternException": "string"
} ]
},
"apiRights": [ "TELEPHONY_BASIC | TELEPHONY_ADVANCED | MESSAGING | CONFERENCING" ],
"applicationRights": [ "BUSINESS_COMMUNICATIONS | CONFERENCING | DESKTOP | NOMADIC | NOMADIC_SIP | ..." ],
"sipUri": "string",
"customAttributes": {
"global": { "string" : "string" },
"user": { "string" : "string" }
}
} |
Associated method :
The preferences of a user
| Name | Type | Cardinality | Description |
|---|
| guiLanguage | string | [0..1] | Language of the User or the Administrator.
It is composed of the language code (ISO 639-1 / alpha-2 codes) and optionally of the country code
(ISO 3166 / alpha-2 capital letters) preceded by an underscore. E.g.: en_GB or en_US.
|
| tuiLanguage | string | [0..1] | Since version 2.5 TUI language of the User or the Administrator. |
| personalMobile | string | [0..1] | User's mobile phone number. |
| professionalMobile | string | [0..1] | User's company mobile phone number.
Only multimedia users can update their professional phone number. |
| personalPhone | string | [0..1] | User's personal phone number. |
| telephony | TelephonyPreferences | [0..1] | Since version 2.1 User's telephony preferences. |
| colleague | string | [0..1] | Since version 2.1 User's colleague. |
[+] : JSON Example{
"guiLanguage": "string",
"tuiLanguage": "string",
"personalMobile": "string",
"professionalMobile": "string",
"personalPhone": "string",
"telephony": {
"clirMode": "UNKNOWN | NOT_SUPPORTED | INACTIVE | ACTIVE | INACTIVE_NOT_UPDATABLE | ..."
},
"colleague": "string"
} |
Associated methods :
User right values.
| Value | Description |
|---|
| TELEPHONY_BASIC | User has TELEPHONY_BASIC right. |
| TELEPHONY_ADVANCED | User has TELEPHONY_ADVANCED right. |
| MESSAGING | User has MESSAGING right. |
| CONFERENCING | Since version 2.1.1 User has CONFERENCING right. |
User type values.
| Value | Description |
|---|
| STANDARD | User is a standard user. |
| MULTIMEDIA | User is a multimedia user. |
Describes user's voicemail.
| Name | Type | Cardinality | Description |
|---|
| number | string | [1] | Voicemail number. |
| type | VoicemailType | [1] | Since version 2.2 Voicemail type. |
[+] : JSON Example{
"number": "string",
"type": "VM_4635 | VM_4645 | VM_UM | VM_LOCAL_STORAGE | EXTERNAL"
} |
Voicemail type values
| Value | Description |
|---|
| VM_4635 | Integrated 46x5 voice mail system
, for STANDARD user.
|
| VM_4645 | Integrated 46x5 voice mail system
, for STANDARD user.
|
| VM_UM | Unified Messaging, based on mail servers (Exchange, Domino or any IMAP4 compliant system). |
| VM_LOCAL_STORAGE | Internal OT storage |
| EXTERNAL | External voice mail systems |
Subscription management
Presentation
Management of all subscription related resources.
Once subscription to events is performed, client should instantiate the
HTTP Chunk notification channel.
To be eligible to event notification, client must fulfill the following conditions:
- Have an opened framework session.
- Have a TELEPHONY_ADVANCED or MESSAGING or CONFERENCING license.
See NOTE1 for additional requirements about license.
- Have subscribed to the set of events he wants to be notified on.
- Have received an ACCEPTED subscription response from the server.
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, OnCallAppeared, OnCallModified, OnCallRemoved, OnUserStateModified, OnDeviceStateModified, OnCallbackRequestAdded]
- eventSummary [OnEventSummaryUpdated]
- unifiedComLog [OnComRecordCreated, OnComRecordModified, OnComRecordsDeleted, OnComRecordsAck, OnComRecordsUnAck]
- user [OnUserInfoChanged, OnPreferencesChanged]
- userManagement [OnUserCreated, OnUserDeleted]
- routingManagement [OnRoutingManagementFailed, OnRoutingProfilesChanged, OnRoutingStateChanged]
- instantMessaging [OnDeferredMessageCountersChanged, OnImParticipantAdded, OnImParticipantDropped, OnImParticipantTyping, OnImReceived]
- presence [OnUserPresenceUpdated, OnContactPresenceUpdated]
- messaging [OnMessageAdded, OnMessageDeleted, OnMessageUpdated]
- conference [OnConferenceCreated, OnConferenceModified, OnConferenceDeleted]
- groups [OnGroupCreated, OnGroupModified, OnGroupRemoved, OnSupervisedUpdated, OnGroupLoggedFailed]
- [OnChannelInformation]
To declare these events or packages in a subscription request, a selector must be used (at least one per event package).
A selector contain a list of names (i.e. logins), and either a list of events or an event package.
It is not possible to mix events of different packages inside the same selector. A different selector must be used in such case.
A subscription request includes other fields such as:
- The desired notification mode. Current version only support HTTP Chunk notification.
- The notification format. JSON is the preferred format.
- 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.
- Chunk specific parameters, sent to the server when initiating the HTTP Chunk mode (timeout, keepalive, ...).
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 (this is the framework session Id in this release).
- 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:
- 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.
- If no activity is detected for a timeout set during subscription, 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.
NOTE1: License check for administrator session.
An administrator can subscribe to event notification concerning a subset of users.
Each user must have either TELEPHONY_ADVANCED or MESSAGING license, or both.
There is no license associated to the administrator,
but the amount of supervised users can not exceed the number of TELEPHONY_ADVANCED licenses installed on the server.
The following rules apply when checking if the limit is reached or not:
- The counter is increased when a user is part of an administrator's subscription for the first time.
- The counter is decreased when the last administrator's subscription is removed for a given user.
- The whole subscription is refused if the content will make the counter exceed the installed number of licenses.
- The whole subscription is refused if at least one of users from the list has no TELEPHONY_ADVANCED and no MESSAGING license.
Resources summary
Resources
/subscriptions
Methods
Create a subscription for event notification.
Licenses
The license TELEPHONY_ADVANCED or MESSAGING is 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 all events of the telephony, eventSummary event packages,
for user userA.
request :POST https://server/api/rest/1.0/subscriptions
Content-Type: application/json
{
"filter":{"selectors":[
{"ids":["userA"],"names":["telephony"],"families":[],"origins":[]},
{"ids":["userA"],"names":["eventSummary"],"families":[],"origins":[]}]},
"mode":"CHUNK","format":"JSON",
"version":"1.0","timeout":10
}response :200 OK
{
"subscriptionId":"...93231353535373132393",
"publicPollingUrl":"https://public.server:8016/OTEvents?subscriptionId=...93231353535373132393",
"privatePollingUrl":"https://server:8016/OTEvents?subscriptionId=...93231353535373132393",
"status":"ACCEPTED",
"mode":"CHUNK","format":"JSON"
} [+] : Create a refused subscription to all events of the telephony, eventSummary and user event packages, for userA, userB, userC.
This subscription will be refused because of exceeded license check.
request :POST https://server/api/rest/1.0/subscriptions
Content-Type: application/json
{
"filter":{"selectors":[
{"ids":["userA","userB","userC"],"names":["telephony"],"families":[],"origins":[]},
{"ids":["userA","userB","userC"],"names":["eventSummary"],"families":[],"origins":[]},
{"ids":["userA","userB","userC"],"names":["user"],"families":[],"origins":[]}]},
"mode":"CHUNK","format":"JSON",
"sessionId":"...2303639373638343","version":"1.0",
"timeout":60,"keepalive":0
}response :400 BadRequest
{
"subscriptionId":"...2303639373638343",
"message":"SUBSCRIPTION_NOT_DONE: Max nb of license used for notification.",
"status":"REFUSED","mode":"CHUNK","format":"JSON"
} 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, keepalive, ...).
Licenses
The license TELEPHONY_ADVANCED or MESSAGING is 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"],"families":[],"origins":[]},
{"ids":["userA","userB"],"names":["eventSummary"],"families":[],"origins":[]}]
}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
The license TELEPHONY_ADVANCED or MESSAGING is 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
boolean'boolean' is a data type, having two values (true and false).
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).
NotificationFormatDefines which standard will be used to format event.
| Value | Description |
|---|
| JSON | JSON event format. |
The method used to notify event.
| Value | Description |
|---|
| CHUNK | HTTP chunk notification mode. Client shall initiate and maintain a
polling on the server. |
| CHUNK_MULTIPART | Since version 2.2 HTTP chunk notification mode, with mixed content type.
The recommended default data format is JSON.
This mode can be used when mixing content:
Example: conferencing events requested in ICAL format, and all the rest in JSON. |
A selector is a filter applied to an event.
The attributes of an event must match all the criteria of the
selector to be sent to the subscriber.
| Name | Type | Cardinality | Description |
|---|
| ids | string | [0..*] | The selector specifies that all events must contain one of these identifier.
This parameter is not mandatory for a user session, but it is mandatory for an
administrator session (at least one identifier must be provided).
|
| names | string | [1..*] | The selector specifies that all events must match this attribute.
The content of this field must match the name of events or one of the event packages, as listed in Subscription overview.
The name can't be empty. |
'string' represents character strings.
SubscriptionContains the status returned by the server on a subscription request.
| Name | Type | Cardinality | Default | 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. |
| mode | NotificationMode | [0..1] | CHUNK | Copy of the NotificationMode of the request. |
| format | NotificationFormat | [0..1] | JSON | Copy of the NotificationFormat of the request. |
[+] : JSON Example{
"subscriptionId": "string",
"message": "string",
"publicPollingUrl": "string",
"privatePollingUrl": "string",
"status": "UNKNOWN | ACCEPTED | REFUSED",
"mode": "CHUNK | CHUNK_MULTIPART",
"format": "JSON"
} |
Associated method :
Contains all information needed for subscription to event notification.
| Name | Type | Cardinality | Default | Description |
|---|
| notificationUrl | string | [0..1] | | Reserved: DO NOT USE.
|
| filter | Filter | [0..1] | | List of selector used to filter events. |
| appId | string | [0..1] | | Since version 2.3.1 The iOS application id. |
| mode | NotificationMode | [0..1] | CHUNK | The notification mode to be used for sending events. |
| format | NotificationFormat | [0..1] | JSON | The format to be used by notified events. |
| sessionId | string | [0..1] | | Reserved: DO NOT USE.
|
| subscriptionId | string | [0..1] | | The subscription identifier |
| token | string | [0..1] | | The voip token identifier |
| tokenRemote | string | [0..1] | | Since version 2.3.1 The remote token identifier |
| version | string | [1] | | The version of the events the user wants to subscribe to. |
| timeout | int | [0..1] | 10 | Since version 2.1 Default lifetime of the channel opened between the server and the client.
After that time, in minutes, the server can close the connection.
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. |
| keepalive | int | [0..1] | 0 | Value, in minutes, used by the server to check if the client is still alive.
Periodically, a keepalive message is sent.
Allowed values are between 1 minute and lower than than the timeout value previously defined.
0 means no keepalive. |
| init | boolean | [0..1] | true | Reserved: DO NOT USE.
|
[+] : JSON Example{
"notificationUrl": "string",
"filter": {
"selectors": [ {
"ids": [ "string" ],
"names": [ "string" ]
} ]
},
"appId": "string",
"mode": "CHUNK | CHUNK_MULTIPART",
"format": "JSON",
"sessionId": "string",
"subscriptionId": "string",
"token": "string",
"tokenRemote": "string",
"version": "string",
"timeout": int,
"keepalive": int,
"init": boolean
} |
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
Resources summary
| Resource | Method | Description |
|---|
| /telephony/basicCall | POST | Initiates a call to another user (the callee). |
| /telephony/basicCall/answer | POST | Responds to the incoming ringing call. |
| /telephony/basicCall/dropme | POST | Exits from the call: if the call is a single call, it is released; if it is a conference,
the call carries on without the user. |
| /telephony/calls | GET | Get information on all the calls in progress. |
| POST | Initiates a new call to another user (the callee). |
| /telephony/calls/{callRef} | GET | Returns a description of a call. |
| DELETE | Hangs on an active call, all the parties are released. |
| /telephony/calls/{callRef}/alternate | POST | Puts on hold the active call and retrieve a call that has been previously put in hold. |
| /telephony/calls/{callRef}/answer | POST | Responds to an incoming ringing call. |
| /telephony/calls/{callRef}/attachdata | POST | (Standard user ONLY) Associates data with an outgoing call, following a previously established external call. |
| /telephony/calls/{callRef}/blindtransfer | POST | Transfers a specified active call to another user, without knowing if this user will answer and
without keeping control on this call. |
| /telephony/calls/{callRef}/callback | POST | (Standard user ONLY) Requests for call back during a call. |
| /telephony/calls/{callRef}/deviceLegs | GET | Returns the legs involved in the call |
| /telephony/calls/{callRef}/deviceLegs/{legId} | GET | Returns the leg whose Id is legId |
| POST | Translates the call from a user device to another device. |
| /telephony/calls/{callRef}/dropme | POST | Exits from an active call: if the call is a single call, it is released; if it is a conference,
the call carries on without the user. |
| /telephony/calls/{callRef}/hold | POST | Holds a specified active call. |
| /telephony/calls/{callRef}/merge | POST | Makes a n-party conference with a specified active call and a specified held call. |
| /telephony/calls/{callRef}/overflowToVoiceMail | POST | Redirects an outgoing ringing call to the voice mail of the called user. |
| /telephony/calls/{callRef}/park | POST | (Standard user ONLY) Park a specified active call to a target device. |
| /telephony/calls/{callRef}/participants | GET | Returns the list of participants in a call. |
| POST | (Multimedia user ONLY) Adds a participant into an active call. |
| /telephony/calls/{callRef}/participants/{participantId} | GET | Returns information about a participant in a call. |
| DELETE | Drops a participant from an active call: if the call is a single call, it is released; if it is a conference,
the call carries on without the participant. |
| /telephony/calls/{callRef}/recording | POST | Starts, stops, pauses or resumes the recording of a call. |
| /telephony/calls/{callRef}/redirect | POST | Redirects an incoming ringing call to another user or number, instead of responding to it. |
| /telephony/calls/{callRef}/retrieve | POST | Retrieves a call that has been previously put in hold. |
| /telephony/calls/{callRef}/sendDtmf | POST | (Standard user ONLY) Sends DTMF in an active call. |
| /telephony/calls/{callRef}/transfer | POST | Transfers a specified active call to a specified held call. |
| /telephony/devices | GET | Gets states of all user devices |
| /telephony/devices/{deviceId} | GET | Gets a user device state |
| /telephony/devices/{deviceId}/mute/{mute} | POST | Activate/deactivate ringing of a device |
| /telephony/devices/{deviceId}/pickup | POST | Picks up an incoming call on another user. |
| /telephony/devices/{deviceId}/unpark | POST | (Standard user ONLY) UnPark a call from a target device. |
| /telephony/incomingCallbacks | GET | (Standard user ONLY) Returns the whole list of callback requests. |
| DELETE | (Standard user ONLY) Deletes all callback requests. |
| /telephony/incomingCallbacks/{callbackId} | DELETE | (Standard user ONLY) Deletes a callback request. |
| /telephony/numbering/canonical | GET |
Transforms the phone number into canonical. |
| /telephony/numbering/dialable | GET |
Transforms a phone number into a dialable number. |
| /telephony/outgoingCallbacks | POST | (Standard user ONLY) Requests for call back from an idle device. |
| /telephony/state | GET | Asks for the user telephonic state and capabilities. |
Notifications summary
| Notification | Description |
|---|
| OnCallAppeared | This notification indicates that a new call for mobile device has been created. |
| OnCallbackRequestAdded | Notification is sent when new callback request is added. |
| 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 have been removed (hang up, transfer...). |
| OnDeviceMuteFailed | This notification indicates that a mute request failed. |
| OnDeviceMuteSuccess | This notification indicates that a mute request was successful. |
| OnDeviceStateModified | This notification indicates that device's state have been modified. |
| OnUserStateModified | This notification indicates that user's state have been modified (FREE, BUSY ...). |
Resources
/telephony/basicCall
Methods
Initiates a call to another user (the callee).
Also used to initiate a call from any connected set which is not associated to an OpenTouch user.
Licenses
The license TELEPHONY_BASIC or TELEPHONY_ADVANCED is required.
Request
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
| code | type | media types | description |
|---|
| 201 | string | application/json
| CREATED |
| 204 | | application/json
| No Content Only for a call from a connected set which is not associated to an OpenTouch user |
| 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
[+] : Initiates a call to another user (the callee)
request :POST https://server/api/rest/1.0/telephony/basicCall
Content-Type: application/json
{
"deviceId": "70021",
"callee": "70022",
"autoAnswer": true
}response :201 Created
Location: http://server/api/rest/1.0/telephony/basicCall/2db0a05647030100
[+] : Initiates a call from any connected set which is not associated to an OpenTouch user.
request :POST https://server/api/rest/1.0/telephony/basicCall
Content-Type: application/json
{
"deviceId": "70060",
"callee": "70022"
}response :204 No Content
Associated notifications
/telephony/basicCall/answer
Methods
Responds to the incoming ringing call.
Licenses
The license TELEPHONY_BASIC or TELEPHONY_ADVANCED is required.
Request
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 |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Associated notifications
/telephony/basicCall/dropme
Methods
Exits from the call: if the call is a single call, it is released; if it is a conference,
the call carries on without the user.
Licenses
The license TELEPHONY_BASIC or TELEPHONY_ADVANCED is 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 | 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 |
Associated notifications
/telephony/calls
Methods
Get information on all the calls in progress.
Licenses
The license TELEPHONY_ADVANCED is 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 |
Initiates a new call to another user (the callee).
To initiate a regular call don't fill the associatedData, pin, secretCode or
businessCode parameters.
(Standard user ONLY) To initiate a call with associated data fill the associatedData parameter.
(Standard user ONLY) To initiate a Private Call fill the pin and secretCode parameters.
(Standard user ONLY) To initiate a Business Call fill the businessCode parameter.
To initiate a call from any connected set which is not associated to an OpenTouch user, don't fill the bypass, associatedData,
pin, secretCode or businessCode parameters.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters| parameter | type | description |
|---|
| loginName | string | Since version 2.2.1 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 |
|---|
| 201 | string | application/json
| CREATED |
| 204 | | application/json
| No Content Only for a call from a connected set which is not associated to an OpenTouch user |
| 400 | | application/json
| Bad Request |
| 401 | | application/json
| Unauthorized |
| 403 | | application/json
| Forbidden |
| 404 | | application/json
| Not Found |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Examples
[+] : Initiates a call to another user (the callee)
request :POST https://server/api/rest/1.0/telephony/basicCall
Content-Type: application/json
{
"deviceId": "70021",
"callee": "70022",
"autoAnswer": true
}response :201 Created
Location: http://server/api/rest/1.0/telephony/calls/49bfa0564a030100
[+] : Initiates a Private call.
request :POST https://server/api/rest/1.0/telephony/basicCall
Content-Type: application/json
{
"deviceId": "70021",
"callee": "70022",
"pin": "01222",
"secretCode": "0124"
}response :201 Created
Location: http://server/api/rest/1.0/telephony/calls/e4c3a0564c030100
[+] : Initiates a Business call.
request :POST https://server/api/rest/1.0/telephony/basicCall
Content-Type: application/json
{
"deviceId": "70021",
"callee": "70022",
"businessCode": "0124"
}response :201 Created
Location: http://server/api/rest/1.0/telephony/calls/e5c3a0564c030100
[+] : Initiates a call from any connected set which is not associated to an OpenTouch user.
request :POST https://server/api/rest/1.0/telephony/basicCall
Content-Type: application/json
{
"deviceId": "70060",
"callee": "70022"
}response :204 No Content
Associated notifications
/telephony/calls/{callRef}
Methods
Returns a description of a call.
Licenses
The license TELEPHONY_ADVANCED is 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 |
Hangs on an active call, all the parties are released.
Licenses
The license TELEPHONY_ADVANCED is 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 | 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 |
Associated notifications
/telephony/calls/{callRef}/alternate
Methods
Puts on hold the active call and retrieve a call that has been previously put in hold.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | reference of the held call. |
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 |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Associated notifications
/telephony/calls/{callRef}/answer
Methods
Responds to an incoming ringing call.
NOTE: To invoke answer on a call, the API user must check the correct state of the concerned call.
This can be done by listening to the telephony events, and more specifically to the capabilities of the involved leg.
(answer capability on the leg).
RESTRICTION: In OpenTouch 2.0, for multimedia users, no error is returned for an incorrect use of the answer
(e.g. on a held call). This restriction does not apply to OpenTouch 2.1.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | Call reference.
|
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 |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Associated notifications
/telephony/calls/{callRef}/attachdata
Methods
(Standard user ONLY) Associates data with an outgoing call, following a previously established external call.
This operation can only be used for a call initiated by a makeCall operation.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | Call reference.
|
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 |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
/telephony/calls/{callRef}/blindtransfer
Methods
Transfers a specified active call to another user, without knowing if this user will answer and
without keeping control on this call.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | Reference of the active call. |
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 | 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 |
Associated notifications
/telephony/calls/{callRef}/callback
Methods
(Standard user ONLY) Requests for call back during a call.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | Reference of the active call. |
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 | 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 |
Associated notifications
/telephony/calls/{callRef}/deviceLegs
Methods
Returns the legs involved in the call
Licenses
The license TELEPHONY_ADVANCED is 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 | Legs | 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/calls/{callRef}/deviceLegs/{legId}
Methods
Returns the leg whose Id is legId
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | Call reference.
|
| legId | string | Leg 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 | Leg | 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 |
Translates the call from a user device to another device.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | Call reference.
|
| legId | string | Leg reference |
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 |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Associated notifications
/telephony/calls/{callRef}/dropme
Methods
Exits from an active call: if the call is a single call, it is released; if it is a conference,
the call carries on without the user.
Licenses
The license TELEPHONY_ADVANCED is 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 | 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 |
Associated notifications
/telephony/calls/{callRef}/hold
Methods
Holds a specified active call.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | Call reference.
|
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 |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Associated notifications
/telephony/calls/{callRef}/merge
Methods
Makes a n-party conference with a specified active call and a specified held call.
The active could be a single call but also, could be already a conference.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | Reference of the active call. |
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 | media types | description |
|---|
| 204 | application/json
| No Content |
| 400 | application/json
| Bad Request |
| 401 | application/json
| Unauthorized |
| 403 | application/json
| Forbidden |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Associated notifications
/telephony/calls/{callRef}/overflowToVoiceMail
Methods
Redirects an outgoing ringing call to the voice mail of the called user.
Licenses
The license TELEPHONY_ADVANCED is 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 | 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 |
Associated notifications
/telephony/calls/{callRef}/park
Methods
(Standard user ONLY) Park a specified active call to a target device. If the device is not provided (in the ParkRequestDTO),
the call will be parked on the current device.
History
Since version 2.2.1
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | Reference of the active call to park. |
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 | 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 |
Associated notifications
/telephony/calls/{callRef}/participants
Methods
Returns the list of participants in a call.
Licenses
The license TELEPHONY_ADVANCED is 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 | Participants | 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 |
(Multimedia user ONLY) Adds a participant into an active call.
Licenses
The license TELEPHONY_ADVANCED is 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 | 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 |
Associated notifications
/telephony/calls/{callRef}/participants/{participantId}
Methods
Returns information about a participant in a call.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | Call reference.
|
| participantId | string | Reference of the participant |
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 | Participant | 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 |
Drops a participant from an active call: if the call is a single call, it is released; if it is a conference,
the call carries on without the participant.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | Call reference.
|
| participantId | string | Reference of the participant |
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 | 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 |
Associated notifications
/telephony/calls/{callRef}/recording
Methods
Starts, stops, pauses or resumes the recording of a call.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | Reference of the active call. |
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.
|
| action | string | Mandatory parameter. Possible values are start, stop, (Standard user ONLY) pause, (Standard user ONLY) resume. |
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 |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Associated notifications
/telephony/calls/{callRef}/redirect
Methods
Redirects an incoming ringing call to another user or number, instead of responding to it.
If redirectTo is equal to VOICEMAIL redirect an incoming ringing call to voice mail.
If redirectTo is equal to DVA Redirect an incoming ringing call to DVA.
Licenses
The license TELEPHONY_ADVANCED is 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 | 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
[+] : Redirect an incoming ringing call to DVA
request :POST https://server/api/rest/1.0/telephony/calls/e4c3a0564c030100/redirect
Content-Type: application/json
{
"redirectTo": "DVA"
}response :204 No Content
Associated notifications
/telephony/calls/{callRef}/retrieve
Methods
Retrieves a call that has been previously put in hold.
NOTE: Although it is possible for a standard user to invoke an answer on a held call instead of invoking a retrieve,
this is not the recommended usage. Furthermore, telephony event OnCallModified, sent after a held operation, does not list any answer
capability on the concerned leg.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | Call reference.
|
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 |
Associated notifications
/telephony/calls/{callRef}/sendDtmf
Methods
(Standard user ONLY) Sends DTMF in an active call.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | Call reference.
|
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 |
/telephony/calls/{callRef}/transfer
Methods
Transfers a specified active call to a specified held call.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | Reference of the active call |
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 | 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 |
Associated notifications
/telephony/devices
Methods
Gets states of all user devices
Licenses
The license TELEPHONY_ADVANCED is 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
The license TELEPHONY_ADVANCED is 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/devices/{deviceId}/mute/{mute}
Methods
Activate/deactivate ringing of a device
History
Since version 2.5
Request
path parameters| parameter | type | description |
|---|
| deviceId | string | device to mute/unmute |
| mute | string | `true` to mute, `false` to unmute |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | |
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 |
Associated notifications
/telephony/devices/{deviceId}/pickup
Methods
Picks up an incoming call on another user.
Licenses
The license TELEPHONY_ADVANCED is 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. |
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 |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Associated notifications
/telephony/devices/{deviceId}/unpark
Methods
(Standard user ONLY) UnPark a call from a target device. If the call has been parked on the current device,
the target device (contained in the ParkRequestDTO) should be omitted.
History
Since version 2.2.1
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| deviceId | string | device from where the unpark request is requested. |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
body parameter| type | media types | description |
|---|
| UnParkRequest | application/json
| |
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 |
Associated notifications
/telephony/incomingCallbacks
Methods
(Standard user ONLY) Returns the whole list of callback requests.
History
Since version 2.1.1
Licenses
The license TELEPHONY_ADVANCED is 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 | Callbacks | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
(Standard user ONLY) Deletes all callback requests.
History
Since version 2.1.1
Licenses
The license TELEPHONY_ADVANCED is 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 | 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 |
/telephony/incomingCallbacks/{callbackId}
Methods
(Standard user ONLY) Deletes a callback request.
History
Since version 2.1.1
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callbackId | string | identifier of the callback to delete |
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 | 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 |
/telephony/numbering/canonical
Methods
Transforms the phone number into canonical.
The result is formatted as specified in the pattern parameter. If no pattern is specified the default pattern "+C (A) xxxxxxxxxx" is used.
History
Since version 2.1
Licenses
No 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.
|
| phoneNumber | string | The phone number to transform.
Note that a phone number is considered valid if it contains numbers potentially
separated by any of the following characters: " ", "(", ")", "-", ".","/". |
| isPrefixIncluded | boolean | Specifies whether the external prefix is present in the phoneNumber parameter.
Note that the system systematically controls the phone number to determine if the phone number is consistent according
to this boolean information. For instance, if the external prefix (say it is configured to be 0) is supposed to be present the system won't
take this parameter into account if the phone number doesn't start by 0.
This parameter is particularly useful when the phone number starts by 00, to distinguish a national number with external prefix from an international number
(when local international prefix is 00). |
| resultPattern | string | The pattern to use to format the canonical number. If null a default pattern is used. The pattern syntax is as follows:
- C: stands for country code. Will print the country code (ITU standard)
- A: stands for area code or national prefix. Will print area code if useful otherwise will print the national prefix.
- a: stands for area code only. Will print the area code. If there is no area code according to the country dialing plan, prints nothing.
- x: represent a local number digit. Will copy the remaining digits from phoneNumber
- supported field separators are " ", "(", ")", "-", ".", "/"
Examples:
- the pattern "+33 (A) xxxxxxxx" is used to transform the French number "0298123456" in "+33 (0) 298123456"
- the pattern "+C (A) xxxxxxxx" will produce the same result as the previous one. It will transform the French number "0298123456" in "+33 (0) 298123456"
- the pattern "+C (A) xxx-xx-xx-xx" will transform the French number "0298123456" in "+33 (0) 298-12-34-56"
- the pattern "+C axxxxxxxx"will transform the French number "0298123456" in "+33 298123456"
- the pattern "+C (A) xxxxxxxx" will transform the German number "0301234567" in "+49 (30) 1234567"
- the pattern "+C axxxxxxxx" will transform the German number "0301234567" in "+49 301234567"
|
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
| code | type | media types | description |
|---|
| 200 | Numbering | 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/numbering/dialable
Methods
Transforms a phone number into a dialable number.
Basically this operation adds the external prefix to the phone number given as parameter (if necessary). To do so the system inspects the phone number to determine
if the external prefix must be added in order to make the phone number dialable:
- The external prefix can be added automatically if the phone number has more than X digits (X is the maximum number of digits of local phone number)
- In some cases it may be useful to distinguish internal phone numbers which look like external ones.
Thus an exception to the previous rule can be done for phone numbers of Y digits beginning with a particular pattern. Y is specified by
ExceptionRule#lengthException and the beginning pattern is specified by ExceptionRule#beginPatternException.
To do so, for each number of length equal to the one defined by ExceptionRule#lengthException , the system controls whether the phone number starts with a
specific pattern. When the beginning of the phone number matches this pattern, the system knows that it doesn't have to dial the external prefix
- Note that if the value of ExceptionRule#lengthException is equal to zero then the pattern control is done for any size of phone number
History
Since version 2.1
Licenses
No 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.
|
| phoneNumber | string | The phone number to transform |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
| code | type | media types | description |
|---|
| 200 | Numbering | 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/outgoingCallbacks
Methods
(Standard user ONLY) Requests for call back from an idle device.
History
Since version 2.1.1
Licenses
The license TELEPHONY_ADVANCED is 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
|
body parameter| type | media types | description |
|---|
| CallbackRequest | application/json
| call back information |
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 |
/telephony/state
Methods
Asks for the user telephonic state and capabilities.
Licenses
The license TELEPHONY_ADVANCED is 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 |
Representations
AddParticipantRequestRequest to add a participant.
| Name | Type | Cardinality | Description |
|---|
| callee | string | [1] | Called phone number. |
| anonymous | boolean | [0..1] | Anonymous call (secret identity).
This parameter is optional. If it is omitted, anonymous is not set for this call. |
| bypass | boolean | [0..1] | Bypass routing rules and presentation rules according to the callee.
This parameter is optional. If it is omitted, bypass is not done. |
Associated method :
Request to switch between an active call and a held call.
| Name | Type | Cardinality | Description |
|---|
| deviceId | string | [1] | Device phone number for which the operation is invoked.
If the session is opened by a User, the device phone number must be one of the user. |
Associated method :
Request to answer a ringing incoming call.
| Name | Type | Cardinality | Description |
|---|
| deviceId | string | [1] | Device phone number for which the operation is invoked.
If the session is opened by a User, the device phone number must be one of the user. |
Associated methods :
Request to transfer an incoming call.
| Name | Type | Cardinality | Description |
|---|
| transferTo | string | [1] | Phone number to which the call is transferred. |
| anonymous | boolean | [0..1] | Anonymous call (secret identity).
This parameter is optional. If it is omitted, anonymous is not set for this call. |
| bypass | boolean | [0..1] | Bypass routing rules and presentation rules according to the callee.
This parameter is optional. If it is omitted, bypass is not done. |
Associated method :
'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",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "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" ]
} ],
"capabilities": {
"addMedias": [ {
"type": "AUDIO | VIDEO | IM"
} ],
"addDevice": boolean,
"addParticipant": boolean,
"intruded": boolean,
"transfer": boolean,
"blindTransfer": boolean,
"merge": boolean,
"redirect": boolean,
"pickedUp": boolean,
"redirectToVoiceMail": boolean,
"redirectToDVA": boolean,
"overflowToVoiceMail": boolean,
"dropMe": boolean,
"terminate": boolean,
"reject": boolean,
"callBack": boolean,
"park": boolean,
"startRecord": boolean,
"stopRecord": boolean,
"pauseRecord": boolean,
"resumeRecord": boolean,
"dropParticipant": boolean,
"muteParticipant": boolean,
"holdParticipant": boolean
}
},
"legs": [ {
"deviceId": "string",
"media": "AUDIO | VIDEO | IM",
"state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
"capabilities": {
"answer": boolean,
"drop": boolean,
"hold": boolean,
"retrieve": boolean,
"reconnect": boolean,
"mute": boolean,
"unMute": boolean,
"sendDtmf": boolean,
"switchDevice": boolean
}
} ],
"participants": [ {
"participantId": "string",
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"anonymous": boolean,
"undroppable": boolean,
"state": "RINGING_INCOMING | ACTIVE",
"medias": [ "AUDIO | VIDEO | IM" ],
"mediaCapabilities": [ {
"type": "AUDIO | VIDEO | IM"
} ]
} ]
} |
Associated method :
Describes a callback.
| Name | Type | Cardinality | Description |
|---|
| callbackId | string | [1] | Callback identifier |
| partyInfo | PartyInfo | [1] | Participant identity card. |
[+] : JSON Example{
"callbackId": "string",
"partyInfo": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
}
} |
Callback Sender Message request data.
| Name | Type | Cardinality | Description |
|---|
| callee | string | [1] | Callee phone number of the called party for which a call back is requested. |
Associated method :
Container for the callbacks.
| Name | Type | Cardinality | Description |
|---|
| callbacks | Callback | [0..*] | List of callbacks |
[+] : JSON Example{
"callbacks": [ {
"callbackId": "string",
"partyInfo": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
}
} ]
} |
Associated method :
Describes the capabilities available on a call : the action that can be
carried out on the call according to its state.
| Name | Type | Cardinality | Description |
|---|
| addMedias | MediaCapability | [0..*] | Capability to add a media. |
| addDevice | boolean | [0..1] | Capability to add a participant or a user's device to this call. |
| addParticipant | boolean | [0..1] | Capability to add a participant. |
| intruded | boolean | [0..1] | Capability to intrude this call by another user. |
| transfer | boolean | [0..1] | Capability to transfer this call with another one. |
| blindTransfer | boolean | [0..1] | Capability to blind transfer this call to an user, device, ... |
| merge | boolean | [0..1] | Capability to merge this call with another one. |
| redirect | boolean | [0..1] | Capability to redirect this call to another user, device, ... |
| pickedUp | boolean | [0..1] | Capability to pick up this call by another user. |
| redirectToVoiceMail | boolean | [0..1] | Capability to redirect this call to the voice mail. |
| redirectToDVA | boolean | [0..1] | Capability to redirect this call to the DVA. |
| overflowToVoiceMail | boolean | [0..1] | Capability to overflow to the voice mail of the called user. |
| dropMe | boolean | [0..1] | Capability to drop me from this call. |
| terminate | boolean | [0..1] | Capability to terminate this call: call termiated on all users. |
| reject | boolean | [0..1] | Capability to reject this call. |
| callBack | boolean | [0..1] | Capability to invoke a call back. |
| park | boolean | [0..1] | Specifies whether the call can be parked.
Available only for Standard users.
|
| startRecord | boolean | [0..1] | Capability to start the record of the call. |
| stopRecord | boolean | [0..1] | Capability to stop the record of the call. |
| pauseRecord | boolean | [0..1] | Capability to pause the record of the call. |
| resumeRecord | boolean | [0..1] | Capability to resume the record of the call. |
| dropParticipant | boolean | [0..1] | Capability to drop a participant. |
| muteParticipant | boolean | [0..1] | Capability to mute/unMute a particpant.
This capabilty is not available in this release.
|
| holdParticipant | boolean | [0..1] | Capability to hold/retrieve a participant.
This capabilty is not available in this release.
|
[+] : JSON Example{
"addMedias": [ {
"type": "AUDIO | VIDEO | IM"
} ],
"addDevice": boolean,
"addParticipant": boolean,
"intruded": boolean,
"transfer": boolean,
"blindTransfer": boolean,
"merge": boolean,
"redirect": boolean,
"pickedUp": boolean,
"redirectToVoiceMail": boolean,
"redirectToDVA": boolean,
"overflowToVoiceMail": boolean,
"dropMe": boolean,
"terminate": boolean,
"reject": boolean,
"callBack": boolean,
"park": boolean,
"startRecord": boolean,
"stopRecord": boolean,
"pauseRecord": boolean,
"resumeRecord": boolean,
"dropParticipant": boolean,
"muteParticipant": boolean,
"holdParticipant": boolean
} |
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. |
| CONFERENCED | This is a multi-party call. |
| INVALID_NUMBER | The call is receiving the invalid number tone. |
| FORWARDED | The call has been forwarded. |
| PICKED_UP | The call has been picked up. |
| REDIRECTED | The call has been redirected. |
| TRANSFERRED | This is a transferred call. |
| UNKNOWN | Unknown cause. |
| PICKED_UP_TANDEM | Picked up tandem. |
| CALL_BACK | Since version 2.2.1 The call is a call back. |
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. |
| capabilities | CallCapabilities | [0..1] | Capabilities available on this call. |
[+] : JSON Example{
"initialCalled": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "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" ]
} ],
"capabilities": {
"addMedias": [ {
"type": "AUDIO | VIDEO | IM"
} ],
"addDevice": boolean,
"addParticipant": boolean,
"intruded": boolean,
"transfer": boolean,
"blindTransfer": boolean,
"merge": boolean,
"redirect": boolean,
"pickedUp": boolean,
"redirectToVoiceMail": boolean,
"redirectToDVA": boolean,
"overflowToVoiceMail": boolean,
"dropMe": boolean,
"terminate": boolean,
"reject": boolean,
"callBack": boolean,
"park": boolean,
"startRecord": boolean,
"stopRecord": boolean,
"pauseRecord": boolean,
"resumeRecord": boolean,
"dropParticipant": boolean,
"muteParticipant": boolean,
"holdParticipant": boolean
}
} |
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",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "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" ]
} ],
"capabilities": {
"addMedias": [ {
"type": "AUDIO | VIDEO | IM"
} ],
"addDevice": boolean,
"addParticipant": boolean,
"intruded": boolean,
"transfer": boolean,
"blindTransfer": boolean,
"merge": boolean,
"redirect": boolean,
"pickedUp": boolean,
"redirectToVoiceMail": boolean,
"redirectToDVA": boolean,
"overflowToVoiceMail": boolean,
"dropMe": boolean,
"terminate": boolean,
"reject": boolean,
"callBack": boolean,
"park": boolean,
"startRecord": boolean,
"stopRecord": boolean,
"pauseRecord": boolean,
"resumeRecord": boolean,
"dropParticipant": boolean,
"muteParticipant": boolean,
"holdParticipant": boolean
}
},
"legs": [ {
"deviceId": "string",
"media": "AUDIO | VIDEO | IM",
"state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
"capabilities": {
"answer": boolean,
"drop": boolean,
"hold": boolean,
"retrieve": boolean,
"reconnect": boolean,
"mute": boolean,
"unMute": boolean,
"sendDtmf": boolean,
"switchDevice": boolean
}
} ],
"participants": [ {
"participantId": "string",
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"anonymous": boolean,
"undroppable": boolean,
"state": "RINGING_INCOMING | ACTIVE",
"medias": [ "AUDIO | VIDEO | IM" ],
"mediaCapabilities": [ {
"type": "AUDIO | VIDEO | IM"
} ]
} ]
} ]
} |
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.
Available only for standard users.
|
| makePrivateCall | boolean | [0..1] | Specifies whether a personal call can be initiated.
Available only for standard users.
|
| unParkCall | boolean | [0..1] | Specifies whether a call can be an unparked call.
Available only for standard users.
|
Describes a user's device state.
| Name | Type | Cardinality | Description |
|---|
| deviceId | string | [1] | Device phone number. |
| state | OperationalState | [1] | Device state. |
| mutable | boolean | [1] | Since version 2.5 Indicates whether a device can be muted or not |
| muted | boolean | [1] | Since version 2.5 Indicates whether a device is muted or not |
[+] : JSON Example{
"deviceId": "string",
"state": "IN_SERVICE | OUT_OF_SERVICE | UNKNOWN",
"mutable": boolean,
"muted": boolean
} |
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",
"mutable": boolean,
"muted": boolean
} ]
} |
Associated method :
'hexBinary' is a built-in datatype that represents binary data encoded in hexadecimal format.
HoldRequestRequest to put an active call on hold.
| Name | Type | Cardinality | Description |
|---|
| deviceId | string | [1] | Device phone number for which the operation is invoked.
If the session is opened by a User, the device phone number must be one of the user. |
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. |
| instantMessagingId | string | [0..1] | Instant messaging identity. |
'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).
[+] : JSON Example{
"deviceId": "string",
"media": "AUDIO | VIDEO | IM",
"state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
"capabilities": {
"answer": boolean,
"drop": boolean,
"hold": boolean,
"retrieve": boolean,
"reconnect": boolean,
"mute": boolean,
"unMute": boolean,
"sendDtmf": boolean,
"switchDevice": boolean
}
} |
Associated method :
Describes the capabilities of a leg :
The action that can be carried out on the leg according to its state.
| Name | Type | Cardinality | Description |
|---|
| answer | boolean | [0..1] | Capability to answer to an incoming call. |
| drop | boolean | [0..1] | Capability to drop this media device. |
| hold | boolean | [0..1] | Capability to hold this call in order to retrieve it later. |
| retrieve | boolean | [0..1] | Capability to retrieve an hold call. |
| reconnect | boolean | [0..1] | Capability to retrieve an hold call and releasing the current active call. |
| mute | boolean | [0..1] | Capability to enable mute for this leg. |
| unMute | boolean | [0..1] | Capability to disable mute for this device. |
| sendDtmf | boolean | [0..1] | Capability to send DTMF codes for this leg. |
| switchDevice | boolean | [0..1] | Capability to switch this device to another one. |
Container for Legs.
| Name | Type | Cardinality | Description |
|---|
| legs | Leg | [0..*] | List of Leg. |
[+] : JSON Example{
"legs": [ {
"deviceId": "string",
"media": "AUDIO | VIDEO | IM",
"state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
"capabilities": {
"answer": boolean,
"drop": boolean,
"hold": boolean,
"retrieve": boolean,
"reconnect": boolean,
"mute": boolean,
"unMute": boolean,
"sendDtmf": boolean,
"switchDevice": boolean
}
} ]
} |
Associated method :
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. |
Request to initiate a new call.
| Name | Type | Cardinality | *1 | *2 | Description |
|---|
| deviceId | string | [1] | X | X | Device phone number for which the operation is invoked.
If the session is opened by a User, the device phone number must be one of the user. |
| callee | string | [1] | X | X | Called phone number. |
| autoAnswer | boolean | [0..1] | X | | Automatic answer on make call.
If this parameter is set to "false" (or omitted) the deviceId is called before
launching the make call to callee, else callee is called immediately. |
*1 : attributes for a call from an OpenTouch user set:
deviceId and
callee are mandatory,
autoAnswer is optional
*2 : attributes for a call from any connected set which is not associated to an OpenTouch user:
deviceId and
callee are mandatory; Allowed only when logged in an administrator session.
Associated method :
Request to initiate a new call.
| Name | Type | Cardinality | *1 | *2 | *3 | *4 | Description |
|---|
| deviceId | string | [0..1] | X | X | X | X | Device phone number for which the operation is invoked.
If the session is opened by a User, the device phone number must be one of the user.
This parameter is mandatory for a MULTIMEDIA user.
This parameter is optional for a STANDARD user . (When omitted the main device is used) |
| callee | string | [1] | X | X | X | X | Called phone number. |
| autoAnswer | boolean | [0..1] | X | | | | Automatic answer on make call.
If this parameter is set to "false" (or omitted) the deviceId is called before
launching the make call to callee, else callee is called immediately. |
| bypass | boolean | [0..1] | X | | | | |
| associatedData | hexBinary | [0..1] | X | | | | (Standard user ONLY) This is used by the application to provide application-related information (limited to 32 bytes).
In general, it is used to give information concerning a previously established call to the party of a second call.
Don't use in conjonction with pin, secretCode, or businessCode parameter |
| pin | string | [0..1] | | X | | | (Standard user ONLY) Private identity number (Mandatory when making a Private Call).
Don't use in conjonction with associatedData or businessCode parameter |
| secretCode | string | [0..1] | | X | | | (Standard user ONLY) Secret code (Mandatory when making a Private Call).
Don't use in conjonction with associatedData or businessCode parameter |
| businessCode | string | [0..1] | | | X | | (Standard user ONLY) The cost center on which the call will be charged (Mandatory when making a Business Call).
Don't use in conjonction with associatedData, pin, or secretCode parameter |
*1 : attributes for a call from an OpenTouch user set:
deviceId and
callee are mandatory,
autoAnswer,
bypass and
associatedData are optional
*2 : attributes for a private call from a Standard OpenTouch user set:
deviceId,
callee,
pin and
secretCode are mandatory
*3 : attributes for a business call from a Standard OpenTouch user set:
deviceId,
callee and
businessCode are mandatory
*4 : attributes for a call from any connected set which is not associated to an OpenTouch user:
deviceId and
callee are mandatory; Allowed only when logged in an administrator session.
Associated method :
Describes a media capabilty.
| Name | Type | Cardinality | Description |
|---|
| type | MediaType | [1] | Type of media (audio, video, ...). |
[+] : JSON Example{
"type": "AUDIO | VIDEO | IM"
} |
Lists the different media states.
| Value | Description |
|---|
| UNKNOWN | Unknown media state. |
| OFF_HOOK | The device is off-hook. |
| 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). |
Lists the different type of medias.
| Value | Description |
|---|
| AUDIO | Audio media. |
| VIDEO | Video media. |
| IM | Instant message media. |
Request to merge two calls, the active one and the held one.
| Name | Type | Cardinality | Description |
|---|
| heldCallRef | string | [1] | Reference of the held call. |
Associated method :
Describes numbering response.
Contains either a dialable or canonical phone number, depending on the request.
| Name | Type | Cardinality | Description |
|---|
| dialable | string | [0..1] | The dialable phone number, when requested. |
| canonical | string | [0..1] | The canonical phone number, when requested. |
Associated methods :
This notification indicates that a new call for mobile device has been created.
It is very similar to existing
OnCallCreated,
but the
OnCallAppeared must be sent only when the REX leg is added to a call
to initiate alerting of the mobile device.
The structure and content of the event is the same, as by
OnCallCreated.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnCallAppeared' |
| 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 | CONFERENCED | INVALID_NUMBER | ...",
"callData": {
"initialCalled": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "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" ]
} ],
"capabilities": {
"addMedias": [ {
"type": "AUDIO | VIDEO | IM"
} ],
"addDevice": boolean,
"addParticipant": boolean,
"intruded": boolean,
"transfer": boolean,
"blindTransfer": boolean,
"merge": boolean,
"redirect": boolean,
"pickedUp": boolean,
"redirectToVoiceMail": boolean,
"redirectToDVA": boolean,
"overflowToVoiceMail": boolean,
"dropMe": boolean,
"terminate": boolean,
"reject": boolean,
"callBack": boolean,
"park": boolean,
"startRecord": boolean,
"stopRecord": boolean,
"pauseRecord": boolean,
"resumeRecord": boolean,
"dropParticipant": boolean,
"muteParticipant": boolean,
"holdParticipant": boolean
}
},
"initiator": "string",
"legs": [ {
"deviceId": "string",
"media": "AUDIO | VIDEO | IM",
"state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
"capabilities": {
"answer": boolean,
"drop": boolean,
"hold": boolean,
"retrieve": boolean,
"reconnect": boolean,
"mute": boolean,
"unMute": boolean,
"sendDtmf": boolean,
"switchDevice": boolean
}
} ],
"participants": [ {
"participantId": "string",
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"anonymous": boolean,
"undroppable": boolean,
"state": "RINGING_INCOMING | ACTIVE",
"medias": [ "AUDIO | VIDEO | IM" ],
"mediaCapabilities": [ {
"type": "AUDIO | VIDEO | IM"
} ]
} ],
"deviceCapabilities": [ {
"deviceId": "string",
"makeCall": boolean,
"makeBusinessCall": boolean,
"makePrivateCall": boolean,
"unParkCall": boolean
} ]
} |
Associated method :
Notification is sent when new callback request is added.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnCallbackRequestAdded' |
| loginName | string | [1] | Login name of the user receiving the event. |
| firstName | string | [1] | First name of the user receiving the event. |
| lastName | string | [1] | Last name of the user receiving the event. |
| phoneNumber | string | [1] | Phone number of the user receiving the event. |
| callbackRequestId | string | [1] | Callback request id. |
| callbacksNumber | int | [1] | Number of all callbacks for this user. |
Associated method :
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 | CONFERENCED | INVALID_NUMBER | ...",
"callData": {
"initialCalled": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "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" ]
} ],
"capabilities": {
"addMedias": [ {
"type": "AUDIO | VIDEO | IM"
} ],
"addDevice": boolean,
"addParticipant": boolean,
"intruded": boolean,
"transfer": boolean,
"blindTransfer": boolean,
"merge": boolean,
"redirect": boolean,
"pickedUp": boolean,
"redirectToVoiceMail": boolean,
"redirectToDVA": boolean,
"overflowToVoiceMail": boolean,
"dropMe": boolean,
"terminate": boolean,
"reject": boolean,
"callBack": boolean,
"park": boolean,
"startRecord": boolean,
"stopRecord": boolean,
"pauseRecord": boolean,
"resumeRecord": boolean,
"dropParticipant": boolean,
"muteParticipant": boolean,
"holdParticipant": boolean
}
},
"initiator": "string",
"legs": [ {
"deviceId": "string",
"media": "AUDIO | VIDEO | IM",
"state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
"capabilities": {
"answer": boolean,
"drop": boolean,
"hold": boolean,
"retrieve": boolean,
"reconnect": boolean,
"mute": boolean,
"unMute": boolean,
"sendDtmf": boolean,
"switchDevice": boolean
}
} ],
"participants": [ {
"participantId": "string",
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"anonymous": boolean,
"undroppable": boolean,
"state": "RINGING_INCOMING | ACTIVE",
"medias": [ "AUDIO | VIDEO | IM" ],
"mediaCapabilities": [ {
"type": "AUDIO | VIDEO | IM"
} ]
} ],
"deviceCapabilities": [ {
"deviceId": "string",
"makeCall": boolean,
"makeBusinessCall": boolean,
"makePrivateCall": boolean,
"unParkCall": boolean
} ]
} |
Associated methods :
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 | CONFERENCED | INVALID_NUMBER | ...",
"previousCallRef": "string",
"replacedByCallRef": "string",
"callData": {
"initialCalled": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "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" ]
} ],
"capabilities": {
"addMedias": [ {
"type": "AUDIO | VIDEO | IM"
} ],
"addDevice": boolean,
"addParticipant": boolean,
"intruded": boolean,
"transfer": boolean,
"blindTransfer": boolean,
"merge": boolean,
"redirect": boolean,
"pickedUp": boolean,
"redirectToVoiceMail": boolean,
"redirectToDVA": boolean,
"overflowToVoiceMail": boolean,
"dropMe": boolean,
"terminate": boolean,
"reject": boolean,
"callBack": boolean,
"park": boolean,
"startRecord": boolean,
"stopRecord": boolean,
"pauseRecord": boolean,
"resumeRecord": boolean,
"dropParticipant": boolean,
"muteParticipant": boolean,
"holdParticipant": boolean
}
},
"modifiedLegs": [ {
"deviceId": "string",
"media": "AUDIO | VIDEO | IM",
"state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
"capabilities": {
"answer": boolean,
"drop": boolean,
"hold": boolean,
"retrieve": boolean,
"reconnect": boolean,
"mute": boolean,
"unMute": boolean,
"sendDtmf": boolean,
"switchDevice": boolean
}
} ],
"addedLegs": [ {
"deviceId": "string",
"media": "AUDIO | VIDEO | IM",
"state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
"capabilities": {
"answer": boolean,
"drop": boolean,
"hold": boolean,
"retrieve": boolean,
"reconnect": boolean,
"mute": boolean,
"unMute": boolean,
"sendDtmf": boolean,
"switchDevice": boolean
}
} ],
"removedLegs": [ {
"deviceId": "string",
"media": "AUDIO | VIDEO | IM",
"state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
"capabilities": {
"answer": boolean,
"drop": boolean,
"hold": boolean,
"retrieve": boolean,
"reconnect": boolean,
"mute": boolean,
"unMute": boolean,
"sendDtmf": boolean,
"switchDevice": boolean
}
} ],
"modifiedParticipants": [ {
"participantId": "string",
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"anonymous": boolean,
"undroppable": boolean,
"state": "RINGING_INCOMING | ACTIVE",
"medias": [ "AUDIO | VIDEO | IM" ],
"mediaCapabilities": [ {
"type": "AUDIO | VIDEO | IM"
} ]
} ],
"addedParticipants": [ {
"participantId": "string",
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"anonymous": boolean,
"undroppable": boolean,
"state": "RINGING_INCOMING | ACTIVE",
"medias": [ "AUDIO | VIDEO | IM" ],
"mediaCapabilities": [ {
"type": "AUDIO | VIDEO | IM"
} ]
} ],
"removedParticipantIds": [ "string" ],
"deviceCapabilities": [ {
"deviceId": "string",
"makeCall": boolean,
"makeBusinessCall": boolean,
"makePrivateCall": boolean,
"unParkCall": boolean
} ]
} |
Associated methods :
This notification indicates that a call have 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 | CONFERENCED | INVALID_NUMBER | ...",
"newDestination": "string",
"deviceCapabilities": [ {
"deviceId": "string",
"makeCall": boolean,
"makeBusinessCall": boolean,
"makePrivateCall": boolean,
"unParkCall": boolean
} ]
} |
Associated methods :
This notification indicates that a mute request failed.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnDeviceMuteFailed' |
| loginName | string | [1] | Login name of a user |
| deviceId | string | [1] | Directory number of a device |
| nativeCode | string | [1] | Native code of an error |
| info | string | [1] | Information about an error |
Associated method :
This notification indicates that a mute request was successful.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnDeviceMuteSuccess' |
| loginName | string | [1] | Login name of a user |
| deviceId | string | [1] | Directory number of a device |
| mute | boolean | [1] | Mute state of a device (true/false) |
Associated method :
This notification indicates that device's state have 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",
"mutable": boolean,
"muted": boolean
} ]
} |
This notification indicates that user's state have 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 methods :
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. |
Request to park an active call on a target device.
If the call shall be parked on the current device, just omit the target device
| Name | Type | Cardinality | Description |
|---|
| parkTo | string | [0..1] | Phone number device where to park the call . |
Associated method :
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] | Since version 2.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. |
| medias | MediaType | [0..*] | Medias involved for this participant. |
| mediaCapabilities | MediaCapability | [0..*] | Media capabilities of the participant. |
[+] : JSON Example{
"participantId": "string",
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"anonymous": boolean,
"undroppable": boolean,
"state": "RINGING_INCOMING | ACTIVE",
"medias": [ "AUDIO | VIDEO | IM" ],
"mediaCapabilities": [ {
"type": "AUDIO | VIDEO | IM"
} ]
} |
Associated method :
Container for Participants.
| Name | Type | Cardinality | Description |
|---|
| participants | Participant | [0..*] | Container for Participants. |
[+] : JSON Example{
"participants": [ {
"participantId": "string",
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"anonymous": boolean,
"undroppable": boolean,
"state": "RINGING_INCOMING | ACTIVE",
"medias": [ "AUDIO | VIDEO | IM" ],
"mediaCapabilities": [ {
"type": "AUDIO | VIDEO | IM"
} ]
} ]
} |
Associated method :
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 "ace", "automated-attendant", "cba", "conferencing", "dva", "msml", "one-number", "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 |
| vcardUrl | string | [0..1] | DEPRECATED: use vcardPath instead |
| vcardPath | string | [0..1] | Since version 2.2 User's vCard relative URL.
Note: To build an absolute URL, this relative path value have to be concatenated with the VCARD base URL.
This VCARD base URL can be retrieved using "Location information" service:
GET http(s)://<server>/api/rest/locator/services?names=VCARD
|
| type | ParticipantType | [0..1] | Type of participant. |
[+] : JSON Example{
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
} |
Request to pickup a call.
| Name | Type | Cardinality | Description |
|---|
| otherCallRef | string | [0..1] | Reference of the call to pickup (on the remote user). |
| otherPhoneNumber | string | [1] | Phone number on which the call is to pickup. |
| autoAnswer | boolean | [0..1] |
True to automatically chain an answer call request after this pickup request (if omitted default value is false).
Note: if the user is a multimedia user and if the user to pickup is a standard user, the autoAnwser can only
be done on devices selected in the presentation route of the multimedia user (else the service is rejected).
|
Associated method :
Lists the different state when recording.
| Value | Description |
|---|
| PAUSED | Recording is paused. |
| RECORDING | Recording is in progress. |
Request to redirect a call.
| Name | Type | Cardinality | Description |
|---|
| redirectTo | string | [1] | Phone number of the target of the redirection |
| anonymous | boolean | [0..1] | Anonymous call (secret identity).
This parameter is optional. If it is omitted, anonymous is not set for this call. |
| bypass | boolean | [0..1] | |
Associated method :
[Tel]: Request to redirect a call.
| Name | Type | Cardinality | Description |
|---|
| deviceId | string | [1] | Device phone number for which the operation is invoked.
If the session is opened by a User, the device phone number must be one of the user. |
Associated method :
SendAssociatedDataRequestRequest to send associated data.
| Name | Type | Cardinality | Description |
|---|
| deviceId | string | [1] | Device phone number for which the operation is invoked.
If the session is opened by a User, the device phone number must be one of the user. |
| associatedData | hexBinary | [1] | (Standard user ONLY)
This is used by the application to provide application-related information (limited to 32 bytes).
In general, it is used to give information concerning a previously established call to the party of a second call. |
Associated method :
Request to send DTMF
| Name | Type | Cardinality | Description |
|---|
| deviceId | string | [1] | Device phone number for which the operation is invoked.
If the session is opened by a User, the device phone number must be one of the user. |
| number | string | [1] | DTMF codes. |
Associated method :
'string' represents character strings.
SwitchDeviceRequestRequest to switch between two devices.
| Name | Type | Cardinality | Description |
|---|
| otherDeviceId | string | [1] | Device phone number on which to switch. |
Associated method :
Describes a Tag (a defined name and a value).
| Name | Type | Cardinality | Description |
|---|
| name | string | [1] | Tag name. |
| value | string | [0..1] | Tag value. |
| visibilities | string | [0..*] | Visibility of this tag : list of login name. |
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. |
[+] : JSON Example{
"calls": [ {
"callRef": "string",
"callData": {
"initialCalled": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "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" ]
} ],
"capabilities": {
"addMedias": [ {
"type": "AUDIO | VIDEO | IM"
} ],
"addDevice": boolean,
"addParticipant": boolean,
"intruded": boolean,
"transfer": boolean,
"blindTransfer": boolean,
"merge": boolean,
"redirect": boolean,
"pickedUp": boolean,
"redirectToVoiceMail": boolean,
"redirectToDVA": boolean,
"overflowToVoiceMail": boolean,
"dropMe": boolean,
"terminate": boolean,
"reject": boolean,
"callBack": boolean,
"park": boolean,
"startRecord": boolean,
"stopRecord": boolean,
"pauseRecord": boolean,
"resumeRecord": boolean,
"dropParticipant": boolean,
"muteParticipant": boolean,
"holdParticipant": boolean
}
},
"legs": [ {
"deviceId": "string",
"media": "AUDIO | VIDEO | IM",
"state": "UNKNOWN | OFF_HOOK | IDLE | RELEASING | DIALING | HELD | RINGING_INCOMING | ...",
"capabilities": {
"answer": boolean,
"drop": boolean,
"hold": boolean,
"retrieve": boolean,
"reconnect": boolean,
"mute": boolean,
"unMute": boolean,
"sendDtmf": boolean,
"switchDevice": boolean
}
} ],
"participants": [ {
"participantId": "string",
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"vcardPath": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"anonymous": boolean,
"undroppable": boolean,
"state": "RINGING_INCOMING | ACTIVE",
"medias": [ "AUDIO | VIDEO | IM" ],
"mediaCapabilities": [ {
"type": "AUDIO | VIDEO | IM"
} ]
} ]
} ],
"deviceCapabilities": [ {
"deviceId": "string",
"makeCall": boolean,
"makeBusinessCall": boolean,
"makePrivateCall": boolean,
"unParkCall": boolean
} ]
} |
Associated method :
Request to transfer the held call to a new destination.
| Name | Type | Cardinality | Description |
|---|
| heldCallRef | string | [1] | Reference of the held call. |
Associated method :
Request to unpark a call from a target device where the call has been parked.
If the call has been parked on the current device, the target device is not required.
| Name | Type | Cardinality | Description |
|---|
| unParkFrom | string | [0..1] | Phone number of the device where the call has been parked. |
Associated method :
Lists the different types of user state.
| Value | Description |
|---|
| FREE | User is free. |
| BUSY | User is busy. |
| UNKNOWN | The user state is unknown. |
Directory search
Presentation
The directory resource is used to search for a contact in several directories:
- OXE call server phone book
- LDAP corporate directories
- OT internal system database
Operations can be invoked using:
- A user session having the TELEPHONY_ADVANCED license.
- An administrator supervising a user having the TELEPHONY_ADVANCED license.
- An administrator without any delegation or account supervision.
Resources summary
Resources
/directory/attributes
Methods
Retrieves the list of the available attributes.
History
Since version 2.6
Licenses
The license TELEPHONY_ADVANCED is 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 | Attributes | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Examples
[+] : Gets the list of available attributes
request :GET https://server/api/rest/1.0/directory/attributes
response :200 OK
Content-Type: application/json
{"attributes":["GIVENNAME","MAIL","MOBILEPHONE","LOGIN","FULLNAME","SN","TELEPHONENUMBER"]} /directory/attributes/{attribute}
Methods
Gets the properties of a specified attribute.
History
Since version 2.6
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| attribute | Attribute | the attribute identifier |
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 | AttributeProperties | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Examples
[+] : Gets the properties of attribute FULLNAME
request :GET https://server/api/rest/1.0/directory/attributes/lastName
response :200 OK
Content-Type: application/json
{
"label":"SN",
"type":"NAME",
"usableForDisplay":true,
"usableForSearch":true
} /directory/directories
Methods
Retrieves the list of the available directories.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters| parameter | type | description |
|---|
| loginName | string | Optional login name of the user for whom an administrator wants to invoke the request. |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
| code | type | media types | description |
|---|
| 200 | Directories | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Examples
[+] : Retrieves the list of the available directories
request :GET https://server/api/rest/1.0/directory/directories
Content-Type: application/json
response :200 OK
Content-Type: application/json
{"directories": [{"id":"merged_directory",
"label":"Merged Directory",
"type":"MERGED_DIRECTORY"
}
]
} /directory/search
Methods
Initiates a search
Note: For the whole solution only 100 concurrent searches are authorized.
For each session (user or administrator), only 5 concurrent searches are authorized.
An unused search context is freed after 1 minute.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters| parameter | type | description |
|---|
| loginName | string | Optional login name of the user for whom an administrator wants to invoke the request. |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
| code | type | media types | description |
|---|
| 201 | string | application/json
| CREATED |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Examples
[+] : Initiates a search
request :POST https://server/api/rest/1.0/directory/search
Content-Type: application/json
{
"directories": [
"merged_directory"
],
"filter" : {
"field": "lastName",
"operation": "BEGIN_WITH",
"operand": "L"
},
"limit": 3,
"attributes": [
"id.phoneNumber",
"id.email",
"id.loginName",
"attribute1",
"photo"
],
"mandatoryAttributes": [
"id.email",
"attribute1"
]
}response :201 Created
Location: http://server/api/rest/1.0/directory/search/
Gets the next available results for the current search.
The principle for executing a search is as follows:
Start a search using the previous operations
Call the getSearch operation in a loop and for each iteration :
- if the
status is NOK, the search is in progress but no result is available : it is recommended to wait before the next iteration (500ms for example)
- if the
status result code is OK, you can process the results
- if the
status result code is FINISH or TIMEOUT, exit the loop
At each iteration you can stop the search using the stopSearch operation and exit the loop.
Note: For the whole solution only 100 concurrent searches are authorized.
For each session (user or administrator), only 5 concurrent searches are authorized.
An unused search context is freed after 1 minute.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters| parameter | type | description |
|---|
| loginName | string | Optional login name of the user for whom an administrator wants to invoke the request. |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
| code | type | media types | description |
|---|
| 200 | SearchResult | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Examples
[+] : Gets the next available results
request :GET https://server/api/rest/1.0/directory/search
Accept: application/json
response :200 OK
Content-Type: application/json
{"resultCode":"OK",
"resultElements":[
{"directorySource":"merged_directory",
"contacts":[
{"id": {"loginName":"auto10000@localdomain",
"email":"auto10000@domain",
"phoneNumber":"10000"
},
"firstName":"F10000",
"lastName":"L10000",
"vcardPath":"/udas/vcards/au/auto10000.vcf?2f95c1a3e9ee4a732d0dd77fdc5077cb"
}
]
},
]
} [+] : Gets the next available results
request :GET https://server/api/rest/1.0/directory/search
Accept: application/json
response :200 OK
Content-Type: application/json
{"resultCode":"OK",
"resultElements":[
{
"contacts":[
{"id": {"loginName":"oxe10000",
"phoneNumber":"10000"
},
"firstName":"F10000",
"lastName":"L10000"
}
]
},
]
} Deletes (stops) search query
Note: For the whole solution only 100 concurrent searches are authorized.
For each session (user or administrator), only 5 concurrent searches are authorized.
An unused search context is freed after 1 minute.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters| parameter | type | description |
|---|
| loginName | string | Optional login name of the user for whom an administrator wants to invoke the request. |
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 |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Examples
[+] : Deletes search query
request :DELETE https://server/api/rest/1.0/directory/search
Accept: application/json
response :204 No Content
Representations
AttributeLists the different types of attributes.
| Value | Description |
|---|
| lastName | Last name. |
| firstName | First name. |
| FULLNAME | Since version 2.6 Full name. |
| id.phoneNumber | The format of the value of an attribute of type PHONENUMBER can be "displaynumber"<dialable number>.
displaynumber is the phone number which will be displayed on the device or on the application.
displaynumber is written between two double quote characters.
dialable number is the phone number which will be used to dial by the device or by the application.
dialable number is written between less than sign and greater than sign character.
The usual format is always possible when no difference is made between the display number and the dialable number. |
| MOBILEPHONE | Since version 2.6 Mobile phone. |
| id.email | Email. |
| id.loginName | Login name. |
| attribute1 | Since version 2.6 Custom attribute1 |
| attribute2 | Since version 2.6 Custom attribute2 |
| attribute3 | Since version 2.6 Custom attribute3 |
| attribute4 | Since version 2.6 Custom attribute4 |
| attribute5 | Since version 2.6 Custom attribute5 |
| IMPP | Since version 2.6 Instant Messaging Id. |
| OTNODE | Since version 2.6 OT Node. |
| VCARD | Since version 2.6 Vcard. |
| PHOTO | Since version 2.6 Photo url. |
| UNKNOWN | Since version 2.6 Unknown. |
Attribute properties
| Name | Type | Cardinality | Description |
|---|
| label | string | [1] | Since version 2.6 label |
| type | AttributeType | [1] | Since version 2.6 type |
| usableForDisplay | boolean | [1] | Since version 2.6 usable for display |
| usableForSearch | boolean | [1] | Since version 2.6 usable for search |
[+] : JSON Example{
"label": "string",
"type": "MAIL | NAME | OTHER | PHONENUMBER | PHOTO",
"usableForDisplay": boolean,
"usableForSearch": boolean
} |
Associated method :
List of attributes
| Name | Type | Cardinality | Description |
|---|
| attributes | Attribute | [0..*] | List of attributes objects. |
[+] : JSON Example{
"attributes": [ "lastName | firstName | FULLNAME | id.phoneNumber | MOBILEPHONE | id.email | ..." ]
} |
Associated method :
Type of attribute
| Value | Description |
|---|
| MAIL | |
| NAME | |
| OTHER | |
| PHONENUMBER | |
| PHOTO | |
'boolean' is a data type, having two values (true and false).
CriterionCriterion descriptor.
[+] : JSON Example 1 {
"field": "lastName | firstName | FULLNAME | id.phoneNumber | MOBILEPHONE | id.email | ...",
"operation": "OR | AND | EQUAL_IGNORE_CASE | BEGIN_WITH | CONTAIN | END_WITH",
"operand": "string" or [ { Criterion } ]
}[+] : JSON Example 2 {
"field": "lastName",
"operation": "BEGIN_WITH",
"operand": "last"
}[+] : JSON Example 3 {
"operation": "AND",
"operand": [
{
"field": "firstName",
"operation": "BEGIN_WITH",
"operand": "first"
},
{
"field": "lastName",
"operation": "BEGIN_WITH",
"operand": "last"
}
]
} |
List of directory objects
| Name | Type | Cardinality | Description |
|---|
| directories | Directory | [0..*] | List of directory objects. |
[+] : JSON Example{
"directories": [ {
"id": "string",
"label": "string",
"type": "CALLSERVER | LDAP | OT_SYSTEM_DIRECTORY | MERGED_DIRECTORY | UNKNOWN"
} ]
} |
Associated method :
Description of a directory
| Name | Type | Cardinality | Description |
|---|
| id | string | [1] | Directory identifier. |
| label | string | [1] | Directory label. |
| type | DirectoryType | [1] | Directory type. |
[+] : JSON Example{
"id": "string",
"label": "string",
"type": "CALLSERVER | LDAP | OT_SYSTEM_DIRECTORY | MERGED_DIRECTORY | UNKNOWN"
} |
The different types of supported directories.
| Value | Description |
|---|
| CALLSERVER | Phone book of the call server. |
| LDAP | LDAP directory. |
| OT_SYSTEM_DIRECTORY | OT internal system directory. |
| MERGED_DIRECTORY | Merged phone book: OT system is configured to merge all or part of defined phone books to a unique phone book. |
| UNKNOWN | Unknown type. |
Description of Identifier
| Name | Type | Cardinality | Description |
|---|
| loginName | string | [0..1] | Login name |
| instantMessagingId | string | [0..1] | Instant messaging identifier |
| email | string | [0..1] | Email |
| phoneNumber | string | [0..1] | Phone number |
'int' is a 32-bit number (-2147483648 to 2147483647).
OperationThe types of operation
| Value | Description |
|---|
| OR | OR operation. |
| AND | AND operation. |
| EQUAL_IGNORE_CASE | EQUAL_IGNORE operation. |
| BEGIN_WITH | BEGIN_WITH operation. |
| CONTAIN | CONTAIN operation. |
| END_WITH | END_WITH operation. |
Description of PartyInfo
| Name | Type | Cardinality | Description |
|---|
| id | Identifier | [0..1] | PartyInfo identifier object |
| firstName | string | [0..1] | First name |
| lastName | string | [0..1] | Last name |
| vcardPath | string | [0..1] | Since version 2.2 User's vCard relative URL.
Note: To build an absolute URL, this relative path value have to be concatenated with the VCARD base URL.
This VCARD base URL can be retrieved using "Location information" service:
GET http(s)://<server>/api/rest/locator/services?names=VCARD
|
| photo | string | [0..1] | Since version 2.6 Photo |
| fullName | string | [0..1] | Since version 2.6 Full name |
| attribute1 | string | [0..1] | Since version 2.6 Custom attribute 1 |
| attribute2 | string | [0..1] | Since version 2.6 Custom attribute 2 |
| attribute3 | string | [0..1] | Since version 2.6 Custom attribute 3 |
| attribute4 | string | [0..1] | Since version 2.6 Custom attribute 4 |
| attribute5 | string | [0..1] | Since version 2.6 Custom attribute 5 |
| mobilePhone | string | [0..1] | Since version 2.6 Mobile phone |
| otNode | string | [0..1] | Since version 2.6 OT Node |
[+] : JSON Example{
"id": {
"loginName": "string",
"instantMessagingId": "string",
"email": "string",
"phoneNumber": "string"
},
"firstName": "string",
"lastName": "string",
"vcardPath": "string",
"photo": "string",
"fullName": "string",
"attribute1": "string",
"attribute2": "string",
"attribute3": "string",
"attribute4": "string",
"attribute5": "string",
"mobilePhone": "string",
"otNode": "string"
} |
This code is returned each time you try to retrieve responses after a search
has been started (
getNextResults operation).
| Value | Description |
|---|
| OK | Responses are provided this time. You will have to continue to invoke getNextResults periodically to get the next response. |
| NOK | No responses this time. You will have to continue to invoke getNextResults periodically to get the next response. |
| FINISH | Search is finished. You no longer need to invoke getNextResults, there are no more responses. |
| TIMEOUT | Search is ended for timeout reason. You no longer need to invoke getNextResults, there are no more responses. |
Gives a result which matches the criterion given in search operation.
The records are obtained by periodically invoking the
getNextResults operation.
| Name | Type | Cardinality | Description |
|---|
| directorySource | string | [1] | The directory identifier from which the result has been found. |
| contacts | PartyInfo | [0..*] | Array of ContactDTO objects |
[+] : JSON Example{
"directorySource": "string",
"contacts": [ {
"id": {
"loginName": "string",
"instantMessagingId": "string",
"email": "string",
"phoneNumber": "string"
},
"firstName": "string",
"lastName": "string",
"vcardPath": "string",
"photo": "string",
"fullName": "string",
"attribute1": "string",
"attribute2": "string",
"attribute3": "string",
"attribute4": "string",
"attribute5": "string",
"mobilePhone": "string",
"otNode": "string"
} ]
} |
This element is used to start an advanced search.
| Name | Type | Cardinality | Description |
|---|
| directories | string | [0..*] | The list of directory identifiers on which to search (if null, default directories are used).
These identifiers can be retrieved using the getDirectories operation. |
| limit | int | [0..1] | Since version 2.0.2 Maximum number of results. Default value is 100.
The range of supported values is [1 .. 100]. |
| filter | Criterion | [1] | searching criterion. |
| mandatoryAttributes | Attribute | [0..*] | Since version 2.6 List of attributes which should not be empty.
This is additional criterion/filter, which says that this attributes must be present(should not be null) for user.
This list does not affect list of returned attributes.
By default is empty list. |
| attributes | Attribute | [0..*] | Since version 2.6 List of returned attributes.
By default SN("lastName"), GIVENNAME("firstName"), TELEPHONENUMBER("id.phoneNumber"), MAIL("id.email"), LOGIN("id.loginName"), VCARD("vcard"), PHOTO("photo"), OTNODE("otnode"). |
[+] : JSON Example{
"directories": [ "string" ],
"limit": int,
"filter": {
"field": "lastName | firstName | FULLNAME | id.phoneNumber | MOBILEPHONE | id.email | ...",
"operation": "OR | AND | EQUAL_IGNORE_CASE | BEGIN_WITH | CONTAIN | END_WITH",
"operand": "string" or [ { Criterion } ]
},
"mandatoryAttributes": [ "lastName | firstName | FULLNAME | id.phoneNumber | MOBILEPHONE | id.email | ..." ],
"attributes": [ "lastName | firstName | FULLNAME | id.phoneNumber | MOBILEPHONE | id.email | ..." ]
} |
Associated method :
The result of a search
| Name | Type | Cardinality | Description |
|---|
| resultCode | ResultCode | [0..1] | Search result status code. |
| resultElements | ResultElement | [0..*] | Search result elements. |
[+] : JSON Example{
"resultCode": "OK | NOK | FINISH | TIMEOUT",
"resultElements": [ {
"directorySource": "string",
"contacts": [ {
"id": {
"loginName": "string",
"instantMessagingId": "string",
"email": "string",
"phoneNumber": "string"
},
"firstName": "string",
"lastName": "string",
"vcardPath": "string",
"photo": "string",
"fullName": "string",
"attribute1": "string",
"attribute2": "string",
"attribute3": "string",
"attribute4": "string",
"attribute5": "string",
"mobilePhone": "string",
"otNode": "string"
} ]
} ]
} |
Associated method :
'string' represents character strings.
Routing management
Presentation
There are two ways to use the routing:
Routing profile:
It is a specific routing profile which can be created, updated and deleted by the user.
Each user can have several profiles but only one can be activated at a time.
In each profile the user can pre-define his presentation route, his forward route or overflow route.
The management of them can be done through
[PUT /routing/profiles] or
[PUT /routing/profiles/{profileId}] resources.
The routing profile is enabled for incoming call as long as no Custom routing is activated.
Custom routing:
When a user wants to make simple forward or overflow, a custom routing state is created automatically and
all his routing profiles are disabled.
The management of this custom routing can be done through
[POST /routing] or
[POST /routing/overflowroute] resources.
When this custom routing is deleted, the previous activated routing profile is re-activated automatically.
Terminologies:
Presentation Route: List of destinations on which incoming calls will be presented (if they are selected by the user and if the system finds them as being acceptable).
Forward Route: One destination is ringing at a time. When destination is a user, the routing management of this user is applied.
For STANDARD user, the forward can be immediate or conditional. For MULTIMEDIA user, the forward is only immediate.
Overflow Route: One destination is ringing at a time, with busy or no answer condition. It does not apply in case of active Forward Route.
Destination: It identifies where the calls are routed. It may be one of:
- A user/device (MULTIMEDIA or STANDARD since OpenTouch 2.1)
- An external number
- The voicemail
Route: Set of destinations. It may be one of:
- Presentation
- Forward
- Overflow
Routing state: Set of routes applied to the calls for a user.
Routing profile: Set of routes stored, in order to change quickly the routing state.
Personal routing profile: Routing profile defined by the end-user, also called custom profile.
Routes management:
| Route |
Destination |
Parameter |
MULTIMEDIA user |
STANDARD user |
| Presentation |
OFFICE |
|
X |
X |
| |
PC |
|
X |
X |
| |
TABLET |
|
X |
|
| |
MOBILE |
|
X |
X |
| |
VIDEO |
|
X |
|
| |
HOME |
|
X |
X |
| |
OTHER |
|
X |
X |
| Forward |
VOICEMAIL |
|
X |
X |
| |
USER |
|
X |
X |
| |
NUMBER |
|
|
X |
| |
|
Forward type |
|
X |
| Overflow |
VOICEMAIL |
|
X |
X |
| |
USER |
|
X |
|
| |
OTHER |
|
X |
|
| |
UNKNOWN |
|
X |
|
| |
ASSOCIATE |
|
|
X |
| |
|
Overflow type |
X |
X |
Destination type:
| OFFICE |
Deskphone device.
Used in presentation routes. |
| MOBILE |
Mobile device.
Used in presentation routes.
Note : For a STANDARD user, MOBILE destination is associated to a Remote Extension device.
|
| HOME |
Home destination handles predefined "Home" external phone number.
Used in presentation routes.
Note : Link with the user's nomadic right.
|
| OTHER |
Other destination permits to handle dynamically external phone number or device number (excluding own user devices and voicemail phoneNumber).
Used in presentation and overflow routes.
Note : Concerning presentation route, for a STANDARD user, OTHER number is only an external destination.
Note : Concerning overflow route, for a STANDARD user, this case is not authorized.
Note : Concerning presentation route, for a MULTIMEDIA user, OTHER number is only a device number.
Note : Concerning overflow route, for a MULTIMEDIA user, OTHER number is only a device number.
Note : Link with the user's nomadic right.
|
| PC |
Softphone device.
Used in presentation routes. |
| TABLET |
IPAD device.
Used in presentation routes. |
| VIDEO |
Video destination handles third party video device.
Used in presentation routes. |
| USER |
User destination handles exclusively USER phone number (MULTIMEDIA or STANDARD).
Used in forward and overflow routes. |
| VOICEMAIL |
Used in forward and overflow routes. |
| UNKNOWN |
Converted internally in VOICEMAIL, OTHER or USER destination depending on the target.
Used in overflow routes. |
| NUMBER |
Number destination permits to set the forward destination of a STANDARD user (internal and external numbers are authorized).
Used in forward routes.
(Since version 2.1). |
| ASSOCIATE |
Associate destination permits to update the associate of a STANDARD user.
Used in overflow routes.
(Since version 2.1). |
Resources summary
Notifications summary
Resources
/routing
Methods
Allows an application to know what the user is allowed to do.
Licenses
The license TELEPHONY_ADVANCED is 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 | Capabilities | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Examples
[+] : Get the routing capabilities of a user.
request :GET https://server/api/rest/1.0/routing
response :Content-Type: application/json
{
"presentationRoute": true,
"forwardRoute": true,
"overflowRoute": true],
"currentDevice": true,
"manageProfile": true,
"applyProfileRoutes": true,
"maxProfiles": 1
} Sets the specified routes
and the currentDeviceId
.
Licenses
The license TELEPHONY_ADVANCED is 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 | 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
[+] : Make an immediate forward to my voicemail.
All routing profiles are automatically disabled.
(The forwardType is an optional condition to forward route for STANDARD users. If this parameter is not provided, forward is unconditional: i.e immediate.)
request :POST https://server/api/rest/1.0/routing
Content-Type: application/json
{
"forwardRoutes": [
{
"destinations": [
{
"type": "VOICEMAIL",
"selected": true
}
]
}
]
}response :204 No Content
[+] : Make a conditional forward (BUSY) to my voicemail for a STANDARD user.
All routing profiles are automatically disabled.
request :POST https://server/api/rest/1.0/routing
Content-Type: application/json
{
"forwardRoutes": [
{
"forwardType": "BUSY",
"destinations": [
{
"type": "VOICEMAIL",
"selected": true
}
]
}
]
}response :204 No Content
[+] : Make an immediate forward for a MULTIMEDIA user to an OpenTouch user (external numbers are not authorized).
request :POST https://ot_server/api/rest/1.0/routing
Content-Type: application/json
{
"forwardRoutes": [
{
"destinations": [
{
"type": "USER",
"number":"32539",
"selected": true
}
]
}
]
}response :204 No Content
[+] : Make a conditional forward (BUSY) for a STANDARD user to an OpenTouch user (external numbers are not authorized).
request :POST https://ot_server/api/rest/1.0/routing
Content-Type: application/json
{
"forwardRoutes": [
{
"forwardType": "BUSY",
"destinations": [
{
"type": "USER",
"number":"32539",
"selected": true
}
]
}
]
}response :204 No Content
[+] : Make an immediate forward for a STANDARD user to an external number.
request :POST https://ot_server/api/rest/1.0/routing
Content-Type: application/json
{
"forwardRoutes": [
{
"destinations": [
{
"type": "NUMBER",
"number":"0298112233",
"selected": true
}
]
}
]
}response :204 No Content
[+] : Disable an immediate forward for a MULTIMEDIA user, in order to switch back to the previous routing state.
request :POST https://ot_server/api/rest/1.0/routing
Content-Type: application/json
{
"forwardRoutes": [
{
"destinations": [
{
"type": "OTHER",
"selected": false
}
]
}
]
}response :204 No Content
Associated notifications
/routing/overflowroute
Methods
Sets the specified overflow routes.
Licenses
The license TELEPHONY_ADVANCED is 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 | 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
[+] : If the user is busy, route the new calls to the voicemail.
request :POST https://server/api/rest/1.0/routing/overflowroute
Content-Type: application/json
{
"overflowRoutes": [ {
"overflowType":"BUSY",
"destinations": [ {
"type": "VOICEMAIL",
"selected": true
} ]
} ]
}response :204 No Content
Associated notifications
Cancels the overflow routes.
This method can be invoked in two different ways:
- By passing a body CancelOverflowRoutesRequest, containing
the requestId.
- By passing the requestId as a query parameter.
The choice depends on the client's REST library support for sending HTTP
DELETE with a body. If supported, both ways can be used. If not, sending
the requestId as a parameter is mandatory.
Licenses
The license TELEPHONY_ADVANCED is 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.
|
| requestId | string | the requestId as a query parameter. |
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 |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Examples
[+] : Cancels the overflow routes.
request :DELETE https://server/api/rest/1.0/routing/overflowroute
response :204 No Content
Associated notifications
/routing/profiles
Methods
Retrieves the list of existing routing profiles.
Licenses
The license TELEPHONY_ADVANCED is 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 | RoutingState | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Examples
[+] : Get all my profiles to know what profile is activated and what it contains
in term of presentation routes, forward routes.
request :GET https://server/api/rest/1.0/routing/profiles
response :200 OK
Content-Type: application/json
{
"profiles": [
{
"id": "0",
"name": "DEFAULT",
"defaultProfile": true,
"activable": true,
"removable": false,
"renameable": false,
"updatable": false,
"presentationRoutes": [
{
"destinations": [
{
"type": "OFFICE",
"deviceId": "32776",
"number": "32776",
"acceptable": true,
"selected": true
},
{
"type": "PC",
"deviceId": "32775",
"number": "32775",
"acceptable": true,
"selected": true
},
{
"type": "TABLET",
"deviceId": "32778",
"number": "32778",
"acceptable": true,
"selected": true
},
{
"type": "MOBILE",
"deviceId": "MOBILE_101451",
"number": "+33 (0) 620131473",
"acceptable": true,
"selected": true
},
{
"type": "VIDEO",
"acceptable": false,
"selected": true
},
{
"type": "HOME",
"deviceId": "NOMADIC_HOME_icm32535",
"number": "+33 (0) 298232537",
"acceptable": true,
"selected": false
},
{
"type": "OTHER",
"deviceId": "NOMADIC_icm32535",
"acceptable": true,
"selected": false
}
]
}
],
"forwardRoutes": [
{
"destinations": [
{
"type": "VOICEMAIL",
"acceptable": true,
"selected": false
},
{
"type": "USER",
"acceptable": true,
"selected": false
}
]
}
],
"currentDeviceId": "32776"
},
{
"id": "10",
"name": "PC",
"defaultProfile": false,
"activable": true,
"removable": true,
"renameable": true,
"updatable": true,
"presentationRoutes": [
{
"destinations": [
{
"type": "OFFICE",
"deviceId": "32776",
"number": "32776",
"acceptable": true,
"selected": false
},
{
"type": "PC",
"deviceId": "32775",
"number": "32775",
"acceptable": true,
"selected": true
},
{
"type": "TABLET",
"deviceId": "32778",
"number": "32778",
"acceptable": true,
"selected": false
},
{
"type": "MOBILE",
"deviceId": "MOBILE_101451",
"number": "+33 (0) 620131473",
"acceptable": true,
"selected": false
},
{
"type": "VIDEO",
"acceptable": false,
"selected": true
},
{
"type": "HOME",
"deviceId": "NOMADIC_HOME_icm32535",
"number": "+33 (0) 298232537",
"acceptable": true,
"selected": false
},
{
"type": "OTHER",
"deviceId": "NOMADIC_icm32535",
"acceptable": true,
"selected": false
}
]
}
],
"forwardRoutes": [
{
"destinations": [
{
"type": "VOICEMAIL",
"acceptable": true,
"selected": false
},
{
"type": "USER",
"acceptable": true,
"selected": false
}
]
}
],
"currentDeviceId": "32776"
}
]
} DEPRECATED: Subject to change: DO NOT USE
Deletes all non default routing profiles.
Licenses
The license TELEPHONY_ADVANCED is 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 | 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 |
Associated notifications
DEPRECATED: Subject to change: DO NOT USE
Creates a personal routing profile.
Licenses
The license TELEPHONY_ADVANCED is 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.
|
| details | boolean | If true, the created profile is included in the response. If
not set (or false), response only contain the Location header
pointing to the newly created profile. |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
| code | type | media types | description |
|---|
| 201 | string | application/json
| CREATED. The identifier of the profile
is returned. |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Associated notifications
/routing/profiles/{profileId}
Methods
Retrieves the specified routing profile.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| profileId | string | The identifier of the profile. |
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 | Profile | 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 |
DEPRECATED: Subject to change: DO NOT USE
Deletes non default specified routing profile.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| profileId | string | The identifier of the profile. |
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 | 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 |
Associated notifications
Activates the specified routing profile.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| profileId | string | The identifier of the profile. |
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 | 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 |
Associated notifications
DEPRECATED: Subject to change: DO NOT USE
Updates an existing routing profile.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| profileId | string | The identifier of the profile. |
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.
|
| details | boolean | If true, the modified profile is included in the response (200
OK). If not set (or false), returned response is 204 No
Content. |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
| code | type | media types | description |
|---|
| 200 | Profile | application/json
| OK |
| 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 |
Associated notifications
/routing/state
Methods
Retrieves the routing context state.
Licenses
The license TELEPHONY_ADVANCED is 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 | RoutingState | 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 |
Examples
[+] : Get the state of my routing, in term of presentation route, forward route and overflow route.
request :GET https://server/api/rest/1.0/routing/state
response :200 OK
Content-Type: application/json
{
"appliedProfile": {
"id": "0",
"name": "DEFAULT",
"defaultProfile": true
},
"activableProfiles": [
{
"id": "0",
"name": "DEFAULT",
"defaultProfile": true
},
{
"id": "10",
"name": "PC",
"defaultProfile": false
}
],
"presentationRoutes": [
{
"destinations": [
{
"type": "OFFICE",
"deviceId": "32776",
"number": "32776",
"acceptable": true,
"selected": true
},
{
"type": "PC",
"deviceId": "32775",
"number": "32775",
"acceptable": true,
"selected": true
},
{
"type": "TABLET",
"deviceId": "32778",
"number": "32778",
"acceptable": true,
"selected": true
},
{
"type": "MOBILE",
"deviceId": "MOBILE_101451",
"number": "+33 (0) 620131473",
"acceptable": true,
"selected": true
},
{
"type": "VIDEO",
"acceptable": false,
"selected": true
},
{
"type": "HOME",
"deviceId": "NOMADIC_HOME_icm32535",
"number": "+33 (0) 298232537",
"acceptable": true,
"selected": false
},
{
"type": "OTHER",
"deviceId": "NOMADIC_icm32535",
"acceptable": true,
"selected": false
}
]
}
],
"forwardRoutes": [
{
"destinations": [
{
"type": "VOICEMAIL",
"acceptable": true,
"selected": false
},
{
"type": "USER",
"acceptable": true,
"selected": false
}
]
}
],
"overflowRoutes": [
{
"overflowType": "BUSY_NO_ANSWER",
"destinations": [
{
"type": "OTHER",
"number": "123456789",
"acceptable": true,
"selected": false
},
{
"type": "VOICEMAIL",
"acceptable": true,
"selected": false
},
{
"type": "USER",
"acceptable": true,
"selected": false
}
]
}
],
"currentDeviceId": "32776"
} [+] : Get the state of my routing, in term of presentation route, forward route and overflow route.
request :GET https://server/api/rest/1.0/routing/state
response :200 OK
Content-Type: application/json
{
"activableProfiles": [
{
"id": "0",
"name": "DEFAULT",
"defaultProfile": true
},
{
"id": "10",
"name": "PC",
"defaultProfile": false
}
],
"presentationRoutes": [
{
"destinations": [
{
"type": "OFFICE",
"deviceId": "32776",
"number": "32776",
"acceptable": true,
"selected": true
},
{
"type": "PC",
"deviceId": "32775",
"number": "32775",
"acceptable": true,
"selected": true
},
{
"type": "TABLET",
"deviceId": "32778",
"number": "32778",
"acceptable": true,
"selected": true
},
{
"type": "MOBILE",
"deviceId": "MOBILE_101451",
"number": "+33 (0) 620131473",
"acceptable": true,
"selected": true
},
{
"type": "VIDEO",
"acceptable": false,
"selected": true
},
{
"type": "HOME",
"deviceId": "NOMADIC_HOME_icm32535",
"number": "+33 (0) 298232537",
"acceptable": true,
"selected": false
},
{
"type": "OTHER",
"deviceId": "NOMADIC_icm32535",
"acceptable": true,
"selected": false
}
]
}
],
"forwardRoutes": [
{
"destinations": [
{
"type": "VOICEMAIL",
"acceptable": true,
"selected": true
},
{
"type": "USER",
"acceptable": true,
"selected": false
}
]
}
],
"overflowRoutes": [
{
"overflowType": "BUSY_NO_ANSWER",
"destinations": [
{
"type": "OTHER",
"number": "123456789",
"acceptable": true,
"selected": false
},
{
"type": "VOICEMAIL",
"acceptable": true,
"selected": false
},
{
"type": "USER",
"acceptable": true,
"selected": false
}
]
}
],
"currentDeviceId": "32776"
} Representations
ApplyProfileRoutesRequestRequest to apply a routing profile.
| Name | Type | Cardinality | Description |
|---|
| requestId | string | [0..1] |
Request identifier provided by the client in order to correlate this request with the events.
If the client doesn't need to correlate this request with the events, this field can be omitted.
This string is created by the client and the client is in charge to produce the correct string
in order to response to its own constraints like uniqueness (login, time, counter, ... can be used).
A dedicated prefix must be also used like 'MyIC', 'Tablet', 'SipDeskphone', ... in order to not produce the
same identifier than the other clients.
|
| otherNumber | string | [0..1] | Since version 2.1 For "OTHER" and "OTHER_AND_MOBILE" profiles only. |
Associated method :
'boolean' is a data type, having two values (true and false).
CapabilitiesDescribes the routing management capabilities.
| Name | Type | Cardinality | Description |
|---|
| presentationRoute | boolean | [0..1] | If true, the user is allowed to manage presentation routes. |
| forwardRoute | boolean | [0..1] | If true, the user is allowed to manage forward routes. |
| overflowRoute | boolean | [0..1] | If true, the user is allowed to manage overflow routes. |
| currentDevice | boolean | [0..1] | If true, the user is allowed to manage the device used for outbound actions. |
| manageProfile | boolean | [0..1] | If true, the user is allowed to manage a profile (create, delete, update, rename). |
| applyProfileRoutes | boolean | [0..1] | If true, the user is allowed to apply a profile. |
| maxProfiles | int | [0..1] | Number of profiles: predefined and personal. |
Associated method :
Request to create a new routing profile.
| Name | Type | Cardinality | Description |
|---|
| profileName | string | [1] | The name of the profile to be created.
Only personal profiles can be renamed (name must be unique). |
| presentationRoutes | PresentationRoute | [0..*] |
List of presentation routes (only one presentation route can be set).
When this parameter is not provided, the default presentation routes of the DEFAULT
profile are 'selected' (all business devices).
|
| forwardRoutes | ForwardRoute | [0..*] |
List of forward routes (only one forward route can be set).
When this parameter is not provided, the forward routes are 'unselected'.
|
| currentDeviceId | string | [0..1] | Specifies which device the user uses for outbound actions (such as making a call).
When this parameter is not provided, the chosen currentDeviceId is taken from the first acceptable destination. |
[+] : JSON Example{
"profileName": "string",
"presentationRoutes": [ {
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"forwardRoutes": [ {
"forwardType": "BUSY | NO_ANSWER | BUSY_NO_ANSWER",
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"currentDeviceId": "string"
} |
Associated method :
Describes a destination.
| Name | Type | Cardinality | Description |
|---|
| type | DestinationType | [1] | Key used to identify the device or other destinations. |
| deviceId | string | [0..1] | Filled by the system in routing state. |
| number | string | [0..1] | Defines the phone number of an external device.
NOTE: the number must be filled if the destination type is OTHER.
Otherwise, it will be set up by the server. |
| acceptable | boolean | [0..1] | Filled by the system.
The value true indicate that selecting or unselecting is possible.
The value false indicate that route is not declared (admin) or no associated right. |
| selected | boolean | [0..1] | Filled by the system for predefined profiles (false by default).
Filled by the client : acceptable should be true.
|
| information | UserInformation | [0..1] | Description of the user if destination type is USER.
It can also be filled if destination type is OTHER and
number match the phone number of an user. |
[+] : JSON Example{
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} |
Lists the different types of a destination.
| Value | Description |
|---|
| OFFICE | Destination is office device. |
| MOBILE | Destination is mobile device. |
| PC | Destination is Personal Computer device. |
| TABLET | Destination is tablet device. |
| VIDEO | Destination is video device. |
| HOME | Destination is home device. |
| OTHER | Destination is other. |
| VOICEMAIL | Destination is the voice mail of the user. |
| USER | Destination is an user. |
| ASSISTANT | Since version 2.1 Destination is an assistant. |
| ASSOCIATE | Since version 2.1 Destination is an associate.
Only for a standard user.
Used in overflow routes. |
| NUMBER | Since version 2.1 Destination is a number.
Only for a standard user.
Used in forward routes. |
| UNKNOWN | Unknown destination type. |
Describes a forward route.
The possible destination type for a forward route are:
| Name | Type | Cardinality | Description |
|---|
| forwardType | ForwardType | [0..1] | Since version 2.1 Optional condition to forward route for STANDARD users.
If this parameter is not provided forward is unconditional: i.e immediate.
(Note : for a MULTIMEDIA user, only immediate forward is allowed). |
| destinations | Destination | [0..*] | List of destinations where calls can be forwarded:
- Calls can not be forked to several
acceptable forward routes.
- MyIC Desktop is not able to 'dial from' one of these destinations.
NOTE: this type of route can be specified in a profile.
|
[+] : JSON Example{
"forwardType": "BUSY | NO_ANSWER | BUSY_NO_ANSWER",
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} |
Lists the different types of forward.
The forwardType is an optional condition to forward route for STANDARD users.
If this parameter is not provided, forward is unconditional: i.e IMMEDIATE.
| Value | Description |
|---|
| BUSY | Incoming calls are diverted to the destination when the phone is busy. |
| NO_ANSWER | Incoming calls are diverted to the destination after a ringing duration. |
| BUSY_NO_ANSWER | Incoming calls are diverted to the destination when the phone is busy or after a ringing duration. |
'int' is a 32-bit number (-2147483648 to 2147483647).
OnRoutingManagementFailedThis notification indicates that a routing request has failed.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnRoutingManagementFailed' |
| loginName | string | [1] | Login name of the user (identifier which can be used for filtering). |
| requestId | string | [0..1] | Request identifier : used to correlate this event with a previous request. |
| resultCode | ResultCode | [0..1] | Error code. |
| cause | string | [0..1] | Can be used in order to localize the error, this cause can be :
- UNAUTHORIZED_OT_USER
- UNAUTHORIZED_NOT_AN_OT_USER
- UNAUTHORIZED_NOT_A_USER
- ...
|
| destinationType | DestinationType | [0..1] | Destination type that produce the error. |
| comment | string | [0..1] | Comment (in 'English'). |
[+] : JSON Example{
"eventName": "string",
"loginName": "string",
"requestId": "string",
"resultCode": "SUCCESS | ERROR_BAD_FRAMEWORK_SESSION_IDENTIFIER | ERROR_INVALID_OPERATION | ...",
"cause": "string",
"destinationType": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"comment": "string"
} |
This notification indicate that a profile (or a set of profiles) is updated.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnRoutingProfilesChanged' |
| loginName | string | [1] | Login name of the user (identifier which can be used for filtering). |
| profiles | Profile | [1..*] | All existing profiles. |
[+] : JSON Example{
"eventName": "string",
"loginName": "string",
"profiles": [ {
"id": "string",
"name": "string",
"defaultProfile": boolean,
"activable": boolean,
"removable": boolean,
"renameable": boolean,
"updatable": boolean,
"presentationRoutes": [ {
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"forwardRoutes": [ {
"forwardType": "BUSY | NO_ANSWER | BUSY_NO_ANSWER",
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"currentDeviceId": "string"
} ]
} |
Associated methods :
This notification indicate that routing state is changed.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnRoutingStateChanged' |
| loginName | string | [1] | Login name of the user (identifier which can be used for filtering). |
| requestId | string | [0..1] | Request identifier : used to correlate this event with a previous request. |
| routingState | RoutingState | [1] | Current routing state. |
[+] : JSON Example{
"eventName": "string",
"loginName": "string",
"requestId": "string",
"routingState": {
"appliedProfile": {
"id": "string",
"name": "string",
"defaultProfile": boolean
},
"activableProfiles": [ {
"id": "string",
"name": "string",
"defaultProfile": boolean
} ],
"presentationRoutes": [ {
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"forwardRoutes": [ {
"forwardType": "BUSY | NO_ANSWER | BUSY_NO_ANSWER",
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"overflowRoutes": [ {
"overflowType": "BUSY | NO_ANSWER | BUSY_NO_ANSWER",
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"currentDeviceId": "string"
}
} |
Associated methods :
Describes an overflow route.
The possible destination type for an overflow route are:
- OTHER
- VOICEMAIL
- USER
- UNKNOWN
- ASSOCIATE
NOTE:
- If UNKNOWN is selected, it will be changed to either OTHER, VOICEMAIL or USER
depending on the value set in number attribute.
| Name | Type | Cardinality | Description |
|---|
| overflowType | OverflowType | [1] | The overflow type. |
| destinations | Destination | [1..*] | List of destinations where calls can be forwarded.
Calls can not be forked to several acceptable overflow routes.
NOTE: this type of route can not be specified in a profile. |
[+] : JSON Example{
"overflowType": "BUSY | NO_ANSWER | BUSY_NO_ANSWER",
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} |
Lists the different types of overflow
| Value | Description |
|---|
| BUSY | Incoming calls are diverted to the destination when the phone is busy. |
| NO_ANSWER | Incoming calls are diverted to the destination after a ringing duration. |
| BUSY_NO_ANSWER | Incoming calls are diverted to the destination when the phone is busy or after a ringing duration. |
Describes a presentation route.
The possible destination type for a presentation route are:
- OFFICE
- MOBILE
- PC
- TABLET
- VIDEO
- HOME
- OTHER
| Name | Type | Cardinality | Description |
|---|
| destinations | Destination | [1..*] | List of destinations where calls can be presented simultaneously:
- Calls can be forked to several
acceptable presentation routes.
- MyIC Desktop is able to 'dial from' one of these destinations.
NOTE: this type of route can be specified in a profile.
|
[+] : JSON Example{
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} |
Describes a routing profile.
| Name | Type | Cardinality | Description |
|---|
| id | string | [1] | Identifies the profile (predefined profiles : DEFAULT, with id = '0'). |
| name | string | [0..1] | The application can use this attribute to display the profile.
This field is empty on predefined profiles.
NOTE: translations are not managed by OT server. |
| defaultProfile | boolean | [0..1] | This parameter is true for fall back profile. |
| activable | boolean | [0..1] | Define whether the profile can be activated.
NOTE: always true for DEFAULT profile. |
| removable | boolean | [0..1] | Specifies whether the profile can be removed (always false for default profile). |
| renameable | boolean | [0..1] | Specifies whether the profile can be renamed (always false for default profile). |
| updatable | boolean | [0..1] | Specifies whether the profile can be modified.
NOTE: this filed is always false for the default profile. |
| presentationRoutes | PresentationRoute | [1..*] | List of presentation (default) routes. |
| forwardRoutes | ForwardRoute | [0..*] | Unconditional forward routes to VOICEMAIL or USER. |
| currentDeviceId | string | [0..1] | Specifies which device the user uses for outbound actions (such as making a call). |
[+] : JSON Example{
"id": "string",
"name": "string",
"defaultProfile": boolean,
"activable": boolean,
"removable": boolean,
"renameable": boolean,
"updatable": boolean,
"presentationRoutes": [ {
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"forwardRoutes": [ {
"forwardType": "BUSY | NO_ANSWER | BUSY_NO_ANSWER",
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"currentDeviceId": "string"
} |
Associated methods :
Container for profiles
| Name | Type | Cardinality | Description |
|---|
| profiles | Profile | [0..*] | List of profiles. |
[+] : JSON Example{
"profiles": [ {
"id": "string",
"name": "string",
"defaultProfile": boolean,
"activable": boolean,
"removable": boolean,
"renameable": boolean,
"updatable": boolean,
"presentationRoutes": [ {
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"forwardRoutes": [ {
"forwardType": "BUSY | NO_ANSWER | BUSY_NO_ANSWER",
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"currentDeviceId": "string"
} ]
} |
Associated method :
Describes a routing profile summary.
| Name | Type | Cardinality | Description |
|---|
| id | string | [1] | Identifies the profile.
The id of the default profile is '0'. |
| name | string | [0..1] | The application can use this attribute to display the profile.
The name of the default profile is 'DEFAULT'. |
| defaultProfile | boolean | [0..1] | This parameter is true for default profile. |
Result code returned by every operation invoked on a service.
| Value | Description |
|---|
| SUCCESS | The operation succeeded. |
| ERROR_BAD_FRAMEWORK_SESSION_IDENTIFIER | The operation failed because the given session identifier is not valid. |
| ERROR_INVALID_OPERATION | The invoked operation is not valid. |
| ERROR_LICENSE_REQUIRED | A license is required to invoke this operation. |
| ERROR_SERVICE_UNAVAILABLE | An internal service, needed to answer the operation, is not available. |
| ERROR_BAD_PARAMETER_VALUE | A parameter given in the operation is not valid or is missing. |
| ERROR_UNAUTHORIZED | The user is not authorized to invoke this operation. |
| ERROR_SERVICE | An internal service raised an error. |
| ERROR_UNEXPECTED | An unexpected error has been raised. |
| ERROR_INCOMPLETE_PHONE_NUMBER | The phone number is incomplete. |
| ERROR_MAX_PROFILE_REACHED | The maximum of profiles has been reached. |
| ERROR_UNKNOWN_PHONE_NUMBER | The phone number is unknown. |
| ERROR_UNKNOWN_PROFILE | The profile is unknown. |
Describes the routing state.
| Name | Type | Cardinality | Description |
|---|
| appliedProfile | ProfileSummary | [0..1] | Since version 2.1 |
| activableProfiles | ProfileSummary | [1..*] | Since version 2.1 The application should use this list to propose the profile selection to the user.
NOTE: there is at least one activable profile (DEFAULT). |
| presentationRoutes | PresentationRoute | [1..*] | List of presentation routes. |
| forwardRoutes | ForwardRoute | [0..*] | List of forward routes. |
| overflowRoutes | OverflowRoute | [0..*] | List of overflow routes. |
| currentDeviceId | string | [0..1] | Since version 2.1 Device used for outbound actions (such as making a call). |
[+] : JSON Example{
"appliedProfile": {
"id": "string",
"name": "string",
"defaultProfile": boolean
},
"activableProfiles": [ {
"id": "string",
"name": "string",
"defaultProfile": boolean
} ],
"presentationRoutes": [ {
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"forwardRoutes": [ {
"forwardType": "BUSY | NO_ANSWER | BUSY_NO_ANSWER",
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"overflowRoutes": [ {
"overflowType": "BUSY | NO_ANSWER | BUSY_NO_ANSWER",
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"currentDeviceId": "string"
} |
Associated methods :
Request to set the overflow routes.
| Name | Type | Cardinality | Description |
|---|
| overflowRoutes | OverflowRoute | [1..*] | New overflow routes (only one overflow route can be set). |
| requestId | string | [0..1] | Since version 2.1 |
[+] : JSON Example{
"overflowRoutes": [ {
"overflowType": "BUSY | NO_ANSWER | BUSY_NO_ANSWER",
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"requestId": "string"
} |
Associated method :
Request to set a profile.
| Name | Type | Cardinality | Description |
|---|
| profileName | string | [1] | The name of the profile.
Only personal profiles can be renamed (name must be unique).
|
| presentationRoutes | PresentationRoute | [0..*] |
List of presentation routes (only one presentation route can be set).
When this parameter is not provided, the default presentation routes of the DEFAULT
profile are 'selected' (all business devices).
|
| forwardRoutes | ForwardRoute | [0..*] |
List of forward routes (only one forward route can be set).
When this parameter is not provided, the forward routes are 'unselected'.
|
| currentDeviceId | string | [0..1] | Specifies which device the user uses for outbound actions (such as making a call).
When this parameter is not provided, the chosen currentDeviceId is taken from the first acceptable destination. |
[+] : JSON Example{
"profileName": "string",
"presentationRoutes": [ {
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"forwardRoutes": [ {
"forwardType": "BUSY | NO_ANSWER | BUSY_NO_ANSWER",
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"currentDeviceId": "string"
} |
Associated method :
Request to select current routes for the user.
| Name | Type | Cardinality | Description |
|---|
| presentationRoutes | PresentationRoute | [0..*] |
List of presentation routes (only one presentation route can be set).
When this parameter is not provided, the default presentation routes of the DEFAULT
profile are 'selected' (all business devices).
|
| forwardRoutes | ForwardRoute | [0..*] |
Calls are prior forwarded to the selected destinations (only one forward route can be set).
When this parameter is not provided, the forward routes are 'unselected'.
|
| currentDeviceId | string | [0..1] | Since version 2.1 |
| requestId | string | [0..1] | Since version 2.1 |
[+] : JSON Example{
"presentationRoutes": [ {
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"forwardRoutes": [ {
"forwardType": "BUSY | NO_ANSWER | BUSY_NO_ANSWER",
"destinations": [ {
"type": "OFFICE | MOBILE | PC | TABLET | VIDEO | HOME | OTHER | VOICEMAIL | USER | ...",
"deviceId": "string",
"number": "string",
"acceptable": boolean,
"selected": boolean,
"information": {
"phoneNumber": "string",
"loginName": "string",
"lastName": "string",
"firstName": "string",
"email": "string"
}
} ]
} ],
"currentDeviceId": "string",
"requestId": "string"
} |
Associated method :
'string' represents character strings.
UserInformationDescribes information about an user.
| Name | Type | Cardinality | Description |
|---|
| phoneNumber | string | [0..1] | User phone number. |
| loginName | string | [0..1] | User login name. |
| lastName | string | [0..1] | User last name. |
| firstName | string | [0..1] | User first name. |
| email | string | [0..1] | User email. |
Communication log
History
Since version 2.0.1
Resources summary
Notifications summary
| Notification | Description |
|---|
| OnComRecordCreated | Notification sent when a new comlog entry has been created. |
| OnComRecordModified | Notification sent when one or more records have been modified. |
| OnComRecordsAck | Notification sent when one or more unanswered comlog records have been acknowledged. |
| OnComRecordsDeleted | Notification sent when one or more call log records have been destroyed. |
| OnComRecordsUnAck | Notification sent when one or more unanswered comlog records have been unacknowledged. |
Resources
/comlog/records
Methods
Either Acknowledge/Unacknowledge the incoming missed communication records specified by their IDs.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters| parameter | type | description |
|---|
| acknowledge | string | true to acknowledge the list of communication records, false to unacknowledge. |
| 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 | 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 |
Associated notifications
Get all the communication log records.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters| parameter | type | description |
|---|
| recordIdList | string | This parameter is optional. If provided none of the other parameters (except loginName) are taken into account.
This is a comma separated string of IDs of the communication log records to retrieve.
The returned data will contain the requested records and the totalCount information. |
| unanswered | boolean | This parameter is optional.
This is a search criterion, when set to true the operation returns only the records for missed calls.
When omitted this operation returns all the records (answered or not) which match the other criteria. |
| unacknowledged | boolean | This is a search criterion, when set to true the operation returns only the records unacknowledged.
If false this operation returns all the records (acknowledged or not) which match the other criteria. |
| withAttachment | string | This parameter is optional.
This is a search criterion, when set to true the operation returns only the records with attachment.
When omitted this operation returns all the records (with or without attachment) which match the other criteria. |
| afterDate | string | This parameter is optional.
The string is an UTC datetime whose format is yyyy-MM-ddTHH:mm:ss.SSSZ (example: 2013-05-16T18:17:14.489Z).
This is a search criterion, when used the operation returns the records not older than this date.
When omitted the operation searches for matching records starting from the oldest. |
| beforeDate | string | This parameter is optional.
The string is an UTC datetime whose format is yyyy-MM-ddTHH:mm:ss.SSSZ (example: 2013-05-16T18:17:15.489Z).
This is a search criterion, when used the operation returns the records older than this date.
When omitted the operation searches for matching records until the newest. |
| role | Role | This parameter is optional.
This is a search criterion, the enum value can be "CALLER", "CALLEE", "CONFLEADER" or CONFPARTICIPANT". It defines the role of the user in the communication.
When omitted this operation returns all the records which match the other criteria. |
| comRef | string | This parameter is optional.
The comref of the com we want to retrieve. |
| remotePartyId | string | This parameter is optional.
Ask to apply the operation on the records in which the user is engaged with this remote party. |
| offset | int | This parameter is optional.
The offset of the first record to return.
This parameter, together with "limit" allows to get the communication log "page by page" for application needs.
Default value is 0. |
| limit | int | This parameter is optional.
Defines the maximum number of records this operation returns.
Default value is 0 (in this case, we assume that the application wants to load the full communication log). |
| optimized | boolean | Since version 2.1.1 This parameter is optional.
When set to true the operation returns the full identity of a participant only the first time it occurs, when the same participant appears in several records
When omitted this operation returns the records with no optimization. |
| 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 | ComHistoryRecords | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Examples
[+] : Get all unanswered communication log records.
request :GET https://server/api/rest/1.0/comlog/records?unanswered=false&offset=0&limit=100
response :200 OK
Content-Type: application/json
{
"comHistoryRecords": [
{
"recordId": 10000,
"comref": "009JP4J3J4987CLKVAC1JB5AES000001",
"acknowledge": false,
"archived": false,
"participants": [
{
"role": "CALLER",
"answered": true,
"identity": {
"id": {
"loginName": "icm32535",
"phoneNumber": "32535",
"instantMessagingId": "icm32535@vm-ot20-pol.bstlabrd.fr.alcatel-lucent.com"
},
"firstName": "F32535",
"lastName": "L32535_250",
"type": {
"main": "USER",
"subType": ""
}
},
"anonymous": false,
"initialCalled": {
"id": {
"loginName": "icm32536",
"phoneNumber": "32536",
"instantMessagingId": "icm32536@vm-ot20-pol.bstlabrd.fr.alcatel-lucent.com"
},
"firstName": "Assistant",
"lastName": "L32536_250",
"type": {
"main": "USER",
"subType": ""
}
},
"reason": "UNKNOWN"
},
{
"identity": {
"id": {
"loginName": "icm32536",
"phoneNumber": "32536",
"instantMessagingId": "icm32536@vm-ot20-pol.bstlabrd.fr.alcatel-lucent.com"
},
"firstName": "Assistant",
"lastName": "L32536_250",
"type": {
"main": "USER",
"subType": ""
}
},
"anonymous": false,
"reason": "UNKNOWN"
}
],
"beginDate": "2013-11-13T11:33:45.000Z",
"endDate": "2013-11-13T11:34:38.000Z",
"medias": [
"AUDIO"
],
"attachments": [],
"extensions": []
},
{
"recordId": 9988,
"comref": "006BVDH0TK97L5CNVAC1JB5AES00001K",
"acknowledge": false,
"archived": false,
"participants": [
{
"role": "CALLEE",
"answered": true,
"identity": {
"id": {
"loginName": "icm32535",
"phoneNumber": "32535",
"instantMessagingId": "icm32535@vm-ot20-pol.bstlabrd.fr.alcatel-lucent.com"
},
"firstName": "F32535",
"lastName": "L32535_250",
"type": {
"main": "USER",
"subType": ""
}
},
"anonymous": false,
"reason": "UNKNOWN"
},
{
"identity": {
"id": {
"loginName": "icm32545",
"phoneNumber": "32545",
"instantMessagingId": "icm32545@vm-ot20-pol.bstlabrd.fr.alcatel-lucent.com"
},
"firstName": "F32545",
"lastName": "L32545",
"type": {
"main": "USER",
"subType": ""
}
},
"anonymous": false,
"reason": "UNKNOWN"
}
],
"beginDate": "2013-11-07T17:15:09.000Z",
"endDate": "2013-11-07T17:15:41.000Z",
"medias": [
"AUDIO"
],
"attachments": [],
"extensions": []
}
],
"offset": 0,
"limit": 100,
"totalCount": 2
} Delete all (or only the specified) communication log records.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters| parameter | type | description |
|---|
| recordIdList | string | This parameter is optional. If provided none of the other parameters (except loginName) are taken into account.
This is a comma separated string of IDs of the communication log records to delete.
If the IDs are unknown, no error message will be raised. In such case, of course, the OnComRecordDeleted event won't be generated. |
| unanswered | string | This parameter is optional.
This is a search criterion, when set to true the operation deletes only the records for missed calls.
When omitted this operation deletes all the records (answered or not) which match the other criteria. |
| unacknowledged | string | This is a search criterion, when set to true the operation returns only the records unacknowledged.
If false this operation returns all the records (unacknowledged or not) which match the other criteria. |
| withAttachment | string | This parameter is optional.
This is a search criterion, when set to true the operation deletes only the records with attachment.
When omitted this operation deletes all the records (with or without attachment) which match the other criteria. |
| afterDate | string | This parameter is optional.
The string is an UTC datetime whose format is yyyy-MM-ddTHH:mm:ss.SSSZ (example: 2013-05-16T18:17:15.489Z).
This is a search criterion, when used the operation deletes the records not older than this date.
When omitted the operation deletes matching records starting from the oldest. |
| beforeDate | string | This parameter is optional.
The string is an UTC datetime whose format is yyyy-MM-ddTHH:mm:ss.SSSZ (example: 2013-05-16T18:17:15.489Z).
This is a search criterion, when used the operation deletes the records older than this date.
When omitted the operation deletes matching records until the newest. |
| role | string | This parameter is optional.
This is a search criterion, the enum value can be "CALLER", "CALLEE", "CONFLEADER" or CONFPARTICIPANT". It defines the role of the user in the communication.
When omitted this operation deletes all the records which match the other criteria. |
| comRef | string | This parameter is optional.
The comref of the com we want to delete. |
| remotePartyId | string | This parameter is optional.
Ask to apply the operation on the records in which the user is engaged with this remote party. |
| 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 | 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 |
Associated notifications
/comlog/records/recordIds
Methods
Get the whole list of communication log record Ids.
Licenses
The license TELEPHONY_ADVANCED is 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 | ComHistoryRecordIds | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
/comlog/records/{recordId}
Methods
Get a communication log record.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| recordId | string | Identifier of the record
|
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 | ComHistoryRecord | 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 |
Delete a record.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| recordId | string | Identifier of the record
|
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 | 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 |
Associated notifications
/comlog/records/{recordId}/im
Methods
Get the IM thread associated to the comLog record.
History
Since version 2.3
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| recordId | string | Identifier of the record
|
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 | ImHistoryRecord | 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 |
Representations
AttachmentAn attachment is either a voice record corresponding to a voice mail
or a conversation record or a conferencing block reference,
which allows to retrieve conference through VCS API
| Name | Type | Cardinality | Description |
|---|
| type | AttachmentType | [1] | Type of attachment which is restricted to a voice record
or a conferencing VCS reference. |
| description | string | [0..1] | Describes the content of the attachment. |
| value | string | [1] | URI or reference of the attachment. |
[+] : JSON Example{
"type": "VOICEMAIL | AUDIOREC | CONFREF",
"description": "string",
"value": "string"
} |
Type of attachment linked with the record.
| Value | Description |
|---|
| VOICEMAIL | Type of attachment is a voice record |
| AUDIOREC | Type of attachment is a audio online record or a voice record |
| CONFREF | Type of attachment is a conferencing |
'boolean' is a data type, having two values (true and false).
ComHistoryRecordCommunication history ticket (ComLog).
| Name | Type | Cardinality | Description |
|---|
| recordId | long | [0..1] | unique identifier of the record. |
| comRef | string | [1] | Communication reference identifier. |
| acknowledged | boolean | [0..1] | False indicates that the ticket corresponds to a non answered incoming call that has not been later acknowledged. |
| participants | Participant | [0..*] | List of participants involved in the communication.
The list may be null for a scheduled conference that has not yet started. |
| beginDate | dateTime | [0..1] | Begin date of the communication (when the call is launched). |
| endDate | dateTime | [0..1] | End date of the conversation (when the call is terminated or canceled). |
| medias | MediaType | [1..*] | The list of medias involved in the communication. |
| attachments | Attachment | [0..*] | The list of documents or media resources attached to the communication. |
| extensions | TagValuePair | [0..*] | For evolution of this element, can contain supplementary information (tag/value pair). |
[+] : JSON Example{
"recordId": long,
"comRef": "string",
"acknowledged": boolean,
"participants": [ {
"role": "CALLER | CALLEE | CONFLEADER | CONFPARTICIPANT | UNKNOWN",
"answered": boolean,
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"anonymous": boolean,
"initialCalled": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"reason": "ALL_TRUNK_BUSY | INVALID_NUMBER | ABANDONED | BUSY | CONFERENCED | PICKUP | ...",
"pilot": "string"
} ],
"beginDate": "dateTime",
"endDate": "dateTime",
"medias": [ "AUDIO | VIDEO | IM | SHARING | RECORD | WHITEBOARD | DOCUMENT | POLL | UNKNOWN" ],
"attachments": [ {
"type": "VOICEMAIL | AUDIOREC | CONFREF",
"description": "string",
"value": "string"
} ],
"extensions": [ {
"name": "string",
"value": "string"
} ]
} |
Associated method :
Container for the list of history record ids (ComLog).
| Name | Type | Cardinality | Description |
|---|
| recordIds | long | [0..*] | The list the IDs of the com log records. |
[+] : JSON Example{
"recordIds": [ long ]
} |
Associated method :
List of ComHistoryRecord (ComLog).
| Name | Type | Cardinality | Description |
|---|
| comHistoryRecords | ComHistoryRecord | [0..*] | List of ComHistoryRecord. |
| offset | int | [0..1] | The offset of the first record which is returned. |
| limit | int | [0..1] | Defines the maximum number of records returned. |
| totalCount | int | [0..1] | Defines the total number of records without pagination. |
[+] : JSON Example{
"comHistoryRecords": [ {
"recordId": long,
"comRef": "string",
"acknowledged": boolean,
"participants": [ {
"role": "CALLER | CALLEE | CONFLEADER | CONFPARTICIPANT | UNKNOWN",
"answered": boolean,
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"anonymous": boolean,
"initialCalled": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"reason": "ALL_TRUNK_BUSY | INVALID_NUMBER | ABANDONED | BUSY | CONFERENCED | PICKUP | ...",
"pilot": "string"
} ],
"beginDate": "dateTime",
"endDate": "dateTime",
"medias": [ "AUDIO | VIDEO | IM | SHARING | RECORD | WHITEBOARD | DOCUMENT | POLL | UNKNOWN" ],
"attachments": [ {
"type": "VOICEMAIL | AUDIOREC | CONFREF",
"description": "string",
"value": "string"
} ],
"extensions": [ {
"name": "string",
"value": "string"
} ]
} ],
"offset": int,
"limit": int,
"totalCount": int
} |
Associated method :
'dateTime' is an UTC datetime whose format (ISO 8601 compatible) is yyyy-MM-ddTHH:mm:ss.SSSZ (example: 2013-05-16T18:17:15.489Z).
IdentifierKey information to help retrieving a participant (ComLog).
| Name | Type | Cardinality | Description |
|---|
| loginName | string | [0..1] | Login name. |
| phoneNumber | string | [0..1] | Company phone number. |
| instantMessagingId | string | [0..1] | Instant messaging identity. |
| companyEmail | string | [0..1] | Company email. |
ImHistoryRecord = List of ImMessage.
| Name | Type | Cardinality | Description |
|---|
| id | string | [0..1] | The id of the IM thread record. |
| title | string | [0..1] | The title of the IM thread record. |
| imMessages | ImMessage | [0..*] | List of ImMessage. |
Associated method :
An IM message is defined by its sender identifier, a date and the message content
| Name | Type | Cardinality | Description |
|---|
| sender | string | [0..1] | The sender of the message. |
| content | string | [0..1] | Describes the content of the message. |
| date | dateTime | [0..1] | date of the message (when the message is sent). |
'int' is a 32-bit number (-2147483648 to 2147483647).
long'long' is a 64-bit number (-9223372036854775808 to 9223372036854775807).
MainTypeMain 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. |
A media can be:
| Value | Description |
|---|
| AUDIO | The media is an audio. |
| VIDEO | The media is a video. |
| IM | The media is an instant messaging. |
| SHARING | The media is a data sharing. |
| RECORD | The media is a record. |
| WHITEBOARD | The media is a white board. |
| DOCUMENT | The media is a document. |
| POLL | The media is a poll. |
| UNKNOWN | The media is unknown. |
'nonNegativeInteger' is all positive integer numbers and zero. Negative integers are excluded.
OnComRecordCreatedNotification sent when a new comlog entry has been created.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnComRecordCreated' |
| loginName | string | [1] | Login name of the user (identifier which can be used for filtering). |
| record | ComHistoryRecord | [1] | Contains all the fields of a call log record. |
| missedCallsNb | nonNegativeInteger | [1] | Since version 2.3.1 Number of missed calls (non acknowledged unanswered incoming calls). |
[+] : JSON Example{
"eventName": "string",
"loginName": "string",
"record": {
"recordId": long,
"comRef": "string",
"acknowledged": boolean,
"participants": [ {
"role": "CALLER | CALLEE | CONFLEADER | CONFPARTICIPANT | UNKNOWN",
"answered": boolean,
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"anonymous": boolean,
"initialCalled": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"reason": "ALL_TRUNK_BUSY | INVALID_NUMBER | ABANDONED | BUSY | CONFERENCED | PICKUP | ...",
"pilot": "string"
} ],
"beginDate": "dateTime",
"endDate": "dateTime",
"medias": [ "AUDIO | VIDEO | IM | SHARING | RECORD | WHITEBOARD | DOCUMENT | POLL | UNKNOWN" ],
"attachments": [ {
"type": "VOICEMAIL | AUDIOREC | CONFREF",
"description": "string",
"value": "string"
} ],
"extensions": [ {
"name": "string",
"value": "string"
} ]
},
"missedCallsNb": nonNegativeInteger
} |
Notification sent when one or more records have been modified.
Modification, could be trigerred by:
- a change of state (e.g. from unanswered to answered)
- a change of media list (e.g. IM and call in a conference).
- a change of end date (e.g. when participants are dropped from a conference)
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnComRecordModified' |
| loginName | string | [1] | Login name of the user (identifier which can be used for filtering). |
| record | ComHistoryRecord | [1] | Contains all or part of the modified fields of a modified com log record.(example: acknowledged). |
[+] : JSON Example{
"eventName": "string",
"loginName": "string",
"record": {
"recordId": long,
"comRef": "string",
"acknowledged": boolean,
"participants": [ {
"role": "CALLER | CALLEE | CONFLEADER | CONFPARTICIPANT | UNKNOWN",
"answered": boolean,
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"anonymous": boolean,
"initialCalled": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"reason": "ALL_TRUNK_BUSY | INVALID_NUMBER | ABANDONED | BUSY | CONFERENCED | PICKUP | ...",
"pilot": "string"
} ],
"beginDate": "dateTime",
"endDate": "dateTime",
"medias": [ "AUDIO | VIDEO | IM | SHARING | RECORD | WHITEBOARD | DOCUMENT | POLL | UNKNOWN" ],
"attachments": [ {
"type": "VOICEMAIL | AUDIOREC | CONFREF",
"description": "string",
"value": "string"
} ],
"extensions": [ {
"name": "string",
"value": "string"
} ]
}
} |
Notification sent when one or more unanswered comlog records have been acknowledged.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnComRecordsAck' |
| loginName | string | [1] | Login name of the user (identifier which can be used for filtering). |
| recordIds | long | [0..*] | A list of IDs of records which have been acknowledged. |
Associated method :
Notification sent when one or more call log records have been destroyed.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnComRecordsDeleted' |
| loginName | string | [1] | Login name of the user (identifier which can be used for filtering). |
| recordIds | long | [0..*] | A list of IDs of records which have been destroyed
Remark : if element is not present it means that all user's records have been destroyed. |
Associated methods :
Notification sent when one or more unanswered comlog records have been unacknowledged.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnComRecordsUnAck' |
| loginName | string | [1] | Login name of the user (identifier which can be used for filtering). |
| recordIds | long | [0..*] | A list of IDs of records which have been acknowledged. |
Associated method :
Describes a participant referenced in the history record (ComLog).
Record content:
-
For a simple call (user A calls user B), the call record on each party will contain both the participant A and the participant B:
(no guaranty on the order of the participants on 2 successive responses)
- On A side, the record will contain :
- participant A (the owner of the record) with role=CALLER and the answered status (whether the call has been answered or not)
- participant B : neither the role nor the state is provided
- On B side, the record will contain :
- participant A : neither the role nor the state is provided
- participant B (the owner of the record) with role=CALLEE and the answered status (whether the call has been answered or not)
-
For a re-routed call (user A calls user B, the call is re-routed on user C, caused by overflow, redirection or pickup), the record
generated on each side including the user B side (the "victim" of the re-routing) will not contain as participant the user B itself
because he was not the last destination of the call:
- On A side, the record will contain :
- participant A : with role=CALLER, the answered status, initialCalled=B
- participant C
- On B side, the record will be similar to the C one and contain :
- participant A : neither the role nor the state is provided
- participant C with role=CALLEE, the answered status (whether the call has been answered or not) and initialCalled=B
which tells B that he was called by A but the call has been rerouted to C (with a reason) which answered or not to the call
- On C side, the record will contain :
- participant A : neither the role nor the state is provided
- participant C with role=CALLEE, the answered status (whether the call has been answered or not) and initialCalled=B
-
Furthermore, for a multi-parties call using addParticipant, the already connected users in the call will also received a call record which will contain
the answered status of the added participant: this information is provided to distinguish the added participants which have really answered and the other
which decline the call.
Identification of the participant:
- in the comlog notification events, the participant owner is identified only by its loginName (in order to reduce the event call flow),
the other participants are identified with their full identity (loginName, phoneNumber, email, instantMessagingId)
- in the getComlog response:
- if no optimization is asked, all the participants are identified with their full identity.
- if the "optimized:true" is present in the request parameter, only the first occurence of a participant (owner or other) are identified with their full identity.
the following occurences are identified only with the phonenumber if the participant has one, or by it IM id if not.
| Name | Type | Cardinality | Description |
|---|
| role | Role | [0..1] | Defines whether the participant was the/a caller party, a called party or a masterconf.
NB:in a conference, a participant can be both a called party and a caller
(consultation call plus conference following an incoming call). |
| answered | boolean | [0..1] | defines whether the participant has really entered in the conversation.
Can be omitted if the value is not known. |
| identity | PartyInfo | [1] | Full description of a party involved in an history record. |
| anonymous | boolean | [0..1] | Indicate if the participant identity is anonymous or not. |
| initialCalled | PartyInfo | [0..1] | The number that has been initially called when this participant has been entered in the call. |
| reason | Reason | [0..1] | The reason why the call has been established, rerouted, terminated ... |
| pilot | string | [0..1] | Since version 2.5 Pilot name if the call was distributed by a pilot |
[+] : JSON Example{
"role": "CALLER | CALLEE | CONFLEADER | CONFPARTICIPANT | UNKNOWN",
"answered": boolean,
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"anonymous": boolean,
"initialCalled": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
},
"reason": "ALL_TRUNK_BUSY | INVALID_NUMBER | ABANDONED | BUSY | CONFERENCED | PICKUP | ...",
"pilot": "string"
} |
Detail about a kind of participant (ComLog).
| 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 "manager", "assistant", "voicemail",... |
[+] : JSON Example{
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
} |
Full description of a party involved in an history record (ComLog).
| Name | Type | Cardinality | Description |
|---|
| id | Identifier | [1] | Key information to help retrieving a participant. |
| 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. |
| vcardUrl | string | [0..1] | Subject to change: DO NOT USE.
|
| type | ParticipantType | [0..1] | Participant's type. |
[+] : JSON Example{
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string",
"vcardUrl": "string",
"type": {
"main": "USER | DEVICE | SERVICE | EXTERNAL | UNKNOWN",
"subType": "string"
}
} |
indicates for what reason the communication has been released, established or rerouted.
The cause may be:
- ABANDONED The call was abandoned.
- ALL_TRUNK_BUSY The call was released because all trunk are busy.
- BUSY The call was released because the remote party is busy.
- FORWARDED The call has been forwarded PICKED_UP the call has been picked up.
- REDIRECTED The call has been redirected.
- TRANSFERRED The call has been transfered.
- VOICEMAILDEPOSIT the call has been forwarded on vmail.
- CONFERENCED The call was set to be a conference.
- ... other ...
| Value | Description |
|---|
| ALL_TRUNK_BUSY | The call was released because all trunk are busy. |
| INVALID_NUMBER | The call was refused because the dialed number is not valid. |
| ABANDONED | The call was canceled by the caller. |
| BUSY | The call failed because the called party is busy. |
| CONFERENCED | The call was set to be a conference. |
| PICKUP | The call was picked up. |
| FORWARDED | The call was forwarded to another destination. |
| REDIRECTED | The call was redirected to another destination. |
| RELEASED_ON_REDIRECT | The call was released since redirection to another destination fails. |
| TRANSFERRED | The call was transferred. |
| RELEASED_ON_TRANSFER | The call was released since transfer to another destination fails. |
| VOICEMAIL | The call ended on voicemail. |
| NORMAL | The call normally ended. |
| UNKNOWN | The reason is unknown. |
role of a participant in the communication.
| Value | Description |
|---|
| CALLER | The participant is a caller party. |
| CALLEE | The participant is a called party. |
| CONFLEADER | The participant is a leader of the conference. |
| CONFPARTICIPANT | The participant is a participant in a conference. |
| UNKNOWN | The role is unknown. |
'string' represents character strings.
TagValuePairKey / value structure.
| Name | Type | Cardinality | Description |
|---|
| name | string | [1] | Key |
| value | string | [1] | Value |
Request sent for updating communication history records (ComLog).
| Name | Type | Cardinality | Description |
|---|
| recordIds | long | [0..*] | The list the IDs of the com log records to update. |
[+] : JSON Example{
"recordIds": [ long ]
} |
Associated method :
Event summary
Resource summary
| Resource | Method | Description |
|---|
| /eventSummary | GET | Retrieves main counters of the user's event log. |
Notification summary
| Notification | Description |
|---|
| OnEventSummaryUpdated | Notification sent each time the user's counters have changed. |
Resource
/eventSummary
Methods
Retrieves main counters of the user's event log.
Licenses
The license TELEPHONY_ADVANCED is 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 | EventSummary | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Examples
[+] : Retrieves main counters of the user's event log.
request :GET https://server/api/rest/1.0/eventSummary
response :200 OK
Content-Type: application/json
{
"missedCallsNb":0,
"voiceMessagesNb":1,
"callBackRequestsNb":0,
"faxNb":0,
"eventWaiting":true
} Representations
boolean'boolean' is a data type, having two values (true and false).
EventSummaryDescribes an event summary.
| Name | Type | Cardinality | Description |
|---|
| missedCallsNb | nonNegativeInteger | [0..1] | Number of missed calls (non acknowledged unanswered incoming calls).
If this attribute is not specified, it means that the server is not able to provide that information :
do not consider it means that the user has 0 missed call but prefer not to display this information.
|
| voiceMessagesNb | nonNegativeInteger | [0..1] | Number of unread voice messages.
If this attribute is not specified, it means that the server is not able to provide that information :
do not consider it means that the user has 0 missed call but prefer not to display this information. |
| callBackRequestsNb | nonNegativeInteger | [0..1] | Number of call back requests.
If this attribute is not specified, it means that the server is not able to provide that information :
do not consider it means that the user has 0 missed call but prefer not to display this information. |
| faxNb | nonNegativeInteger | [0..1] | Number of fax.
If this attribute is not specified, it means that the server is not able to provide that information :
do not consider it means that the user has 0 missed call but prefer not to display this information. |
| eventWaiting | boolean | [0..1] | Specifies whether an event is waiting.
This flag can be used by an application to light a "LED" or to warn the user as it want that an event is waiting.
It is interesting to consider that the user could define rules on his profile defining when he wants his "LED"
to be lighted. Considering that, the application does not have to decide when to light the "LED" but only has to
follow this information.
If an application indicates to the user he has waiting events with additional events not provided here
(number of unread emails or IM for instance) :
- it would first have to take into account this flag (if true the "LED" has to be lighted)
- and then, if the flag is false, the application would be able to take into account those
additional events to know whether it wants to warn the user about waiting events.
|
| forResynchronization | boolean | [0..1] | The server sets the flag to true to indicate that some changes occur on the voice messages.
The device or the application should resynchronize the voice messages list by using
IcsMessaging (loadMessages and getMessages). |
Associated method :
'nonNegativeInteger' is all positive integer numbers and zero. Negative integers are excluded.
OnEventSummaryUpdatedNotification sent each time the user's counters have changed.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnEventSummaryUpdated' |
| loginName | string | [1] | Login name of the user (identifier which can be used for filtering). |
| eventSummary | EventSummary | [1] | The new event summary. |
'string' represents character strings.
Maintenance
Notification summary
| Notification | Description |
|---|
| OnChannelInformation | Notification sent for information to the user :error, info, keepalive. |
Representations
OnChannelInformationNotification sent for information to the user :error, info, keepalive.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnChannelInformation' |
| text | string | [0..1] | Details about the information sent. |
'string' represents character strings.
Instant Messaging
History
Since version 2.1.1
Resources summary
Notifications summary
Resources
/im/calls
Methods
List all the currently active IM sessions of the user.
Licenses
The license TELEPHONY_ADVANCED is 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 | IMSessions | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Create a new instant messaging session.
The reference of the newly session is provided in the 'Location' HTTP header of the response.
Note that this session is not yet known from the presence server, until an instant message is sent.
Licenses
The license TELEPHONY_ADVANCED is 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 | media types | description |
|---|
| 201 | application/json
| Created |
| 400 | application/json
| Bad Request |
| 403 | application/json
| Forbidden |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
/im/calls/{callRef}
Methods
Delete an instant messaging session.
Warning: Deleting an IM session will drop all participants in the given session.
To drop only yourself or a set of participants, see DELETE ..../participants
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | reference of the session. |
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 | 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 |
Associated notifications
/im/calls/{callRef}/participants
Methods
List all the participants of an IM session.
Licenses
The license TELEPHONY_ADVANCED is 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 | Participants | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Add a list of participants into an IM session.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | the reference of the IM session. |
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
|
body parameter| type | media types | description |
|---|
| ParticipantIds | | the container for the list of participants to add (list of instantMessagingIds). |
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 |
Associated notifications
Remove (drop) a list of participants from an IM session.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | the reference of the IM session. |
query parameters| parameter | type | description |
|---|
| partIds | string | list of comma separated participants Ids to remove (list of instantMessagingIds). |
| 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 | 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 |
Associated notifications
/im/calls/{callRef}/send
Methods
Send an instant message to a list of participants in a given IM session.
To be able to send / receive IM, the following steps should be performed:
- Subscribe to the 'instantMessaging' event package in order to receive instant messaging related events.
- Set the IM presence to 'online'.
- Create an IM session.
- Add participants to the session.
- Send the IM.
Recipients should then be notified by an 'OnImReceived' of the new message.
The recipients of this IM are the participants of the session. However, it is possible to filter these recipients
by specifying a list of instantMessagingIds who should receive the message.
This is also known as 'private message' feature.
Pay attention to the fact there is no guarantee of correct delivery of the message,
and no returned result of the operation (successful / unsuccessful).
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | reference of the session. |
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
|
body parameter| type | media types | description |
|---|
| IMMessage | | IMMessage the message info to send (message and optional list of recipients). |
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 |
Associated notifications
/im/calls/{callRef}/state
Methods
Set the user's state as 'typing a message'.
This could be used to indicate to recipients that the user is currently replying.
Recipients will received an OnImParticipantTyping event.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| callRef | string | the reference of the IM session. |
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
|
body parameter| type | media types | description |
|---|
| IMState | application/json
| the typing state, including a filter on recipients. |
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 |
Associated notifications
/im/deferred
Methods
Retrieve all the deferred messages stored on the server.
Licenses
The license TELEPHONY_ADVANCED is 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 | DeferredMessages | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Delete the deferred messages stored on the server.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters| parameter | type | description |
|---|
| msgIds | string | list of comma separated deferred messages to delete. |
| 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 | 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 |
Associated notifications
Update the status of the deferred messages stored on the server.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters| parameter | type | description |
|---|
| read | string | true to set the messages as read, false to set them as unread. |
| 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 | 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 |
Associated notifications
/im/deferred/counters
Methods
When user is offline, messages sent to him can not be delivered.
The server then store these 'deferred' messages, and when the user will connect,
he will be able to consult these messages.
This specific operation helps him to list how many read / unread messages are stored on the server.
Licenses
The license TELEPHONY_ADVANCED is 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 | DeferredMsgCounters | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Representations
boolean'boolean' is a data type, having two values (true and false).
dateTime'dateTime' is an UTC datetime whose format (ISO 8601 compatible) is yyyy-MM-ddTHH:mm:ss.SSSZ (example: 2013-05-16T18:17:15.489Z).
DeferredMessageDeferred message description.
| Name | Type | Cardinality | Description |
|---|
| messageId | string | [1] | Identifier of the message. |
| from | PartyInfo | [1] | Party info of the sender. |
| date | dateTime | [0..1] | Date and time of deposit of the message, in ISO8601 compatible format. |
| unread | boolean | [1] | Indicates If this message has been read or not. |
| message | string | [1] | Content of the message. |
[+] : JSON Example{
"messageId": "string",
"from": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"date": "dateTime",
"unread": boolean,
"message": "string"
} |
Container for a list of deferre messages.
| Name | Type | Cardinality | Description |
|---|
| messages | DeferredMessage | [0..*] | List of DeferredMessages. |
[+] : JSON Example{
"messages": [ {
"messageId": "string",
"from": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"date": "dateTime",
"unread": boolean,
"message": "string"
} ]
} |
Associated method :
Container for a list of deferred messages ids.
| Name | Type | Cardinality | Description |
|---|
| ids | string | [0..*] | List of DeferredMessagesIds. |
Associated method :
Description of deferred messages left on the server.
| Name | Type | Cardinality | Description |
|---|
| waiting | boolean | [1] | Indicates there are deferred messages left on the server (read or unread). |
| read | int | [1] | Number of deferred messages remaining on the server that have been marked as read (i.e. acknowledged). |
| unread | int | [1] | Number of deferred messages remaining on the server that have been marked as unread (i.e. unacknowledged). |
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. |
| instantMessagingId | string | [0..1] | Instant messaging identity. |
| companyEmail | string | [0..1] | Company email. |
Instant message descriptor.
| Name | Type | Cardinality | Description |
|---|
| recipients | string | [0..*] | List of recipients of the message (instantMessagingIds).
If not set, all the participants will receive the message.
Setting the recipients list to a subset of the participants
is the way to send a private message. |
| message | string | [1] | Content of the message to send. |
Associated method :
Describes an instant messaging session.
| Name | Type | Cardinality | Description |
|---|
| owner | PartyInfo | [1] | Party Info of the user who has created the session. |
| callRef | string | [1] | Reference of the IM session. |
| confName | string | [0..1] | If the IM session has been initiated as part of a scheduled conference,
this field indicates the name of the conference. |
| participants | Participant | [0..*] | List of Participants. |
[+] : JSON Example{
"owner": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"callRef": "string",
"confName": "string",
"participants": [ {
"participantId": "string",
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"leader": boolean,
"owner": boolean
} ]
} |
Container for list of IM sessions.
| Name | Type | Cardinality | Description |
|---|
| imSessions | IMSession | [0..*] | List of IM sessions. |
[+] : JSON Example{
"imSessions": [ {
"owner": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"callRef": "string",
"confName": "string",
"participants": [ {
"participantId": "string",
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"leader": boolean,
"owner": boolean
} ]
} ]
} |
Associated method :
State indication of an IM session.
| Name | Type | Cardinality | Description |
|---|
| imTypingState | boolean | [1] | Set the typing state of the user. |
| recipients | string | [0..*] | List of recipients of the typing state (instantMessagingIds).
If not set, all the participants will receive the state change. |
Associated method :
'int' is a 32-bit number (-2147483648 to 2147483647).
OnDeferredMessageCountersChangedEvent received indicating that an instant message has been left on the server.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnDeferredMessageCountersChanged' |
| loginName | string | [1] | Login of the user receiving the event. |
| waiting | boolean | [0..1] | Indicates if there is still some deferred messages on the server, whatever the state (read or unread). |
| read | int | [1] | Number of messages stored on the server that have been read. |
| unread | int | [1] | Number of messages stored on the server that have not been read. |
Associated methods :
Event sent when a participant is added in an IM session.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnImParticipantAdded' |
| loginName | string | [1] | Login name of the user receiving the event. |
| callRef | string | [1] | Reference of the IM session. |
| participant | PartyInfo | [1] | Added participant information. |
Associated method :
Event sent when a participant is dropped from an IM session.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnImParticipantDropped' |
| loginName | string | [1] | Login of the user receiving the event. |
| callRef | string | [1] | Reference of the IM session. |
| participantId | string | [1] | Dropped participantId. |
Associated methods :
Event sent when a participant has set its typing state (i.e. just starting typing).
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnImParticipantTyping' |
| loginName | string | [1] | Login of the user receiving the event. |
| callRef | string | [1] | Reference of the IM session. |
| participantId | string | [1] | Typing participantId. |
| imTypingState | boolean | [0..1] | True if the participant is typing. |
Associated method :
Event received containing the instant message.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnImReceived' |
| loginName | string | [1] | Login of the user receiving the event. |
| callRef | string | [1] | Reference of the IM session. |
| from | PartyInfo | [1] | Participant information of the sender. |
| to | string | [0..*] | List of participantId (i.e. recipients)of the message.
If not set, all participants of a session receive the message. |
| message | string | [1] | Received message. |
[+] : JSON Example{
"eventName": "string",
"loginName": "string",
"callRef": "string",
"from": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"to": [ "string" ],
"message": "string"
} |
Associated method :
Describes a participant referenced in instant messaging (IM).
| Name | Type | Cardinality | Description |
|---|
| participantId | string | [1] | Identifier of the participant. Equivalent to instantMessagingId. |
| identity | PartyInfo | [1] | Party info contains additional fields about the participant. |
| leader | boolean | [1] | Indicate if the given participant is leader in the referring IM session or not. |
| owner | boolean | [0..1] | Indicate if the participant is the creator of the IM session. |
Container for a list of participant Ids.
| Name | Type | Cardinality | Description |
|---|
| participantIds | string | [0..*] | Container for a list of participants. |
[+] : JSON Example{
"participantIds": [ "string" ]
} |
Associated method :
Container for a list of participants.
| Name | Type | Cardinality | Description |
|---|
| participants | Participant | [0..*] | Container for Participants. |
Associated method :
Full description of a party (i.e. participant's description).
| Name | Type | Cardinality | Description |
|---|
| id | Identifier | [1] | Key information to help retrieving a participant. |
| firstName | string | [0..1] | First name of the participant. |
| lastName | string | [0..1] | Last name of the participant. |
| displayName | string | [0..1] | Display name of the participant. |
'string' represents character strings.
Presence
Presentation
Management of all presence related resources.
Presence of a user is made of several categories (types).
These categories are:
- im: instant messaging presence - the ability to send / receive instant messaging (values: online, offline).
- basic: well known user presence state (values: busy, be-right-back, appear-offline, [blank], [custom]).
- phone: simple phone presence (value: on-the-phone, not-on-the-phone).
- note: short 'mood phrase'. A few words or a short sentence, or [blank] to clear it.
- calendar : calendar presence (value: in-a-meeting, free, not-available).
Please note that retrieving this presence is not supported for non favorites contacts.
To present the presence on a user interface, the client application can decide to aggregate some presence types in a simpler way,
or can strictly follow the categories defined here.
A user, or an administrator (see session management) can:
- Retrieve its presence for a given type or all of them in one go.
- Set its presence for a given type, if supported.
- Retrieve all types of presence for a list of contacts.
- Subscribe / unsubscribe to the presence of a list of contacts.
A contact is a user of the OpenTouch system, or a user from a federated server, who has some presence interaction capabilities,
allowing to communicate with him.
A favorite is special contact of a user who has been added to a dedicated list or group (not managed in this presence resource).
Users must be aware that presence could be filtered at different levels:
- At (distant) contact level: Could reject, filter or block any presence request.
- At local user level: System Administrator could have blocked the right to request other's presence.
- At distant domain level: Federated domain could have blocked presence request, or partially support it.
Please refer to your system administrator for any request regarding expected behavior of the system.
Receiving presence events is subject to a subscription to the presence event package (see subscription resource).
The OnUserPresenceUpdated event is sent after modification of one of the previously listed categories, from this API or from another device.
The OnContactPresenceUpdated event is sent after the presence one of a contact we have subscribed to (see POST /presence/contacts/subscribe
has changed, or when the presence of one of our favorite has changed (no need to subscribe to them).
History
Since version 2.1.1
Resources summary
Notifications summary
Resources
/presence/contacts
Methods
Retrieves contacts presences.
Contacts can be retrieved either by their instantMessagingId or their phone number.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters| parameter | type | description |
|---|
| imIds | string | comma separated list of instantMessagingIds. |
| phoneNumbers | string | comma separated list of company phone numbers. |
| details | boolean | If true, will return as much information as possible in the PartyInfo of the contacts.
false is the default value (short PartyInfo containing only the instantMessagingId field). |
| 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 | ContactsPresences | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
/presence/contacts/subscribe
Methods
Subscribe to a list of contacts for which we want to receive presence updates.
NOTE1: Subscription to presence of favorites is automatically done, without the need to perform it here.
NOTE2: Presence update notification could be filtered at different level (contact, administration).
No error message will be returned in such case.
Licenses
The license TELEPHONY_ADVANCED is 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
|
body parameter| type | media types | description |
|---|
| ContactsInfo | application/json
| container for the list of instantMessagingIds or phoneNumbers to subscribe to. |
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 |
Associated notifications
/presence/contacts/unsubscribe
Methods
Unsubscribe a list of contacts for which we no longer want to receive presences updates.
Licenses
The license TELEPHONY_ADVANCED is 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
|
body parameter| type | media types | description |
|---|
| ContactsInfo | application/json
| container for list of instantMessagingIds or phoneNumbers to unsubscribe from. |
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 |
/presence/user
Methods
Retrieves all the user presences types in a single operation.
Licenses
The license TELEPHONY_ADVANCED is 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 | Presences | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
/presence/user/basic
Methods
Retrieves the user's basic presence.
Possible values are:
- [blank] : will clear the previously set basic presence.
- 'busy' : user is present but does not want to be disturbed.
- 'be-right-back' : user indicates he is temporarily busy or away, but should be back soon.
- 'appear-offline' : user is seen as offline by others.
For some clients (devices) who aggregate all presences types into a single information, clearing the basic presence
will result in displaying the IM presence ('online').
Licenses
The license TELEPHONY_ADVANCED is 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 | Presence | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Set the user's basic presence.
See
GET /presence/user/basic for values.
Licenses
The license TELEPHONY_ADVANCED is 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
|
body parameter| type | media types | description |
|---|
| Presence | application/json
| Presence the presence type and value. |
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 |
Associated notifications
/presence/user/calendar
Methods
Retrieves the user's calendar presence.
Values are 'in-a-meeting', 'free', 'not-available'.
History
Since version 2.2
Licenses
The license TELEPHONY_ADVANCED is 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 | Presence | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Set the user's calendar presence.
See
GET /presence/user/calendar for values.
History
Since version 2.2
Licenses
The license TELEPHONY_ADVANCED is 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
|
body parameter| type | media types | description |
|---|
| Presence | application/json
| The calendar presence to set. |
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 |
Associated notifications
/presence/user/im
Methods
Retrieves the user's IM presence.
Values are 'online', 'offline'.
Licenses
The license TELEPHONY_ADVANCED is 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 | Presence | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
/presence/user/note
Methods
Retrieves the user's note presence.
This is also known as the mood phrase
Licenses
The license TELEPHONY_ADVANCED is 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 | Presence | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Set the user's note presence.
This information should fit in a few words, or a short sentence.
Licenses
The license TELEPHONY_ADVANCED is 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
|
body parameter| type | media types | description |
|---|
| Presence | application/json
| Presence the presence type and value. |
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 |
Associated notifications
/presence/user/phone
Methods
Retrieves the user's phone presence.
Values are 'on-the-phone', 'not-on-the-phone'.
Licenses
The license TELEPHONY_ADVANCED is 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 | Presence | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Representations
CalendarInfosCalendar presence supplementary information.
| Name | Type | Cardinality | Description |
|---|
| endDate | string | [0..1] | Date and time (ISO8601 format) of the end of the meeting.
Example: '2015-07-10T10:15:00Z' |
Container for a list of contacts identifiers.
A contact is mainly identified by its instantMessagingId,
but could also be by its phone number.
| Name | Type | Cardinality | Description |
|---|
| instantMessagingIds | string | [0..*] | List of contacts instantMessagingId. |
| phoneNumbers | string | [0..*] | List of contacts phoneNumber. |
[+] : JSON Example{
"instantMessagingIds": [ "string" ],
"phoneNumbers": [ "string" ]
} |
Associated methods :
Container for a list of presence..
| Name | Type | Cardinality | Description |
|---|
| contacts | Presences | [0..*] | The list of different contact presences. |
[+] : JSON Example{
"contacts": [ {
"party": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"presences": [ {
"type": "string",
"value": "string",
"calendarInfos": {
"endDate": "string"
}
} ]
} ]
} |
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. |
| instantMessagingId | string | [0..1] | Instant messaging identity. |
| companyEmail | string | [0..1] | Company email. |
Event received on contact's presence changed.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnContactPresenceUpdated' |
| loginName | string | [1] | Login of the user receiving the event. |
| party | PartyInfo | [1] | Identity details of the contact whose presence has changed.
NOTE: In this event, the party info will contain only the minimalistic information for the contact
(only its instantMessagingId). |
| presences | Presence | [1..*] | Presence types. |
[+] : JSON Example{
"eventName": "string",
"loginName": "string",
"party": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"presences": [ {
"type": "string",
"value": "string",
"calendarInfos": {
"endDate": "string"
}
} ]
} |
Associated methods :
Event received on user's presence changed.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnUserPresenceUpdated' |
| loginName | string | [1] | Login of the user receiving the event. |
| presences | Presence | [1..*] | Presence types. |
Associated methods :
Full description of a party (i.e. participant's description).
| Name | Type | Cardinality | Description |
|---|
| id | Identifier | [1] | Key information to help retrieving a participant. |
| firstName | string | [0..1] | First name of the participant. |
| lastName | string | [0..1] | Last name of the participant. |
| displayName | string | [0..1] | Display name of the participant. |
Presence descriptor.
| Name | Type | Cardinality | Description |
|---|
| type | string | [1] | The type / category of presence: im, phone, basic, calendar, ... |
| value | string | [1] | Value of the presence: online, busy, ... |
| calendarInfos | CalendarInfos | [0..1] | Since version 2.2 Only provided for calendar presence (type=calendar) and provides supplementary information about the calendar presence.
This info is only provided for contacts permanently associated to user (i.e favorites). |
Associated methods :
Container for a list of presence..
| Name | Type | Cardinality | Description |
|---|
| party | PartyInfo | [0..1] | The party. |
| presences | Presence | [0..*] | The list of different presences. |
[+] : JSON Example{
"party": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"presences": [ {
"type": "string",
"value": "string",
"calendarInfos": {
"endDate": "string"
}
} ]
} |
Associated method :
'string' represents character strings.
Messaging
Resources summary
Notifications summary
| Notification | Description |
|---|
| OnMessageAdded | Event sent when a new voice message has been stored in the user's mailbox. |
| OnMessageDeleted | Event sent when a voice message has been deleted from the user's mailbox. |
| OnMessageUpdated | Event sent when a voice message status has been updated. |
Resources
/messaging/mailboxes
Methods
Get all the user's mailboxes.
This is the mandatory first step to access all messaging / greetings features.
The id of the retrieved mailboxes is used as a key to go down resources hierarchy.
Depending on the mailbox type, some operations or notifications are not allowed or supported.
These capabilities information are provided for each mailbox.
NOTE: OpenTouch supports only one mailbox per user in 2.1 release.
Provision is taken to support several mailboxes in a future release.
Licenses
The license MESSAGING is 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 | MailBoxes | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
/messaging/mailboxes/{mailboxId}
Methods
Get a specific mailbox information.
A mailbox information contains counters about the concerned mailbox:
- Number of total voicemails.
- Number of new (unread) voicemails.
- Storage usage of the mailbox, if supported, as a percentage (100 = 100% full).
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| mailboxId | string | Identifier of the mailbox.
|
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 | MailBoxInfo | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
/messaging/mailboxes/{mailboxId}/player
Methods
Start or resume playing a voice message.
If no media session is already opened, a new one is automatically created, calling the given phone number
(or the default business number if not specified).
The voicemailId can be omitted is the media session is ready to resume a previously paused message.
The offset determines the position, in seconds, from where the message should be played.
Providing an offset different from 0 is only allowed when resuming a paused message.
In such case, the offset can take any value from 0 to the length of the message.
See PlayVoiceMessageRequest for the syntax of this field.
A OnMessageUpdated event will be sent if the voice message was previously unread.
NOTE: To check if this feature is supported by the mailbox, please use the GET /messaging/mailboxes resource to get mailbox capabilities (See MailBoxCapabilities).
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| mailboxId | string | Identifier of the mailbox.
|
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 | 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 |
Associated notifications
Terminate a player session with the media server.
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| mailboxId | string | Identifier of the mailbox.
|
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 | 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 |
/messaging/mailboxes/{mailboxId}/player/pause
Methods
Pause the current voice message being played.
NOTE: To check if this feature is supported by the mailbox, please use the GET /messaging/mailboxes resource to get mailbox capabilities (See MailBoxCapabilities).
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| mailboxId | string | Identifier of the mailbox.
|
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 | 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 |
/messaging/mailboxes/{mailboxId}/player/stop
Methods
Stop a currently playing on a message.
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| mailboxId | string | Identifier of the mailbox.
|
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 | 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 |
/messaging/mailboxes/{mailboxId}/recorder
Methods
Start or restart a record of a new voice message.
If no media session is already opened, a new one is automatically created, calling the given phone number
(or the default business number if not specified).
The record can be stopped by calling POST /messaging/mailboxes/{mailboxId}/recorder/stop resource.
NOTE: To check if this feature is supported by the mailbox, please use the GET /messaging/mailboxes resource to get mailbox capabilities (See MailBoxCapabilities).
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| mailboxId | string | Identifier of the mailbox.
|
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 | 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 |
Get the previously recorded message.
Cancel also removes the draft voice message from the mailbox.
NOTE: To check if this feature is supported by the mailbox, please use the GET /messaging/mailboxes resource to get mailbox capabilities (See MailBoxCapabilities).
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| mailboxId | string | Identifier of the mailbox.
|
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 | VoiceRecord | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Terminate a recorder session with the media server.
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| mailboxId | string | Identifier of the mailbox.
|
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 | 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 |
/messaging/mailboxes/{mailboxId}/recorder/cancel
Methods
Cancel a currently recording message, or the previously created message.
Cancel also removes the draft voice message from the mailbox.
NOTE: To check if this feature is supported by the mailbox, please use the GET /messaging/mailboxes resource to get mailbox capabilities (See MailBoxCapabilities).
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| mailboxId | string | Identifier of the mailbox.
|
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 | 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 |
/messaging/mailboxes/{mailboxId}/recorder/resume
Methods
Resume recording of a message.
The record has been previously stopped (stop).
NOTE: To check if this feature is supported by the mailbox, please use the GET /messaging/mailboxes resource to get mailbox capabilities (See MailBoxCapabilities).
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| mailboxId | string | Identifier of the mailbox.
|
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 | 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 |
/messaging/mailboxes/{mailboxId}/recorder/send
Methods
Send a recorded message to a list of recipients.
The list of recipients are identified by either their phone numbers, login names, instantMessagingIds or company emails.
The message is sent by resolving the recipient's phone number from the information contained in Identifier object.
NOTE1: Fields of Identifier object are scanned in the following order:
- phoneNumber,
- loginName,
- instantMessagingId,
- companyEmail
The first filled field which is valid will be used to resolve the recipient's phone number.
NOTE2: To check if this feature is supported by the mailbox, please use the GET /messaging/mailboxes resource to get mailbox capabilities (See MailBoxCapabilities).
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| mailboxId | string | Identifier of the mailbox.
|
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
|
body parameter| type | media types | description |
|---|
| SendMessageRequest | application/json
| descriptor containing the list of recipients and the url of the message. |
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 |
/messaging/mailboxes/{mailboxId}/recorder/stop
Methods
Stop currently recording on a message.
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| mailboxId | string | Identifier of the mailbox.
|
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 | 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 |
/messaging/mailboxes/{mailboxId}/voicemails
Methods
Retrieve all user's voicemails, or only those specified by the filter parameters
offset /
limit /
newOnly.
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| mailboxId | string | Identifier of the mailbox.
|
query parameters| parameter | type | description |
|---|
| offset | int | the offset from which to start retrieving the voicemail list (Default value is 0). |
| limit | int | the maximum number of items to return (Default value is -1: no limit). |
| newOnly | boolean | filter only unread voicemail if set to 'true' (Default value is 'false'). |
| 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 | Voicemails | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Delete specified voicemails.
If no message Ids are provided, all voice messages will be deleted.
NOTE1: OnMessageDeleted OnMessageDeleted event will be generated for each deleted message.
In case of unknown message ids, no error message will be sent.
In such case, of course, the OnMessageDeleted event won't be sent.
NOTE2: Developers must pay attention to the fact that some parts of the URL could need encoding,
when some characters known as reserved are present in some parts of the URL
(see RFC3986).
In the current context, this is particularly true with some type of voicemail boxes,
where voicemailId could contain a reserved '+' character (in msgIds query parameter).
In such case, the client application should encode the '+' as %2B .
NOTE3: To be able to delete all messages, a previous call to one of following resources must be done:
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| mailboxId | string | Identifier of the mailbox.
|
query parameters| parameter | type | description |
|---|
| msgIds | string | list of voice message Ids to delete (comma separated list of voicemailIds) |
| 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 | 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 |
Associated notifications
/messaging/mailboxes/{mailboxId}/voicemails/{voicemailId}
Methods
Delete the specified voicemail.
NOTE: If successfull, OnMessageDeleted OnMessageDeleted event will be generated for the deleted message.
In case of unknown message ids, no error message will be sent.
In such case, of course, the OnMessageDeleted event won't be sent.
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| voicemailId | string | Identifier of the message.
|
| mailboxId | string | Identifier of the mailbox.
|
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 | 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 |
Associated notifications
Retrieve a given user's voicemail, containing the full details (including the URL).
NOTE: Retrieving a specific voicemail with its full details (the URL) implies that the given
voicemail will be seen as read, and thus an event OnMessageUpdated OnMessageUpdated will be generated.
This behavior is subject to change in future releases.
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| mailboxId | string | Identifier of the mailbox.
|
| voicemailId | string | Identifier of the message.
|
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 | Voicemail | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Associated notifications
/messaging/mailboxes/{mailboxId}/voicemails/{voicemailId}/callback
Methods
Call back the sender of a voice message.
NOTE1: This request can be prohibited by the administrator (configuration depending of the voicemail profile for the user).
To check if this feature (forward) is supported by the mailbox, please use the GET /messaging/mailboxes
resource to get mailbox capabilities (See MailBoxCapabilities).
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| mailboxId | string | Identifier of the mailbox.
|
| voicemailId | string | Identifier of the message.
|
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
|
body parameter| type | media types | description |
|---|
| CallbackRequest | | call back information. |
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 |
/messaging/mailboxes/{mailboxId}/voicemails/{voicemailId}/forward
Methods
Forward an existing message with recording an introduction.
If no media session is already opened, a new one is automatically created, calling the given phone number
(or the default business number if not specified).
The introduction record can be stopped by calling POST /messaging/mailboxes/{mailboxId}/recorder/stop resource.
Then calling DELETE /messaging/mailboxes/{mailboxId}/recorder will terminate the introduction recording.
The message is then ready to be sent by calling POST /messaging/mailboxes/{mailboxId}/recorder/send to a recipient
with the newly attached introduction.
To check if this feature (forward) is supported by the mailbox, please use the GET /messaging/mailboxes
resource to get mailbox capabilities (See MailBoxCapabilities).
History
Since version 2.2.1
Licenses
The license MESSAGING is required.
Request
path parameters| parameter | type | description |
|---|
| mailboxId | string | Identifier of the mailbox.
|
| voicemailId | string | Identifier of the message.
|
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
|
body parameter| type | media types | description |
|---|
| ForwardRequest | | forward request information. |
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 |
Representations
boolean'boolean' is a data type, having two values (true and false).
CallbackRequestCallback Sender Message request data.
| Name | Type | Cardinality | Description |
|---|
| phoneNumber | string | [0..1] | Phone number to use for the callback, if different from the default one. |
Associated method :
'dateTime' is an UTC datetime whose format (ISO 8601 compatible) is yyyy-MM-ddTHH:mm:ss.SSSZ (example: 2013-05-16T18:17:15.489Z).
ForwardRequestForwardRequest Message request data.
| Name | Type | Cardinality | Description |
|---|
| phoneNumber | string | [0..1] | Phone number to use for the forward, if different from the default one. |
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. |
| instantMessagingId | string | [0..1] | Instant messaging identity. |
| companyEmail | string | [0..1] | Company email. |
'int' is a 32-bit number (-2147483648 to 2147483647).
MailBoxDescriptor of a mailbox.
| Name | Type | Cardinality | Description |
|---|
| id | string | [0..1] | Identifier of the mailbox. |
| name | string | [0..1] | Name of the mailbox. |
| capabilities | MailBoxCapabilities | [0..1] | Capabilities supported by the mailbox. |
[+] : JSON Example{
"id": "string",
"name": "string",
"capabilities": {
"listMessages": boolean,
"getMessages": boolean,
"getRecord": boolean,
"play": boolean,
"pause": boolean,
"hangup": boolean,
"record": boolean,
"resume": boolean,
"cancel": boolean,
"forward": boolean,
"callback": boolean,
"send": boolean,
"events": boolean
}
} |
List the capabilities supported by a mailbox.
| Name | Type | Cardinality | Description |
|---|
| listMessages | boolean | [0..1] | Voicemail server can return the list of messages. |
| getMessages | boolean | [0..1] | Voice messages can be downloaded. |
| getRecord | boolean | [0..1] | Recorded message can be downloaded. |
| play | boolean | [0..1] | Voicemail server is capable of playing voice messages. |
| pause | boolean | [0..1] | Playing voice message can be paused and resumes from the position it has been paused. |
| hangup | boolean | [0..1] | Media session can be terminate. |
| record | boolean | [0..1] | The voicemail server is capable of recording voice messages. |
| resume | boolean | [0..1] | Voice message recording can be resumed after being stopped. |
| cancel | boolean | [0..1] | The current recording can be cancelled. |
| forward | boolean | [0..1] | The voicemail server is capable of forwarding voice messages. |
| callback | boolean | [0..1] | The voicemail server can call back the originator of the voice message. |
| send | boolean | [0..1] | Voice message or record can be sent to recipients. |
| events | boolean | [0..1] | Voicemail server is capable to send events in case of message deposit / removal. |
[+] : JSON Example{
"listMessages": boolean,
"getMessages": boolean,
"getRecord": boolean,
"play": boolean,
"pause": boolean,
"hangup": boolean,
"record": boolean,
"resume": boolean,
"cancel": boolean,
"forward": boolean,
"callback": boolean,
"send": boolean,
"events": boolean
} |
Container for a list of Mailbox
| Name | Type | Cardinality | Description |
|---|
| mailboxes | MailBox | [0..*] | List of user mailboxes. |
[+] : JSON Example{
"mailboxes": [ {
"id": "string",
"name": "string",
"capabilities": {
"listMessages": boolean,
"getMessages": boolean,
"getRecord": boolean,
"play": boolean,
"pause": boolean,
"hangup": boolean,
"record": boolean,
"resume": boolean,
"cancel": boolean,
"forward": boolean,
"callback": boolean,
"send": boolean,
"events": boolean
}
} ]
} |
Associated method :
Descriptor of a MailboxInfo.
| Name | Type | Cardinality | Description |
|---|
| totalVoiceMsg | int | [0..1] | Number of voice messages. |
| newVoiceMsg | int | [0..1] | Number of new (unread) voice messages. |
| storageUsage | int | [0..1] | Threshold indicating mailbox usage ratio.
100 mean 100% full. No more message deposit is allowed.
-1 means information not available. |
[+] : JSON Example{
"totalVoiceMsg": int,
"newVoiceMsg": int,
"storageUsage": int
} |
Associated method :
'nonNegativeInteger' is all positive integer numbers and zero. Negative integers are excluded.
OnMessageAddedEvent sent when a new voice message has been stored in the user's mailbox.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnMessageAdded' |
| loginName | string | [1] | Login name of the user receiving the event. |
| mailboxId | string | [1] | Identifier of the user's mailbox for which the event was generated. |
| message | Voicemail | [1] | Newly added message in user's mailbox. |
| newVoiceMessagesNb | nonNegativeInteger | [1] | Since version 2.3.1 Number of unread voice messages. |
[+] : JSON Example{
"eventName": "string",
"loginName": "string",
"mailboxId": "string",
"message": {
"voicemailId": "string",
"from": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"duration": int,
"date": "dateTime",
"unread": boolean,
"highPriority": boolean,
"url": "string"
},
"newVoiceMessagesNb": nonNegativeInteger
} |
Event sent when a voice message has been deleted from the user's mailbox.
When several messages are deleted, this event is sent for every deleted voice messages.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnMessageDeleted' |
| loginName | string | [1] | Login name of the user receiving the event. |
| mailboxId | string | [1] | Identifier of the user's mailbox for which the event was generated. |
| messageId | string | [1] | Id of the deleted message. |
Associated methods :
Event sent when a voice message status has been updated.
The update mostly concern the read / unread status of the voice message.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnMessageUpdated' |
| loginName | string | [1] | Login name of the user receiving the event. |
| mailboxId | string | [1] | Identifier of the user's mailbox for which the event was generated. |
| message | Voicemail | [1] | Updated message in user's mailbox. |
[+] : JSON Example{
"eventName": "string",
"loginName": "string",
"mailboxId": "string",
"message": {
"voicemailId": "string",
"from": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"duration": int,
"date": "dateTime",
"unread": boolean,
"highPriority": boolean,
"url": "string"
}
} |
Associated methods :
Full description of a party (i.e. participant's description).
| Name | Type | Cardinality | Description |
|---|
| id | Identifier | [1] | Key information to help retrieving a participant. |
| firstName | string | [0..1] | First name of the participant. |
| lastName | string | [0..1] | Last name of the participant. |
| displayName | string | [0..1] | Display name of the participant. |
Play message Descriptor.
| Name | Type | Cardinality | Description |
|---|
| voicemailId | string | [0..1] | Identifier of the voicemail to play. |
| phoneNumber | string | [0..1] | Phone number on which to play the message. |
| offset | string | [0..1] | Offset of the message, in seconds, to start playing the message.
The format for the offset has the following syntax : [+|-]value[%].
Some examples of valid offset:
"65" Absolute offset of 65 seconds from the beginning. Range is 0 to
the duration of the voice message.
"12%" Absolute offset of 12 percent from the beginning. Range is 0
to 100%.
"+10" Relative offset of 10 seconds ahead of the current position.
The range depends on the current position and the duration of the voice
message.
"-20" Relative offset of 20 seconds before the current position
An offset different from 0 can not be applied the first time a message is played.
|
Associated method :
Callback sender request data.
| Name | Type | Cardinality | Description |
|---|
| phoneNumber | string | [0..1] | Phone number to use for the callback, if different from the default one. |
Associated method :
Descriptor of a voice message.
| Name | Type | Cardinality | Description |
|---|
| destinations | Identifier | [0..*] | List of the destinations (i.e. recipients) of the message.
NOTE: Fields of Identifier object are scanned in the following order:
- phoneNumber,
- loginName,
- instantMessagingId,
- companyEmail
The first filled field which is valid will be used to resolve the recipient's phone number. |
| highPriority | boolean | [0..1] | Normal (default=false) high (true).. |
| url | string | [0..1] | If specified, send the given url file instead of the newly recorded message. |
Associated method :
'string' represents character strings.
VoicemailDescriptor of a voice message.
| Name | Type | Cardinality | Description |
|---|
| voicemailId | string | [1] | Identifier of the voicemail. |
| from | PartyInfo | [0..1] | Originator of the voicemail. |
| duration | int | [1] | Duration, in seconds, of the voicemail. |
| date | dateTime | [1] | Date and time (ISO-8601) of the message. |
| unread | boolean | [1] | Indicates if this message has been read or not. |
| highPriority | boolean | [1] | Indicate if the message has been tagged as urgent or not. |
| url | string | [0..1] | Url of the voicemail. The url is valid as long as the server is running. If the server is restarted, user should get the messages with new url. |
[+] : JSON Example{
"voicemailId": "string",
"from": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"duration": int,
"date": "dateTime",
"unread": boolean,
"highPriority": boolean,
"url": "string"
} |
Associated method :
List of voicemails.
| Name | Type | Cardinality | Description |
|---|
| voicemails | Voicemail | [0..*] | List of voicemails. |
[+] : JSON Example{
"voicemails": [ {
"voicemailId": "string",
"from": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"duration": int,
"date": "dateTime",
"unread": boolean,
"highPriority": boolean,
"url": "string"
} ]
} |
Associated method :
Record message Descriptor.
| Name | Type | Cardinality | Description |
|---|
| url | string | [0..1] | The Url of the wav file of the newly recorded voice message. |
Associated method :
Groups
Presentation
The REST groups service covers the Supervision service and the Hunting Group service.
Supervision
- The supervision groups are managed by administrator.
- A member is inserted in a group with a role and right : supervised/supervisor/both.
- A user member of a group can choose its role depending on its right (logon/logoff).
- Furthermore, a user member of a group can use the FULL role in the changeRole request(without precisely knowing its rights), its final role will depend on its rights: SUPERVISOR and/or SUPERVISED.
| Member right |
Member role |
Meaning |
| SUPERVISOR |
None |
The user is not logged in the group |
| |
SUPERVISOR |
The user is logged as supervisor in the group |
| SUPERVISED |
None |
The user is not logged in the group |
| |
SUPERVISED |
The user is logged as supervised in the group |
| SUPERVISOR&SUPERVISED |
None |
The user is not logged in the group |
| |
SUPERVISOR |
The user is logged as supervisor in the group |
| |
SUPERVISED |
The user is logged as supervised in the group |
| |
SUPERVISOR&SUPERVISED |
The user is logged as supervisor and supervised in the group |
- A supervisor is notified with all the incoming calls on the members of its group which allows him to pick-up the call.
Hunting Group (HG)
- The HG groups are managed by administrator.
- A member is inserted in a HG group with a basic right : AGENT, which means it takes part in the call distribution
- A user member of a HG group can join(set role=AGENT) or leave, that means becomes or not active in the call distribution.
History
Since version 2.1.1
Resources summary
Notifications summary
| Notification | Description |
|---|
| OnGroupCreated | This notification indicates to a user that it is inserted in a new group. |
| OnGroupLoggedFailed | This notification indicates to a member of a group that the group logged request failed. |
| OnGroupModified | This notification indicates to a member of a group that this group has been modified:
members added, members removed or members changed (right or role). |
| OnGroupRemoved | This notification indicates that a user is removed from a group |
| OnSupervisedUpdated | This notification indicates to a supervisor user that some of its supervised users have changed. |
Resources
/groups
Methods
Get information on all the groups of the user.
Licenses
The license TELEPHONY_ADVANCED is 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 | Groups | 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 |
/groups/refresh
Methods
Ask to be refreshed by notification on all the calls which happened on the groups of the user.
Licenses
The license TELEPHONY_ADVANCED is 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 | media types | description |
|---|
| 204 | application/json
| No Content |
| 400 | application/json
| Bad Request |
| 401 | application/json
| Unauthorized |
| 403 | application/json
| Forbidden |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Associated notifications
/groups/{groupId}
Methods
Returns a description of one group.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| groupId | string | |
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 | Group | 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 |
/groups/{groupId}/changeRole
Methods
Change the role of member(s) of a group.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters| parameter | type | description |
|---|
| groupId | string | |
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 | 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
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. |
| participants | Participant | [0..*] | Participants. |
[+] : JSON Example{
"callRef": "string",
"callData": {
"initialCalled": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"anonymous": boolean
},
"participants": [ {
"participantId": "string",
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
}
} ]
} |
Detail about data associated to a call.
| Name | Type | Cardinality | Description |
|---|
| initialCalled | PartyInfo | [0..1] | Initial called identifier. |
| anonymous | boolean | [0..1] | If true it's a anonymous call. |
Request sent for changing the role of a list of members inside a group.
This request is used to login in a group with a role or to logoff from a group
| Name | Type | Cardinality | Description |
|---|
| newMemberRoles | NewMemberRole | [0..*] | The list of the members and their new role to update. |
[+] : JSON Example{
"newMemberRoles": [ {
"memberId": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"roles": [ "SUPERVISOR | SUPERVISED | AGENT | FULL" ]
} ]
} |
Associated method :
Describes an user's group.
| Name | Type | Cardinality | Description |
|---|
| identifier | string | [1] | Group unique identifier. |
| name | string | [0..1] | Group unique identifier. |
| props | GroupProps | [1] | Group properties. |
| members | GroupMember | [0..*] | Group members. |
[+] : JSON Example{
"identifier": "string",
"name": "string",
"props": {
"type": "SUPERVISION | HUNTING_GROUP",
"userManaged": boolean,
"mode": "REGULAR | COLLABORATION"
},
"members": [ {
"partyInfo": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"rights": [ "SUPERVISOR | SUPERVISED | MANAGER | ASSISTANT_MAIN | ASSISTANT_BACKUP | AGENT" ],
"roles": [ "SUPERVISOR | SUPERVISED | AGENT | FULL" ]
} ]
} |
Associated method :
Detail about a groupMember.
[+] : JSON Example{
"partyInfo": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"rights": [ "SUPERVISOR | SUPERVISED | MANAGER | ASSISTANT_MAIN | ASSISTANT_BACKUP | AGENT" ],
"roles": [ "SUPERVISOR | SUPERVISED | AGENT | FULL" ]
} |
Lists the different rights that can take a group member.
SUPERVISOR and SUPERVISED can be affected at the same time for a Supervision group member.
MANAGER, ASSISTANT_MAIN and ASSISTANT_BACKUP are specific for manager/assistant.
AGENT is specific to a Hunting Group member
| Value | Description |
|---|
| SUPERVISOR | The group member is a supervisor. |
| SUPERVISED | The group member is a supervised. |
| MANAGER | The group member is a manager. |
| ASSISTANT_MAIN | The group member is a main assistant. |
| ASSISTANT_BACKUP | The group member is a backup assistant. |
| AGENT | The group member is an agent in a Hunting group |
Lists the different roles that can take a group member, depending on its rights.
SUPERVISOR and SUPERVISED can be used together by a supervision group member.
FULL is a mode only usable on changeRole request, which allows a client to log into the group in default mode without knowing its real rights.
For a supervision group member
- an empty role means that the member is not logged in its group.
- FULL means logging with the whole rights: SUPERVISOR and/or SUPERVISED.
For a Hunting Group member:
- AGENT means that the user participates to the call distribution.
- FULL means AGENT.
| Value | Description |
|---|
| SUPERVISOR | The group member is logged as supervisor. |
| SUPERVISED | The group member is logged as supervised. |
| AGENT | Since version 2.4 Hunting Group: the HG member is active in the call distribution. |
| FULL | all types of group: default logging mode (only usable in changeMode request) |
Indicate the working mode of a Supervision group.
| Value | Description |
|---|
| REGULAR | In a regular group, supervised only users should only care about the supervisors. |
| COLLABORATION | In a collaboration group, supervised only users could care about all group members. |
Describes the properties of a group.
| Name | Type | Cardinality | Description |
|---|
| type | GroupType | [1] | Group type. |
| userManaged | boolean | [0..1] | Group manageable by user. Only for Supervision groups (always False) |
| mode | GroupMode | [0..1] | Group mode. For supervision group only ! |
[+] : JSON Example{
"type": "SUPERVISION | HUNTING_GROUP",
"userManaged": boolean,
"mode": "REGULAR | COLLABORATION"
} |
List of Group.
| Name | Type | Cardinality | Description |
|---|
| groups | Group | [0..*] | List of groups |
[+] : JSON Example{
"groups": [ {
"identifier": "string",
"name": "string",
"props": {
"type": "SUPERVISION | HUNTING_GROUP",
"userManaged": boolean,
"mode": "REGULAR | COLLABORATION"
},
"members": [ {
"partyInfo": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"rights": [ "SUPERVISOR | SUPERVISED | MANAGER | ASSISTANT_MAIN | ASSISTANT_BACKUP | AGENT" ],
"roles": [ "SUPERVISOR | SUPERVISED | AGENT | FULL" ]
} ]
} ]
} |
Associated method :
Lists the different types of group.
| Value | Description |
|---|
| SUPERVISION | Supervision group. |
| HUNTING_GROUP | Since version 2.4 Hunting group. |
Key information to help retrieving a participant.
| Name | Type | Cardinality | Description |
|---|
| loginName | string | [0..1] | Login name. |
| phoneNumber | string | [0..1] | Company phone number. |
| instantMessagingId | string | [0..1] | Instant messaging identity. |
| companyEmail | string | [0..1] | Company email. |
Contain the new role of a group member, used when the role of a member is changed.
| Name | Type | Cardinality | Description |
|---|
| memberId | Identifier | [1] | Group member unique identifier. Restriction: only the loginName is accepted |
| roles | GroupMemberRole | [0..*] | New Group member roles |
[+] : JSON Example{
"memberId": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"roles": [ "SUPERVISOR | SUPERVISED | AGENT | FULL" ]
} |
This notification indicates to a user that it is inserted in a new group.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnGroupCreated' |
| loginName | string | [1] | Login name of the user (identifier which can be used for filtering). |
| identifier | string | [1] | Unique identifier of the group. |
| name | string | [0..1] | name of the group. |
| props | GroupProps | [1] | Properties of the group. |
| members | GroupMember | [0..*] | Members of the group. |
[+] : JSON Example{
"eventName": "string",
"loginName": "string",
"identifier": "string",
"name": "string",
"props": {
"type": "SUPERVISION | HUNTING_GROUP",
"userManaged": boolean,
"mode": "REGULAR | COLLABORATION"
},
"members": [ {
"partyInfo": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"rights": [ "SUPERVISOR | SUPERVISED | MANAGER | ASSISTANT_MAIN | ASSISTANT_BACKUP | AGENT" ],
"roles": [ "SUPERVISOR | SUPERVISED | AGENT | FULL" ]
} ]
} |
This notification indicates to a member of a group that the group logged request failed.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnGroupLoggedFailed' |
| loginName | string | [1] | Login name of the user receiving the event. |
| identifier | string | [1] | Unique identifier of the group. |
| name | string | [0..1] | Name of the group. |
| props | GroupProps | [1] | Properties of the group. |
| deviceNumber | string | [1] | Device number. |
| causeId | string | [0..1] | Cause of failed request. |
| description | string | [0..1] | Description of failed request. |
[+] : JSON Example{
"eventName": "string",
"loginName": "string",
"identifier": "string",
"name": "string",
"props": {
"type": "SUPERVISION | HUNTING_GROUP",
"userManaged": boolean,
"mode": "REGULAR | COLLABORATION"
},
"deviceNumber": "string",
"causeId": "string",
"description": "string"
} |
Associated method :
This notification indicates to a member of a group that this group has been modified:
members added, members removed or members changed (right or role).
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnGroupModified' |
| loginName | string | [1] | Login name of the user (identifier which can be used for filtering). |
| identifier | string | [1] | Unique identifier of the group. |
| name | string | [0..1] | name of the group. |
| props | GroupProps | [1] | Properties of the group. |
| addedMembers | GroupMember | [0..*] | AddedMembers in the group. |
| modifiedMembers | GroupMember | [0..*] | ModifiedMembers in the group. |
| removedMembers | GroupMember | [0..*] | RemovedMembers from the group. |
[+] : JSON Example{
"eventName": "string",
"loginName": "string",
"identifier": "string",
"name": "string",
"props": {
"type": "SUPERVISION | HUNTING_GROUP",
"userManaged": boolean,
"mode": "REGULAR | COLLABORATION"
},
"addedMembers": [ {
"partyInfo": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"rights": [ "SUPERVISOR | SUPERVISED | MANAGER | ASSISTANT_MAIN | ASSISTANT_BACKUP | AGENT" ],
"roles": [ "SUPERVISOR | SUPERVISED | AGENT | FULL" ]
} ],
"modifiedMembers": [ {
"partyInfo": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"rights": [ "SUPERVISOR | SUPERVISED | MANAGER | ASSISTANT_MAIN | ASSISTANT_BACKUP | AGENT" ],
"roles": [ "SUPERVISOR | SUPERVISED | AGENT | FULL" ]
} ],
"removedMembers": [ {
"partyInfo": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"rights": [ "SUPERVISOR | SUPERVISED | MANAGER | ASSISTANT_MAIN | ASSISTANT_BACKUP | AGENT" ],
"roles": [ "SUPERVISOR | SUPERVISED | AGENT | FULL" ]
} ]
} |
This notification indicates that a user is removed from a group
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnGroupRemoved' |
| loginName | string | [1] | Login name of the user (identifier which can be used for filtering). |
| identifier | string | [1] | Unique identifier of the group. |
| props | GroupProps | [0..1] | Properties of the group. |
[+] : JSON Example{
"eventName": "string",
"loginName": "string",
"identifier": "string",
"props": {
"type": "SUPERVISION | HUNTING_GROUP",
"userManaged": boolean,
"mode": "REGULAR | COLLABORATION"
}
} |
This notification indicates to a supervisor user that some of its supervised users have changed.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnSupervisedUpdated' |
| loginName | string | [1] | Login name of the supervisor user (identifier which can be used for filtering). |
| supervisedUsers | SupdUser | [0..*] | supervised users list that have changed. |
[+] : JSON Example{
"eventName": "string",
"loginName": "string",
"supervisedUsers": [ {
"loginName": "string",
"phoneNumber": "string",
"telPresenceState": "FREE | RINGING_INCOMING | BUSY | BUSY_RINGING_INCOMING | UNKNOWN",
"calls": [ {
"callRef": "string",
"callData": {
"initialCalled": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"anonymous": boolean
},
"participants": [ {
"participantId": "string",
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
}
} ]
} ]
} ]
} |
Associated method :
Detail about a participant in a remote call
| Name | Type | Cardinality | Description |
|---|
| participantId | string | [1] | Participant identifer (Should not be displayed). |
| identity | PartyInfo | [0..1] | Participant identity card. |
Full description of a party (i.e. participant's description).
| Name | Type | Cardinality | Description |
|---|
| id | Identifier | [1] | Key information to help retrieving a participant. |
| firstName | string | [0..1] | First name of the participant. |
| lastName | string | [0..1] | Last name of the participant. |
| displayName | string | [0..1] | Display name of the participant. |
'string' represents character strings.
SupdUserDescribes a supervised.
| Name | Type | Cardinality | Description |
|---|
| loginName | string | [1] | loginName of the supervised user. |
| phoneNumber | string | [0..1] | phoneNumber of the supervised user. |
| telPresenceState | TelPresenceState | [1] | tel Presence state. |
| calls | Call | [0..*] | incoming calls. |
[+] : JSON Example{
"loginName": "string",
"phoneNumber": "string",
"telPresenceState": "FREE | RINGING_INCOMING | BUSY | BUSY_RINGING_INCOMING | UNKNOWN",
"calls": [ {
"callRef": "string",
"callData": {
"initialCalled": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"anonymous": boolean
},
"participants": [ {
"participantId": "string",
"identity": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
}
} ]
} ]
} |
Lists the telephonic presence state of group supervised member.
| Value | Description |
|---|
| FREE | The supervised is free. |
| RINGING_INCOMING | The supervised receives an incoming ringing call (or more). |
| BUSY | The supervised is engaged in one or several call. |
| BUSY_RINGING_INCOMING | The supervised receives an incoming ringing call (or more) while it is already busy with another call. |
| UNKNOWN | UNKNOWN state. |
Conference
Presentation
Conference Management API
This service offers the ability for the user to manage its conferences.
Following actions are available from this API:
- Retrieve all conferences owned by a user, as well as the invitations,either in classical JSON format or as an iCalendar file.
- Create a new conference, either from a classical JSON descriptor, or from an uploaded iCalendar file.
- Delete a programmed conference.
- Modify an existing conference. Depending on the state of the conference (started or not), some parameters may not be modifiable.
- Add or remove participants to an existing conference.
- Add or remove documents to an existing conference.
- Promote (i.e. change from participant to leader) or demote (i.e. change from leader to participant) a participant of a conference.
- Set / Unset delegation for a user. Delegation allows a user to give access to another user on the conference management.
- Join a conference.
Delegation
Delegation is the ability for the user to give the right to manage its conferences to someone else.
For example, a manager sets delegation to its assistant. The assistant can then create, modify and delete
the manager's conferences. Please note that both manager and assistant will be notified of events generated
for the conference.
As soon as the delegation right is removed by a delegator on its delegate, no more events will be received by the delegate,
even if he/she still has the right on the previously created conferences.
In the case the conferencing REST API is planned to be used from an administrator session, some extra provisioning steps are required.
In such case, a dedicated user must be created, to support all requests made from the administrator session (conference creation ...).
The provisioning steps to follow are:
- Create a user that will manage all conferences on behalf of end-users in 8770.
- Assign a phone number, email address to this user.
- Grant Conferencing rights to this user
- Edit /var/data/ics-group/connector2007/calendar.provider.acs.cfg
- Set Delegation.Account = _login_ (removing potential '#' or ' ' leading char)
- Set Delegation.Account.Email = _email_
- Set Delegation.Password = _GUI password_
A restart of the OpenTouch solution is recommended.
Restrictions / limitations
When creating a conference from an existing
iCalendar file, some limitations may be found:
- Only the first VEVENT component will be processed. Others will be ignored.
- Documents included inside the file (i.e. inline) will not be taken into account.
- If using the API from an administrator session, see Delegation extra provisioning steps.
History
Since version 2.2
Resources summary
Notifications summary
Resources
/conferences
Methods
Get all the user conferences.
The conferences of the user are the one created by himself (as the owner), or by one of its delegates.
It also contain the list of conferences he has been invited to.
Licenses
The license CONFERENCE is 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.
|
| expired | boolean | If true, response will include also expired conferences (default is false). |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
| code | type | media types | description |
|---|
| 200 | Conferences | application/json
| OK |
| 400 | | application/json
| Bad Request |
| 401 | | application/json
| Unauthorized |
| 403 | | application/json
| Forbidden |
| 500 | | application/json
| Internal Server Error |
| 503 | | application/json
| Service Unavailable |
Examples
[+] : Retrieve all user conferences
request :GET https://server/api/rest/1.0/conferences
Accept: application/json
response :200 OK
Content-Type: application/json
{
"conferences": [
{
"conferenceId": "0114398",
"callId": "110102371617872server",
"joinOnlineUrl": "http://server/call/0105130",
"leaderAccessCode": "0114398",
"participantAccessCode": "0105130",
"type": "SCHEDULED",
"profile": "MEETING",
"owner": {
"id": { "loginName": "alice", "phoneNumber": "32535",
"instantMessagingId": "alice@server", "companyEmail": "alice@server"},
"firstName": "Alice", "lastName": "A1", "displayName": "Alice A1" },
"startDate": "2015-10-06T17:10:26.000+02:00", "endDate": "2015-10-07T17:10:26.000+02:00",
"participants": [
{"party": {
"id": { "loginName": "bob", "phoneNumber": "32536",
"instantMessagingId": "bob@server", "companyEmail": "bob@server"},
"firstName": "Bob", "lastName": "B1", "displayName": "Bob B1"},
"leader": false}
],
"documents": [
{"id":"1.pdf","name":"leTelegramme-Brest-08-04-2015.pdf","type":"PRESENTATION",
"url":"https://server/slides/d.DEFAULT/44454641554C54/1_742E6672/1.pdf"}
]
}
]
} Get all the conferences in iCalendar format.
The client must request the server with an Accept HTTP header set to 'text/calendar'.
The Response body contains the .ics file.
Please refer to iCalendar for the list of supported properties of the RFC2445.
Licenses
The license CONFERENCE is 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.
|
| expired | boolean | If true, response will also include expired conferences (default is false). |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
Response
| code | type | media types | description |
|---|
| 200 | iCalendar | text/calendar
| OK |
| 400 | | text/calendar
| Bad Request |
| 401 | | text/calendar
| Unauthorized |
| 403 | | text/calendar
| Forbidden |
| 500 | | text/calendar
| Internal Server Error |
| 503 | | text/calendar
| Service Unavailable |
Examples
[+] : Retrieve all user conferences in iCalendar format
request :GET https://server/api/rest/1.0/conferences
Accept: text/calendar
response :200 OK
Content-Disposition: attachment; filename=carol_OTConferences.ics
Content-Type: text/calendar
BEGIN:VCALENDAR
PRODID:-//OpenTouch API//iCal4j 1.0//EN
VERSION:2.0
CALSCALE:GREGORIAN
BEGIN:VEVENT
DTSTAMP:20150717T160845Z
DTSTART:20150717T134900Z
DTEND:20150717T144900Z
SUMMARY:My Conference 1
X-ALE-CALLID:213551319825885server
UID:0177068
TRANSP:OPAQUE
URL:https://server/call/0158224
ORGANIZER;CN=Carole Bouquet:MAILTO:carole@server
CATEGORIES:MEETING
DESCRIPTION: Conference textual information
ATTACH;X-ALE-FILENAME=leTelegramme-Brest-08-04-2015.pdf;X-ALE-DOCTYPE=PRESENTATION:https://server/742E6672/1.pdf
ATTENDEE;CN=Bob Geldof:MAILTO:bob@server
BEGIN:VALARM
TRIGGER:-PT5M
ACTION:DISPLAY
DESCRIPTION:Reminder
END:VALARM
END:VEVENT
END:VCALENDAR
Create a conference from the given descriptor.
The minimum required parameters for a conference creation are:
- A subject.
- A conference type (scheduled / reservationless).
Depending on the selected type, some restrictions
may be applied (conference duration, visibility in iCalendar, ...)
- A conference profile.
The following parameters are optional when creating a conference:
- The start Date. If not set, the time and date of the server will be selected.
- The end Date. If not set, the server will consider the end date so that the duration will match the default duration depending on the type of conference.
- the list of participants.
Licenses
The license CONFERENCE is 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.
|
| details | boolean | If true, the created profile is included in the response (201
Created). If not set (or false), returned response only contain the
location header pointing to the newly created conference. |
| delegator | string | If specified, indicate the conference owner. Delegation must have been set previously. |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
body parameter| type | media types | description |
|---|
| ConferenceRequest | application/json
| Contains mandatory parameters and potentially optional ones to create a conference. |
Response
| code | type | media types | description |
|---|
| 201 | string | application/json
| CREATED |
| 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
[+] : Create a conference
request :POST https://server/api/rest/1.0/conferences
Accept: application/json
{
"type":"SCHEDULED","subject":"MyConfNb2","profile":"MEETING",
"startDate":"2015-07-17T08:15:00Z",
"endDate":"2015-07-17T23:15:00Z"
}response :201 CREATED
Associated notifications
Create or update a conference from a given iCalendar file.
Only the first VEVENT component of the iCalendar will be processed, others will be ignored.
If the UID matches an existing conference Id, then an update will be done.
For a conference update, the same restrictions applies
as the ones in PUT /conferences/{conferenceId}
Licenses
The license CONFERENCE is required.
Request
query parameters| parameter | type | description |
|---|
| details | boolean | If true, the created conference is included in the response (201
Created). If not set (or false), returned response only contain the
location header pointing to the newly created conference. |
| 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.
|
| delegator | string | If specified, indicate the conference owner. Delegation must have been set previously. |
cookie parameters| parameter | type | description |
|---|
| AlcUserId | string | Identifier of the Session
|
body parameter| type | media types | description |
|---|
| iCalendar | text/calendar
| Represents the iCalendar stream. |
Response
| code | media types | description |
|---|
| 201 | application/json
| CREATED |
| 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
[+] : Create a conference from an uploaded iCalendar
request :POST https://server/api/rest/1.0/conferences
Accept: application/json
Content-Type: text/calendar
BEGIN:VCALENDAR
PRODID:-//OpenTouch// 4.0//EN
VERSION:2.0
METHOD:PUBLISH
BEGIN:VEVENT
DTSTART:20150717T184900Z
DTEND:20150717T204900Z
TRANSP:OPAQUE
SEQUENCE:1437145129
DTSTAMP:20150717T145849Z
CATEGORIES:MEETING
SUMMARY:TestConfCreationNb1
DESCRIPTION:description of the conference
PRIORITY:5
STATUS:CONFIRMED
END:VEVENT
END:VCALENDAR
response :201 CREATED
Location: https://server/api/rest/1.0/conferences/0165152
Associated notifications
/conferences/delegates
Methods
Retrieve the delegates.
Licenses
The license CONFERENCE is 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 | ConferenceParticipantIds | 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 |
Set delegation to participant(s).
Licenses
The license CONFERENCE is 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 | media types | description |
|---|
| 204 | application/json
| No Content |
| 400 | application/json
| Bad Request |
| 401 | application/json
| Unauthorized |
| 403 | application/json
| Forbidden |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Unset delegation to participant(s).
Licenses
The license CONFERENCE is required.
Request
query parameters| parameter | type | description |
|---|
| partIds | string | list of comma separated participants Ids to unset. |
| 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 | media types | description |
|---|
| 204 | application/json
| No Content |
| 400 | application/json
| Bad Request |
| 401 | application/json
| Unauthorized |
| 403 | application/json
| Forbidden |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
/conferences/{conferenceId}
Methods
Get a specific conference.
Licenses
The license CONFERENCE is required.
Request
path parameters| parameter | type | description |
|---|
| conferenceId | string | the Id of the conference to retrieve. |
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 | Conference | 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 |
Modify a specific conference.
Only the provided conference parameters, if not null, will be modified.
Please note that some paramters can not be changed after creation:
- The conference profile (MEETING, WEBINAR ...)
- The start date if the conference has already started.
- Partial update of the recurrence is not accepted (the whole recurrence must be provided).
Licenses
The license CONFERENCE is required.
Request
path parameters| parameter | type | description |
|---|
| conferenceId | string | the Id of the conference to modify. |
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
|
body parameter| type | media types | description |
|---|
| ConferenceRequest | | the conference parameters to modify. |
Response
the modified conference.
| code | type | media types | description |
|---|
| 200 | Conference | 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 |
Associated notifications
Get a specific conference, as iCalendar format.
The client must request the server with an Accept HTTP header set to 'text/calendar'.
Response body contains the .ics file.
Licenses
The license CONFERENCE is required.
Request
path parameters| parameter | type | description |
|---|
| conferenceId | string | the Id of the conference to retrieve. |
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 | iCalendar | text/calendar
| OK |
| 400 | | text/calendar
| Bad Request |
| 401 | | text/calendar
| Unauthorized |
| 403 | | text/calendar
| Forbidden |
| 500 | | text/calendar
| Internal Server Error |
| 503 | | text/calendar
| Service Unavailable |
Delete a conference.
Licenses
The license CONFERENCE is required.
Request
path parameters| parameter | type | description |
|---|
| conferenceId | string | |
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 | media types | description |
|---|
| 204 | application/json
| No Content |
| 400 | application/json
| Bad Request |
| 401 | application/json
| Unauthorized |
| 403 | application/json
| Forbidden |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Associated notifications
/conferences/{conferenceId}/documents
Methods
Add a document to a conference.
Please note that in case of uploading a presentation document, the conference server needs some time to process
the document (split the document in slides). In such case the corresponding notification will be sent at the end of
the processing.
Attachement only documents are not concerned by this mechanism, and the associated notification is sent right after the
end of the upload.
The supported document format for presentation are:
- Microsoft Office document: Excel, Word, PowerPoint (if version and conversion supported on server side).
- Common image format: PNG, BMP, GIF, JPEG.
- Plain text files.
- Acrobat reader doculment (PDF).
Licenses
The license CONFERENCE is required.
Request
form parameters| parameter | type | description |
|---|
| file | byte | the document to add (uploaded from a form). |
path parameters| parameter | type | description |
|---|
| conferenceId | string | the conference Id. |
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 |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Associated notifications
/conferences/{conferenceId}/documents/{documentId}
Methods
Remove a document from a conference.
Licenses
The license CONFERENCE is required.
Request
path parameters| parameter | type | description |
|---|
| conferenceId | string | the conference Id. |
| documentId | string | the Id of the document to remove. |
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.
|
| details | boolean | If true, the modified conference is included in the response (200
OK). If not set (or false), returned response is 204 No Content. |
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 |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Associated notifications
/conferences/{conferenceId}/join
Methods
Join the conference.
Licenses
The license CONFERENCE is required.
Request
path parameters| parameter | type | description |
|---|
| conferenceId | string | the Id of the conference to join. |
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
|
body parameter| type | media types | description |
|---|
| JoinConferenceRequest | | the parameters needed to join the conference. |
Response
| code | media types | description |
|---|
| 200 | application/json
| No Content |
| 400 | application/json
| Bad Request |
| 401 | application/json
| Unauthorized |
| 403 | application/json
| Forbidden |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
/conferences/{conferenceId}/participants
Methods
Add participant(s) to a conference.
Licenses
The license CONFERENCE is required.
Request
path parameters| parameter | type | description |
|---|
| conferenceId | string | the conference Id. |
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.
|
| details | boolean | If true, the modified conference is included in the response (200
OK). If not set (or false), returned response is 204 No
Content. |
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 |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Associated notifications
Remove participant(s) from a conference.
Licenses
The license CONFERENCE is required.
Request
path parameters| parameter | type | description |
|---|
| conferenceId | string | the conference Id. |
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.
|
| partIds | string | list of comma separated participants Ids to remove. |
| details | boolean | If true, the modified conference is included in the response (200
OK). If not set (or false), returned response is 204 No Content. |
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 |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Associated notifications
/conferences/{conferenceId}/participants/promote
Methods
Promote participant(s) as leader(s).
Licenses
The license CONFERENCE is required.
Request
path parameters| parameter | type | description |
|---|
| conferenceId | string | the conference Id. |
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.
|
| details | boolean | If true, the modified conference is included in the response (200
OK). If not set (or false), returned response is 204 No Content. |
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 |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Associated notifications
Demote participants from leader role.
Licenses
The license CONFERENCE is required.
Request
path parameters| parameter | type | description |
|---|
| conferenceId | string | the conference Id. |
query parameters| parameter | type | description |
|---|
| partIds | string | list of comma separated participants Ids to demote. |
| 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.
|
| details | boolean | If true, the modified conference is included in the response (200
OK). If not set (or false), returned response is 204 No Content. |
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 |
| 500 | application/json
| Internal Server Error |
| 503 | application/json
| Service Unavailable |
Associated notifications
Representations
boolean'boolean' is a data type, having two values (true and false).
ConferenceDescriptor of a conference.
Contains all relevant information concerning a conference.
| Name | Type | Cardinality | Description |
|---|
| conferenceId | string | [0..1] | Unique identifier of a conference.
When creating a conference, this parameter should be null (will be ignored on server side). |
| callId | string | [0..1] | CallId of the conference used for call control operations.
When creating a conference, this parameter should be null (will be ignored on server side). |
| subject | string | [0..1] | Subject of the conference.
This is a brief description of the topic of a conference. |
| joinOnlineUrl | string | [0..1] | URL for joining the web conference (e.g. via a web browser). |
| leaderAccessCode | string | [0..1] | Leaders have to provide a specific access code when joining the conference. |
| participantAccessCode | string | [0..1] | Participant access code. |
| type | ConferenceType | [0..1] | The type of the conference. |
| profile | ConferenceProfile | [0..1] | Profile of the conference.
A profile is used to group a set of options. |
| owner | PartyInfo | [0..1] | Owner of the conference. |
| startDate | string | [0..1] | Date and time (ISO-8601 format) of the beginning of the conference.
It expects a format yyyy-MM-ddThh:mm:ss[Z|[+-]hh:mm]
Example: '2015-07-10T10:15:00Z'
When creating a conference, if the value is not set, the start time is the current
time of the server. |
| endDate | string | [0..1] | Date and time (ISO-8601) of the end of the conference.
If not set during conference creation, the server will apply default values for the conference
duration depending on its type (scheduled or reservationless). Refer to system administrator to
get these default values. |
| duration | string | [0..1] | Duration (ISO8601) of the conference, relative to the start date.
Example: 'PT01H30M' |
| participants | ConferenceParticipant | [0..*] | List of participants to the conference. |
| documents | ConferenceDocument | [0..*] | List of the documents uploaded for the conference. |
| audioPassword | string | [0..1] | If set, the user will have to enter the requested password when joining the audio conference. |
| webPassword | string | [0..1] | If set, the user will have to enter the requested password when joining the web conference. |
| recurrence | Recurrence | [0..1] | The recurrence of this conference. |
[+] : JSON Example{
"conferenceId": "string",
"callId": "string",
"subject": "string",
"joinOnlineUrl": "string",
"leaderAccessCode": "string",
"participantAccessCode": "string",
"type": "SCHEDULED | RESERVATIONLESS",
"profile": "MEETING | WEBINAR | TRAINING | CONFCALL",
"owner": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"startDate": "string",
"endDate": "string",
"duration": "string",
"participants": [ {
"party": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"leader": boolean,
"status": "string"
} ],
"documents": [ {
"id": "string",
"name": "string",
"type": "ATTACHMENT | PRESENTATION | ATTACHMENT_PRESENTATION",
"url": "string"
} ],
"audioPassword": "string",
"webPassword": "string",
"recurrence": {
"type": "DAILY | WEEKLY | MONTHLY | MONTHLY_BY_WEEK",
"interval": int,
"daysOfTheWeek": [ "string" ],
"dayOfTheMonth": int,
"weekOfTheMonth": int,
"nbOfOccurences": int
}
} |
Associated methods :
Descriptor for a conference document.
| Name | Type | Cardinality | Description |
|---|
| id | string | [0..1] | The Identifier of the document. |
| name | string | [0..1] | The name of the document. |
| type | ConferenceDocumentType | [0..1] | The document type. Only supported types of document can be presented. |
| url | string | [0..1] | URL to retrieve the document.
Please note that this URL can be used ONLY to download an attachment.
For a presentation, this is the root URL from which browsing slides can be done. |
[+] : JSON Example{
"id": "string",
"name": "string",
"type": "ATTACHMENT | PRESENTATION | ATTACHMENT_PRESENTATION",
"url": "string"
} |
Conference document type.
| Value | Description |
|---|
| ATTACHMENT | The document is not one of the supported presentation format.
It can be downloaded by participants. |
| PRESENTATION | The document is one of the well known supported file format.
This file will be processed by the server so that it can be accessible slide by slide.
Supported file format for presentation are:
- Microsoft PowerPoint
- Microsoft Word
- Microsoft Excel
- Adobe PDF
- Plain text file
- PNG image
- GIF image
- JPG image
- BMP image
|
| ATTACHMENT_PRESENTATION | The file can be downloaded as an attachment, but also be accessed slide by slide (presentation). |
Conference Member descriptor.
A conference member can be either a simple participant, or a leader.
| Name | Type | Cardinality | Description |
|---|
| party | PartyInfo | [1] | Party Info of the participant of a conference. |
| leader | boolean | [0..1] | Indicate if this is a simple participant (false) or a leader (true). |
| status | string | [0..1] | This optional field can indicate the participant status (accepted / declined).
It can be filled in case of interaction with other calendar providers. |
Container for a list of members Ids of a conference.
| Name | Type | Cardinality | Description |
|---|
| participantIds | string | [0..*] | List of participant Ids. |
[+] : JSON Example{
"participantIds": [ "string" ]
} |
Associated methods :
Container for a list of members of a conference.
Associated method :
Conference profile is a convenient way of grouping a set of options on the conference server.
| Value | Description |
|---|
| MEETING | The profile correspond to a standard meeting.
The main characteristics of such profile are:
- Callers names are recorded and announced when joining the conference.
- No limitations on conversation between members (except the ones specific to leader / participant role).
- All members can control their audio (mute / unmute ...).
- All members can join on their preferred way (audio only, web only, audio and web).
|
| WEBINAR | This profile is designed for a webinar session.
The main characteristics of such profile are:
- Only leaders can interact with participants. Participants can not see each other.
- Participants join the audio conference as muted, and can not change it.
- The audio conference will end as soon as the last leader leaves.
- Callers names are not recorded, nor announced (not even join tones).
|
| TRAINING | This profile is designed for a training session.
The main characteristics of such profile are:
- The presentation is lead by the owner (the 'trainer').
- Trainees join the audio conference as muted, but they can not change it.
- The audio conference will end as soon as the last leader leaves.
- Callers names are recorded, and announced (no join tones).
|
| CONFCALL | This profile correspond to an audio only conference session. |
Descriptor of a conference request, used to create or modify a conference.
| Name | Type | Cardinality | Description |
|---|
| type | ConferenceType | [0..1] | The type of the conference. |
| subject | string | [0..1] | Subject of the conference.
This is a brief description of the topic of a conference. |
| profile | ConferenceProfile | [0..1] | Profile of the conference.
A profile is used to group a set of options. |
| startDate | string | [0..1] | Date and time (ISO8601 format) of the beginning of the conference.
It expects a format yyyy-MM-ddThh:mm:ss[Z|[+-]hh:mm]
Example: '2015-07-10T10:15:00Z'
When creating a conference, if the value is not set, the start time is the current
time of the server. |
| endDate | string | [0..1] | Date and time (ISO8601) of the end of the conference.
If not set during conference creation, the server will apply default values for the conference
duration depending on its type (scheduled or reservationless). Refer to system administrator to
get these default values. |
| duration | string | [0..1] | Duration (ISO8601) of the conference, relative to the start date.
Example: 'PT01H30M' |
| recurrence | Recurrence | [0..1] | The recurrence of this conference.
All needed fields must be provided for conference creation or modification. |
| participants | ConferenceParticipant | [0..*] | List of participants to the conference. |
| audioPassword | string | [0..1] | If set, the user will have to enter the requested password when joining the audio conference. |
| webPassword | string | [0..1] | If set, the user will have to enter the requested password when joining the web conference. |
[+] : JSON Example{
"type": "SCHEDULED | RESERVATIONLESS",
"subject": "string",
"profile": "MEETING | WEBINAR | TRAINING | CONFCALL",
"startDate": "string",
"endDate": "string",
"duration": "string",
"recurrence": {
"type": "DAILY | WEEKLY | MONTHLY | MONTHLY_BY_WEEK",
"interval": int,
"daysOfTheWeek": [ "string" ],
"dayOfTheMonth": int,
"weekOfTheMonth": int,
"nbOfOccurences": int
},
"participants": [ {
"party": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"leader": boolean,
"status": "string"
} ],
"audioPassword": "string",
"webPassword": "string"
} |
Associated methods :
Container for a list of conferences.
| Name | Type | Cardinality | Description |
|---|
| conferences | Conference | [0..*] | List of conferences |
[+] : JSON Example{
"conferences": [ {
"conferenceId": "string",
"callId": "string",
"subject": "string",
"joinOnlineUrl": "string",
"leaderAccessCode": "string",
"participantAccessCode": "string",
"type": "SCHEDULED | RESERVATIONLESS",
"profile": "MEETING | WEBINAR | TRAINING | CONFCALL",
"owner": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"startDate": "string",
"endDate": "string",
"duration": "string",
"participants": [ {
"party": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"leader": boolean,
"status": "string"
} ],
"documents": [ {
"id": "string",
"name": "string",
"type": "ATTACHMENT | PRESENTATION | ATTACHMENT_PRESENTATION",
"url": "string"
} ],
"audioPassword": "string",
"webPassword": "string",
"recurrence": {
"type": "DAILY | WEEKLY | MONTHLY | MONTHLY_BY_WEEK",
"interval": int,
"daysOfTheWeek": [ "string" ],
"dayOfTheMonth": int,
"weekOfTheMonth": int,
"nbOfOccurences": int
}
} ]
} |
Associated method :
Indicates the kind of conference the user wants to program.
| Value | Description |
|---|
| SCHEDULED | This conference type is used when the user knows when and how long the conference will last.
It is the most common type of conference, and has a limited maximum duration (example 24 hours).
Refer to your system administrator to check this setting. |
| RESERVATIONLESS | This kind of conference can cover a larger period (e.g. 6 months).
Refer to system administrator for the maximum duration of such conference. |
The support of the iCalendar format, as specified by the
RFC2445
(updated by
RFC5545) is detailed hereafter.
Interoperability with others iCalendar providers is respected. Any custom properties or parameters defined in this API should be ignored if they were not found
in existing iCalendar. In such case, the server will use default values if needed.
Only the VEVENT calendar component is supported (no VTODO ...), with the exception of a fixed VALARM (15 minutes reminder) embedded in the VEVENT.
Only the properties listed here are supported, other ones will be ignored.
| Property / Parameter |
Description |
| UID |
Unique identifier of the conference (not to be confused with the callId used for call control operations). |
| PRODID |
Contains a brief description of the product (OpenTouch) and the generator used for ICal format. |
| SUMMARY |
Subject of the conference (the title). |
| DESCRIPTION |
Contain textual information about the conference, including a link to the join online URL. |
| X-ALT-DESC |
Contain HTML description of a conference (e.g. created from outlook plugin). |
| URL |
The join Online URL for the conference. |
| ORGANIZER |
The owner of the conference (i.e. the one who has created it, directly or by delegation).
Example:ORGANIZER;CN=Alice A1:MAILTO:alice@server.com
Note: If the owner is a user of the system, the CN field ("firstName lastName") as well as the MAILTO field will be provided.
If not, only the MAILTO will be provided.
|
| DTSTART |
The start date / time of a conference. Preferred time is relative to UTC, in ISO8601 format. |
| DTEND |
The end date / time of a conference. Preferred time is relative to UTC, in ISO8601 format. |
| DTSTAMP |
The timestamp of the generated iCalendar. This is not to be confused with CREATED and LAST-MODIFIED (not managed). |
| CATEGORIES |
Will be used to carry the conference profile, as it is used today on OTC-PC clients:
MEETING, WEBINAR, TRAINING, and CONFCALL.
If not provided, the default profile will be considered to be MEETING.
|
| TRANSP |
Transparency can be used to search for free/busy period.
(TRANSP: TRANSPARENT for reservationless, TRANSP: OPAQUE for scheduled).
|
| LOCATION |
Contain the conference bridge phone number, as well as the conference Id, |
| ATTENDEE |
Participant of a conference.
The same rule applies for the CN field and MAILTO field as it is in ORGANIZER.
Example:ATTENDEE;CN="Alice A1";MAILTO:alice@server.fr.
|
| RRULE |
Recurrence rule for the conference.
Example 1: daily
RRULE:FREQ=DAILY;INTERVAL=1.
Example 2: weekly, every monday and friday
RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,FR;WKST=MO.
Example 3: monthly, every 2 months, the 20th
RRULE:FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=20.
Example 4: monthly by week, monday the third week of every 2 months
RRULE:FREQ=MONTHLY;INTERVAL=2;BYDAY=MO;BYSETPOS=3.
|
| ATTACH |
File attachments to be added to the conference.
As much as possible, URL should be used to refer to these files,
instead of embedding the corresponding bytes in the ICal file.
|
| X-ALE-FILENAME |
Parameter used in the ATTACH property to specify the file name of the attachment. |
| X-ALE-DOCTYPE |
Parameter used in the ATTACH property to specify the type of the attachment. See ConferenceDocumentType |
| X-ALE-AUDIOPWD |
Parameter used to store the audio password of the conference. |
| X-ALE-WEBPWD |
Parameter used to store the web password of the conference. |
Key information to help retrieving a participant.
| Name | Type | Cardinality | Description |
|---|
| loginName | string | [0..1] | Login name. |
| phoneNumber | string | [0..1] | Company phone number. |
| instantMessagingId | string | [0..1] | Instant messaging identity. |
| companyEmail | string | [0..1] | Company email. |
'int' is a 32-bit number (-2147483648 to 2147483647).
JoinConferenceRequestContainer used for passing parameters to join a conference.
| Name | Type | Cardinality | Description |
|---|
| audioOnly | boolean | [0..1] | Join only the audio conference. Default is false. |
| webOnly | boolean | [0..1] | Join only the web conference. Default is false. |
| phone | string | [1] | Device phone number on which the audio conference bridge will call. |
| webPassword | string | [0..1] | The password to join the web conference. If set during conference creation, audioPassword will be requested at TUI level. |
Associated method :
Event sent when a new conference has been created.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnConferenceCreated' |
| loginName | string | [1] | Login name of the user receiving the event. |
| conference | Conference | [0..1] | The newly created conference. |
[+] : JSON Example{
"eventName": "string",
"loginName": "string",
"conference": {
"conferenceId": "string",
"callId": "string",
"subject": "string",
"joinOnlineUrl": "string",
"leaderAccessCode": "string",
"participantAccessCode": "string",
"type": "SCHEDULED | RESERVATIONLESS",
"profile": "MEETING | WEBINAR | TRAINING | CONFCALL",
"owner": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"startDate": "string",
"endDate": "string",
"duration": "string",
"participants": [ {
"party": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"leader": boolean,
"status": "string"
} ],
"documents": [ {
"id": "string",
"name": "string",
"type": "ATTACHMENT | PRESENTATION | ATTACHMENT_PRESENTATION",
"url": "string"
} ],
"audioPassword": "string",
"webPassword": "string",
"recurrence": {
"type": "DAILY | WEEKLY | MONTHLY | MONTHLY_BY_WEEK",
"interval": int,
"daysOfTheWeek": [ "string" ],
"dayOfTheMonth": int,
"weekOfTheMonth": int,
"nbOfOccurences": int
}
}
} |
Associated methods :
Event sent when a conference has been deleted.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnConferenceDeleted' |
| loginName | string | [1] | Login name of the user receiving the event. |
| conferenceId | string | [0..1] | The conferenceId of the deleted conference. |
Associated method :
Event sent when a conference has been modified.
| Name | Type | Cardinality | Description |
|---|
| eventName | string | [1] | The name of the event : 'OnConferenceModified' |
| loginName | string | [1] | Login name of the user receiving the event. |
| conference | Conference | [0..1] | The modified conference. |
[+] : JSON Example{
"eventName": "string",
"loginName": "string",
"conference": {
"conferenceId": "string",
"callId": "string",
"subject": "string",
"joinOnlineUrl": "string",
"leaderAccessCode": "string",
"participantAccessCode": "string",
"type": "SCHEDULED | RESERVATIONLESS",
"profile": "MEETING | WEBINAR | TRAINING | CONFCALL",
"owner": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"startDate": "string",
"endDate": "string",
"duration": "string",
"participants": [ {
"party": {
"id": {
"loginName": "string",
"phoneNumber": "string",
"instantMessagingId": "string",
"companyEmail": "string"
},
"firstName": "string",
"lastName": "string",
"displayName": "string"
},
"leader": boolean,
"status": "string"
} ],
"documents": [ {
"id": "string",
"name": "string",
"type": "ATTACHMENT | PRESENTATION | ATTACHMENT_PRESENTATION",
"url": "string"
} ],
"audioPassword": "string",
"webPassword": "string",
"recurrence": {
"type": "DAILY | WEEKLY | MONTHLY | MONTHLY_BY_WEEK",
"interval": int,
"daysOfTheWeek": [ "string" ],
"dayOfTheMonth": int,
"weekOfTheMonth": int,
"nbOfOccurences": int
}
}
} |
Associated methods :
Full description of a party (i.e. participant's description).
| Name | Type | Cardinality | Description |
|---|
| id | Identifier | [1] | Key information to help retrieving a participant. |
| firstName | string | [0..1] | First name of the participant. |
| lastName | string | [0..1] | Last name of the participant. |
| displayName | string | [0..1] | Display name of the participant. |
| Name | Type | Cardinality | Description |
|---|
| type | RecurrenceType | [1] | DAILY, WEEKLY, MONTHLY, MONTHLY_BY_WEEK. |
| interval | int | [1] | Interval. Means 'every x days / weeks / months |
| daysOfTheWeek | string | [0..*] | List of named days used in weekly and monthly by week types.
Named days are monday, tuesday, ... sunday. |
| dayOfTheMonth | int | [0..1] | Day of the month used in monthly recurrence.
E.g. Meeting every 15th of the month. |
| weekOfTheMonth | int | [0..1] | Week of the month for monthly by week type.
E.g. Meeting every month on monday of the 2nd week. |
| nbOfOccurences | int | [0..1] | The number of occurrence. If set (different from 0), the end date will be ignored when creating a conference.
NOTE: This parameter should be considered as a helper to create and schedule a meeting, and must be ignored right after the
conference has been created.
The system will correctly compute the start date, end date and duration of the conference, taking into account the value of this parameter.
Once the conference created, this parameter should be considered as meaningless.
|
[+] : JSON Example{
"type": "DAILY | WEEKLY | MONTHLY | MONTHLY_BY_WEEK",
"interval": int,
"daysOfTheWeek": [ "string" ],
"dayOfTheMonth": int,
"weekOfTheMonth": int,
"nbOfOccurences": int
} |
The recurrence type.
| Value | Description |
|---|
| DAILY | Recurrence is daily.
Use in conjunction with interval.
E.g. everyday, or every 2 days. |
| WEEKLY | Recurrence is weekly.
Use in conjunction with interval, daysOfTheWeek.
E.g. every week on monday, or every 2 weeks on mondays and tuesday ... |
| MONTHLY | Recurrence is monthly.
Use in conjunction with interval, dayOfTheMonth.
E.g. every month the 14th, or every 2 months the 15th. |
| MONTHLY_BY_WEEK | Recurrence is monthly by week.
Use in conjunction with interval, weekOfTheMonth, daysOfTheWeek.
E.g. every 2nd month, the 3rd week, on monday and friday. |
'string' represents character strings.