Introduction

Overview

Each resource can be accessed through the following kind of URL:
http(s)://<host>:<port>/api/rest/<version>/<resource _name>
Where: 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.52.42.32.2.12.22.1.12.12.0.22.0.1

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 :
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:
typecodehelpMessagecanRetry
NOT_READY1000The server is not yet available. Please retry later if the initialization is not finished.true
INVALID_SESSION1001No valid session found for the given identifier. Please logout and login with correct credentials.true
NOT_ALLOWED1002The operation is not allowed, because of insufficient rights or bad credential. Please contact the administrator to fix the problem.false
NOT_FOUND1003Missing or bad parameter sent by a request on a service. Fix the problem and retry.true
NOT_EXPECTED1004The request can not be performed due to current user's state.Check the state or fix your request before sending it back.true
NOT_SUPPORTED1005This operation is not supported. Please check the documentation.false
BAD_PARAMETER1006Request parameters are not correct. Please fix the problem and send the request back.true
SERVER_PROBLEM1007Server 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: 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).
HttpStatus
List of all HTTP status.
ValueDescription
CONTINUE100 Continue
SWITCHING_PROTOCOLS101 Switching Protocols
PROCESSING102 Processing
OK200 OK
CREATED201 Created
ACCEPTED202 Accepted
NON_AUTHORITATIVE_INFORMATION203 Non-Authoritative Information
NO_CONTENT204 No Content
RESET_CONTENT205 Reset Content
PARTIAL_CONTENT206 Partial Content
MULTI_STATUS207 Multi-Status
ALREADY_REPORTED208 Already Reported
IM_USED226 IM Used
MULTIPLE_CHOICES300 Multiple Choices
MOVED_PERMANENTLY301 Moved Permanently
FOUND302 Found
MOVED_TEMPORARILY302 Moved Temporarily
SEE_OTHER303 See Other
NOT_MODIFIED304 Not Modified
USE_PROXY305 Use Proxy
TEMPORARY_REDIRECT307 Temporary Redirect
BAD_REQUEST400 Bad Request
UNAUTHORIZED401 Unauthorized
PAYMENT_REQUIRED402 Payment Required
FORBIDDEN403 Forbidden
NOT_FOUND404 Not Found
METHOD_NOT_ALLOWED405 Method Not Allowed
NOT_ACCEPTABLE406 Not Acceptable
PROXY_AUTHENTICATION_REQUIRED407 Proxy Authentication Required
REQUEST_TIMEOUT408 Request Timeout
CONFLICT409 Conflict
GONE410 Gone
LENGTH_REQUIRED411 Length Required
PRECONDITION_FAILED412 Precondition failed
REQUEST_ENTITY_TOO_LARGE413 Request Entity Too Large
REQUEST_URI_TOO_LONG414 Request-URI Too Long
UNSUPPORTED_MEDIA_TYPE415 Unsupported Media Type
REQUESTED_RANGE_NOT_SATISFIABLE416 Requested Range Not Satisfiable
EXPECTATION_FAILED417 Expectation Failed
INSUFFICIENT_SPACE_ON_RESOURCE419 Insufficient Space on Resource
METHOD_FAILURE420 Method Failure
DESTINATION_LOCKED421 Destination Locked
UNPROCESSABLE_ENTITY422 Unprocessable Entity
LOCKED423 Locked
FAILED_DEPENDENCY424 Failed Dependency
UPGRADE_REQUIRED426 Upgrade Required
INTERNAL_SERVER_ERROR500 Internal Server Error
NOT_IMPLEMENTED501 Not Implemented
BAD_GATEWAY502 Bad Gateway
SERVICE_UNAVAILABLE503 Service Unavailable
GATEWAY_TIMEOUT504 Gateway Timeout
HTTP_VERSION_NOT_SUPPORTED505 HTTP Version Not Supported
VARIANT_ALSO_NEGOTIATES506 Variant Also Negotiates
INSUFFICIENT_STORAGE507 Insufficient Storage
LOOP_DETECTED508 Loop Detected
NOT_EXTENDED510 Not Extended
int
'int' is a 32-bit number (-2147483648 to 2147483647).
OTRestApiDescriptor
High level information of the server and supported REST API versions.
NameTypeCardinalityDescription
serverInfoServerInfo[0..1]

Since version 2.1

Provide extra information about the server hosting the REST API.
versionsVersion[1..*]List of the versions supported on the server.
[+] : JSON Example
ProductVersion
Give information about the version installed on the server.
NameTypeCardinalityDescription
majorstring[0..1]Major version of the product. This field should help to identify the release of a product.
minorstring[0..1]Minor revision of the product. This field is for internal needs.
[+] : JSON Example
RestErrorInfo
Contains all information from errors sent while invoking REST operations on resources.
NameTypeCardinalityDescription
httpStatusHttpStatus[0..1]The HTTP status.
codeint[0..1]A REST API error code, linked with the above type, to help the user's application to quickly differentiate possible errors.
helpMessagestring[0..1]A help message, associated with the above type and code, providing a more detailed cause of the error.
typestring[0..1]A REST API error type, which group all possible underlying errors in a finite number of possibilities.
innerMessagestring[0..1]This message contains relevant information to help an administrator or support team to find the cause of the problem.
canRetryboolean[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
ServerInfo
Provide information on the server.
NameTypeCardinalityDescription
productNamestring[1]Friendly description of the product.
productTypestring[1]Short name of the product.
productVersionProductVersion[0..1]Version of the product.
haModeboolean[0..1]Indicate if the server is in High Availability mode.
[+] : JSON Example
string
'string' represents character strings.
Version
NameTypeCardinalityDescription
idstring[1]Identifier of the version (e.g. '1.0').
statusstring[1]Status of the given version. 'CURRENT' means this is the latest version on the server.
publicUrlstring[1]Authentication URL to use from public (i.e. internet) access.
internalUrlstring[1]Authentication URL to use from private (i.e. intranet) access.
[+] : JSON Example

Session management

Resources summary

ResourceMethodDescription
/sessionsGETGets information of the opened session.
POSTOpen a session for a user or an administrator.
DELETECloses a Session.
/sessions/keepalivePOSTRestarts the session timer.

Resources

/sessions

Methods
GET/sessions
Gets information of the opened session.
Licenses
No license required.
Request
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200SessionInfoapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
POST/sessions
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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
SessionRequestapplication/json
This element is used to open a Session.
Response
codetypemedia typesdescription
200SessionInfoapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Creation of a user session

[+] : Creation of an administrator session

[+] : Creation of a supervised user session

DELETE/sessions
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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content (The session is closed)
400application/json
Bad Request
403application/json
Forbidden (The session is already closed)
500application/json
Internal Server Error (The session doesn't exist)
503application/json
Service Unavailable

/sessions/keepalive

Methods
POST/sessions/keepalive
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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content (The session timer has been correctly refreshed)
400application/json
Bad Request
403application/json
Forbidden (The session doesn't exist)
500application/json
Internal Server Error
503application/json
Service Unavailable

Representations

boolean
'boolean' is a data type, having two values (true and false).
int
'int' is a 32-bit number (-2147483648 to 2147483647).
Service
This value contains all available information about a local service.
NameTypeCardinalityDescription
serviceNamestring[1]This value contains the name of the service.
serviceVersionstring[0..1]This value contains the version of the service, which allows an application to check its compatibility with the service.
relativeUrlstring[1]This value contains the relative URL of the service, which allows a consumer to access it.
[+] : JSON Example
SessionInfo
Session information.
NameTypeCardinalityDescription
adminboolean[0..1]

Since version 2.1

Indicate if the session has been opened by an administrator.
timeToLiveint[0..1]The duration of the Session in seconds.
publicBaseUrlstring[0..1]This value contains the public base URL which must be used by a consumer to access services from the Internet.
privateBaseUrlstring[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.
servicesService[0..*]All information available about the local services provided by public API for the current user.
capabilitiesstring[0..*]The capabilities of the current user : licenses, rights).
[+] : JSON Example
Associated methods :
SessionRequest
This element is used to open a Session.
NameTypeCardinalityDescription
applicationNamestring[1]Application name to check the rights or to take a particular license.
applicationAddressstring[0..1]Application address.
supervisedAccountSupervisedAccount[0..1]Identifier used to retrieve the supervised user (Administrator authentication but user session).
[+] : JSON Example
Associated method :
string
'string' represents character strings.
SupervisedAccount
The supervised user description.
NameTypeCardinalityDescription
idstring[1]The identifier itself. The type of this value is given by the SupervisedAccountType attribute.
typeSupervisedAccountType[1]Gives the type of the identifier.
[+] : JSON Example
SupervisedAccountType
The supervised account type values.
ValueDescription
LOGIN_NAMEThe identifier is a login name.
PHONE_NUMBERThe identifier is a phone number.
EMAILThe identifier is an email.
INSTANT_MESSAGING_IDThe identifier is an instant messaging id.

User information

Resources summary

ResourceMethodDescription
/loginsGETAn administrator can get the list of the users (login name).
/usersGET Find information about a user from its login name, company email, company phone or instant messaging identifier.
/users/{loginName}GETGets information about a user account.
/users/{loginName}/passwordPUTChange user's password.
/users/{loginName}/preferencesGETGets information about user's preferences.
POSTUpdates information about user's preferences.
/users/{loginName}/preferences/telephonyGETGets information about user's telephony preferences:
  • User's CLIR mode
  • ...
POSTUpdates information about user's telephony preferences:
  • User's CLIR mode
  • ...

Notifications summary

NotificationDescription
OnPreferencesChangedThis 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).

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

Resources

/logins

Methods
GET/logins
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
parametertypedescription
typesstring

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.
apiRightsstring

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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200LoginsResponseapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

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

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

[+] : Get STANDARD user's logins. The session was opened by a administrator.

[+] : Retrieve logins of MULTIMEDIA user's who have TELEPHONY_BASIC or TELEPHONY_ADVANCED rights. The session was opened by a administrator.

/users

Methods
GET/users
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
parametertypedescription
loginNamestringLogin name of the user to retrieve the account description.
companyEmailstring

Since version 2.2.1

Company email of the user to retrieve the account description.
instantMessagingIdstring

Since version 2.2.1

Instant messaging identifier of the user to retrieve the account description.
companyPhonestringCompany phone of the user to retrieve the account description.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
Returns a redirect response to /users/{loginName} resource if a matching user is found.
codemedia typesdescription
307application/json
Redirect
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable

/users/{loginName}

Methods
GET/users/{loginName}
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
parametertypedescription
loginNamestringLogin name of the user to retrieve the account description.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
Returns the result code and, if the code is SUCCESS, information about the concerned user User
codetypemedia typesdescription
200Userapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

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

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

Associated notifications

/users/{loginName}/password

Methods
PUT/users/{loginName}/password
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
parametertypedescription
loginNamestringLogin name of the user to change the password.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
ChangePasswordRequestcontaining the old and the new passwords
Response
Returns the result code and
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/users/{loginName}/preferences

Methods
GET/users/{loginName}/preferences
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
parametertypedescription
loginNamestringLogin name of the user to retrieve the preferences.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
Returns the result code and, if the code is SUCCESS, preferences about the concerned user UserPreferences
codetypemedia typesdescription
200UserPreferencesapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Get user's preferences for which the session is opened.

POST/users/{loginName}/preferences
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
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
UserPreferencesapplication/json
Response
Returns the result code.
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : set user's preferences for which the session is opened.

Associated notifications

/users/{loginName}/preferences/telephony

Methods
GET/users/{loginName}/preferences/telephony
Gets information about user's telephony preferences:
  • User's CLIR mode
  • ...
History
Since version 2.1
Licenses
No license required.
Request
path parameters
parametertypedescription
loginNamestringLogin name of the user to retrieve the telephony preferences.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
Returns the result code and, if the code is SUCCESS, telephony preferences about the concerned user TelephonyPreferences
codetypemedia typesdescription
200TelephonyPreferencesapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Get user's telephony preferences for which the session is opened.

POST/users/{loginName}/preferences/telephony
Updates information about user's telephony preferences:
  • User's CLIR mode
  • ...
History
Since version 2.1
Licenses
No license required.
Request
path parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
TelephonyPreferencesapplication/json
Response
Returns the result code.
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : set user's telephony preferences for which the session is opened.

Associated notifications

Representations

ApplicationRight
Application right values.
ValueDescription
BUSINESS_COMMUNICATIONSUser has BUSINESS_COMMUNICATIONS right.
CONFERENCINGUser has CONFERENCING right.
DESKTOPUser has DESKTOP right.
NOMADICUser has NOMADIC right (only for MULTIMEDIA users).
NOMADIC_SIPUser has NOMADIC_SIP right (only for STANDARD users).
NOMADIC_GSMUser has NOMADIC_SIP right (only for STANDARD users).
MOBILEUser has OFF_SITE_MOBILITY right (ie right to use a mobile phone).
TABLETUser has TABLET right.
VOICE_MAILUser has VOICE_MAIL right.
FLEX_OFFICEUser has FLEX_OFFICE right.
ChangePasswordRequest
Request to change password of the user
NameTypeCardinalityDescription
oldPasswordstring[1]Old password
newPasswordstring[1]New password
[+] : JSON Example
Associated method :
ClirMode
CLIR state values
ValueDescription
UNKNOWNCLIR mode can not be determined.
NOT_SUPPORTEDCLIR mode is not supported.
INACTIVECLIR is inactive
ACTIVECLIR is active
INACTIVE_NOT_UPDATABLECLIR is inactive but can't be modified
ACTIVE_NOT_UPDATABLECLIR is active but can't be modified
CustomAttributes
Describes custom attributes associated to a user.
NameTypeCardinalityDescription
global{ string , string }[0..*]Global custom attributes.
user{ string , string }[0..*]User custom attributes.
[+] : JSON Example
Device
Describe a device.
NameTypeCardinalityDescription
typeDeviceType[0..1]Device's type.
idstring[0..1]Device identifier which is used to identify the device in telephony requests and events.
labelstring[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.
subTypestring[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, ...
associatedNumberstring[0..1]If the device type is MOBILE this parameter defines the real number of the mobile.
configIdstring[0..1]

Reserved: DO NOT USE.

[+] : JSON Example
DeviceType
The device type values.
ValueDescription
DECTA wireless phone set used within the enterprise.
DESKPHONEA phone set on an office's desk.
MOBILEA mobile phone.
NOMADICAllows to temporarily use an external phone.
SOFTPHONEA phone started from a computer with VOIP.
DialingRule

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)

NameTypeCardinalityDescription
countryCodestring[1]Country code.
externalPrefixstring[1]External prefix.
addPfxForNbLengthint[1]Phone number length above which we must add the external prefix.
areaCodestring[0..1]Area code.
exceptionRulesExceptionRule[0..*]Exception rules.
[+] : JSON Example
ExceptionRule

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.

NameTypeCardinalityDescription
lengthExceptionint[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.
beginPatternExceptionstring[1]Specifies the pattern for which, when present at the beginning of a phone number, we do not dial the external prefix.
[+] : JSON Example
int
'int' is a 32-bit number (-2147483648 to 2147483647).
LoginsResponse
The get logins response.
NameTypeCardinalityDescription
loginNamesstring[1..*]List of logins matching the request.
[+] : JSON Example
Associated method :
OnPreferencesChanged
This event is sent on any change on the user's preferences.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnPreferencesChanged'
loginNamestring[1]The login name of the user.
preferencesUserPreferences[1]The changed user preferences object.
[+] : JSON Example
Associated methods :
OnUserCreated

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

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

NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnUserCreated'
userUser[1]The created user object.
[+] : JSON Example
OnUserDeleted

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

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

NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnUserDeleted'
loginNamestring[1]The login name of the deleted user.
[+] : JSON Example
OnUserInfoChanged
This event is sent on any change on the user's data.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnUserInfoChanged'
userUser[1]The changed user object.
[+] : JSON Example
Associated method :
Salutation
ValueDescription
MRMister title
MRSMadam title
MISSMiss title
string
'string' represents character strings.
TelephonyPreferences
Describes user's telephony preferences.
NameTypeCardinalityDescription
clirModeClirMode[0..1]

Since version 2.1

User's telephony preferences
[+] : JSON Example
Associated methods :
User
The description of a user
NameTypeCardinality*1Description
companyPhonestring[0..1]User's company phone number.
salutationSalutation[1]

Since version 2.5

User's salutation.
firstNamestring[0..1]First name of the User or Administrator owner of this Account.
lastNamestring[0..1]Last name of the User or Administrator owner of this Account.
companyEmailstring[0..1]Company e-mail of the User or the Administrator.
loginNamestring[0..1]Login name which identifies the User Account.
instantMessagingIdstring[0..1]Instant messaging identifier of the User.
typeUserType[0..1]XUser's type.
sitestring[0..1]X

Since version 2.5

Name of the site.
departmentstring[0..1]X

Since version 2.5

Name of the department.
vcardPathstring[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

voicemailVoicemail[0..1]User's voicemail description.
devicesDevice[0..*]XUser's devices.
dialingRuleDialingRule[0..1]X

Since version 2.1

User's dialing rule description.
apiRightsUserRight[0..*]X

Since version 2.1.1

User's API rights.
applicationRightsApplicationRight[0..*]X

Since version 2.2

User's application rights. The valid rights ApplicationRight are added in this list.
sipUristring[0..1]

Since version 2.2

User's SIP URI.
customAttributesCustomAttributes[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
Associated method :
UserPreferences
The preferences of a user
NameTypeCardinalityDescription
guiLanguagestring[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.
tuiLanguagestring[0..1]

Since version 2.5

TUI language of the User or the Administrator.
personalMobilestring[0..1]User's mobile phone number.
professionalMobilestring[0..1]User's company mobile phone number. Only multimedia users can update their professional phone number.
personalPhonestring[0..1]User's personal phone number.
telephonyTelephonyPreferences[0..1]

Since version 2.1

User's telephony preferences.
colleaguestring[0..1]

Since version 2.1

User's colleague.
[+] : JSON Example
Associated methods :
UserRight
User right values.
ValueDescription
TELEPHONY_BASICUser has TELEPHONY_BASIC right.
TELEPHONY_ADVANCEDUser has TELEPHONY_ADVANCED right.
MESSAGINGUser has MESSAGING right.
CONFERENCING

Since version 2.1.1

User has CONFERENCING right.
UserType
User type values.
ValueDescription
STANDARDUser is a standard user.
MULTIMEDIAUser is a multimedia user.
Voicemail
Describes user's voicemail.
NameTypeCardinalityDescription
numberstring[1]Voicemail number.
typeVoicemailType[1]

Since version 2.2

Voicemail type.
[+] : JSON Example
VoicemailType
Voicemail type values
ValueDescription
VM_4635Integrated 46x5 voice mail system , for STANDARD user.
VM_4645Integrated 46x5 voice mail system , for STANDARD user.
VM_UMUnified Messaging, based on mail servers (Exchange, Domino or any IMAP4 compliant system).
VM_LOCAL_STORAGEInternal OT storage
EXTERNALExternal 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:

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:

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:

A subscription response will provide following information to the user:

The following remarks must be taken in consideration while designing a REST client:


NOTE1: License count check for administrator session.
An administrator can subscribe to event notification concerning a subset of users. 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:

Resources summary

ResourceMethodDescription
/subscriptionsPOSTCreate a subscription for event notification.
PUTUpdate an existing subscription for event notification.
/subscriptions/{subscriptionId}DELETERemove a subscription.

Resources

/subscriptions

Methods
POST/subscriptions
Create a subscription for event notification.
Licenses
The license TELEPHONY_ADVANCED or MESSAGING is required.
Request
cookie parameters
parametertypedescription
AlcUserIdstringThe user framework session Identifier, received as a cookie.
body parameter
typemedia typesdescription
SubscriptionRequestapplication/json
Response
Returns the subscription response (which contains the subscription state).
codetypemedia typesdescription
200Subscriptionapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Create a subscription to all events of the telephony, eventSummary event packages, for user userA.

[+] : 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.

PUT/subscriptions
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
parametertypedescription
AlcUserIdstringThe user framework session Identifier, received as a cookie.
body parameter
typemedia typesdescription
Filterapplication/json
The filter to update. Filter
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

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

/subscriptions/{subscriptionId}

Methods
DELETE/subscriptions/{subscriptionId}
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
parametertypedescription
subscriptionIdstringThe identifier of the subscription.
cookie parameters
parametertypedescription
AlcUserIdstringThe user framework session Identifier, received as a cookie.
Response
The result code.
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
Examples

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

Representations

boolean
'boolean' is a data type, having two values (true and false).
Filter
High level container of event selector.
NameTypeCardinalityDescription
selectorsSelector[0..*]List of selectors.
[+] : JSON Example
Associated method :
int
'int' is a 32-bit number (-2147483648 to 2147483647).
NotificationFormat
Defines which standard will be used to format event.
ValueDescription
JSONJSON event format.
NotificationMode
The method used to notify event.
ValueDescription
CHUNKHTTP 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.
Selector
A selector is a filter applied to an event. The attributes of an event must match all the criteria of the selector to be sent to the subscriber.
NameTypeCardinalityDescription
idsstring[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).
namesstring[1..*]The selector specifies that all events must match this attribute.
The content of this field must match the name of events or one of the event packages, as listed in Subscription overview.
The name can't be empty.
[+] : JSON Example
string
'string' represents character strings.
Subscription
Contains the status returned by the server on a subscription request.
NameTypeCardinalityDefaultDescription
subscriptionIdstring[0..1]The identifier of the subscription, if this one has been accepted.
messagestring[0..1]Contains a relevant message, especially in case of error or failure.
publicPollingUrlstring[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).
privatePollingUrlstring[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).
statusSubscriptionState[1]Status of the subscription returned by the server.
modeNotificationMode[0..1]CHUNKCopy of the NotificationMode of the request.
formatNotificationFormat[0..1]JSONCopy of the NotificationFormat of the request.
[+] : JSON Example
Associated method :
SubscriptionRequest
Contains all information needed for subscription to event notification.
NameTypeCardinalityDefaultDescription
notificationUrlstring[0..1]

Reserved: DO NOT USE.

filterFilter[0..1]List of selector used to filter events.
modeNotificationMode[0..1]CHUNKThe notification mode to be used for sending events.
formatNotificationFormat[0..1]JSONThe format to be used by notified events.
sessionIdstring[0..1]

Reserved: DO NOT USE.

subscriptionIdstring[0..1]The subscription identifier
tokenstring[0..1]The token identifier
versionstring[1]The version of the events the user wants to subscribe to.
timeoutint[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.

keepaliveint[0..1]0Value, 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.
initboolean[0..1]true

Reserved: DO NOT USE.

[+] : JSON Example
Associated method :
SubscriptionState
Defines the response status of the server on a subscription request.
ValueDescription
UNKNOWNSubscription state is unknown.
ACCEPTEDFull subscription has been accepted.
REFUSEDThe subscription has been refused.

Call control

Resources summary

ResourceMethodDescription
/telephony/basicCallPOSTInitiates a call to another user (the callee).
/telephony/basicCall/answerPOSTResponds to the incoming ringing call.
/telephony/basicCall/dropmePOSTExits 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/callsGETGet information on all the calls in progress.
POSTInitiates a new call to another user (the callee).
/telephony/calls/{callRef}GETReturns a description of a call.
DELETEHangs on an active call, all the parties are released.
/telephony/calls/{callRef}/alternatePOSTPuts on hold the active call and retrieve a call that has been previously put in hold.
/telephony/calls/{callRef}/answerPOSTResponds to an incoming ringing call.
/telephony/calls/{callRef}/attachdataPOST(Standard user ONLY) Associates data with an outgoing call, following a previously established external call.
/telephony/calls/{callRef}/blindtransferPOSTTransfers a specified active call to another user, without knowing if this user will answer and without keeping control on this call.
/telephony/calls/{callRef}/callbackPOST(Standard user ONLY) Requests for call back during a call.
/telephony/calls/{callRef}/deviceLegsGETReturns the legs involved in the call
/telephony/calls/{callRef}/deviceLegs/{legId}GETReturns the leg whose Id is legId
POSTTranslates the call from a user device to another device.
/telephony/calls/{callRef}/dropmePOSTExits 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}/holdPOSTHolds a specified active call.
/telephony/calls/{callRef}/mergePOSTMakes a n-party conference with a specified active call and a specified held call.
/telephony/calls/{callRef}/overflowToVoiceMailPOSTRedirects an outgoing ringing call to the voice mail of the called user.
/telephony/calls/{callRef}/parkPOST(Standard user ONLY) Park a specified active call to a target device.
/telephony/calls/{callRef}/participantsGETReturns the list of participants in a call.
POST(Multimedia user ONLY) Adds a participant into an active call.
/telephony/calls/{callRef}/participants/{participantId}GETReturns information about a participant in a call.
DELETEDrops 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}/recordingPOSTStarts, stops, pauses or resumes the recording of a call.
/telephony/calls/{callRef}/redirectPOSTRedirects an incoming ringing call to another user or number, instead of responding to it.
/telephony/calls/{callRef}/retrievePOSTRetrieves a call that has been previously put in hold.
/telephony/calls/{callRef}/sendDtmfPOST(Standard user ONLY) Sends DTMF in an active call.
/telephony/calls/{callRef}/transferPOSTTransfers a specified active call to a specified held call.
/telephony/devicesGETGets states of all user devices
/telephony/devices/{deviceId}GETGets a user device state
/telephony/devices/{deviceId}/mute/{mute}POSTActivate/deactivate ringing of a device
/telephony/devices/{deviceId}/pickupPOSTPicks up an incoming call on another user.
/telephony/devices/{deviceId}/unparkPOST(Standard user ONLY) UnPark a call from a target device.
/telephony/incomingCallbacksGET(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/canonicalGET

Transforms the phone number into canonical.

/telephony/numbering/dialableGET

Transforms a phone number into a dialable number.

/telephony/outgoingCallbacksPOST(Standard user ONLY) Requests for call back from an idle device.
/telephony/stateGETAsks for the user telephonic state and capabilities.

Notifications summary

NotificationDescription
OnCallCreatedThis notification indicates that a new call has been created.
OnCallModifiedThis notification indicates that an existing call has been modified.
OnCallRemovedThis notification indicates that a call have been removed (hang up, transfer...).
OnDeviceMuteFailedThis notification indicates that a mute request failed.
OnDeviceMuteSuccessThis notification indicates that a mute request was successful.
OnDeviceStateModifiedThis notification indicates that device's state have been modified.
OnUserStateModifiedThis notification indicates that user's state have been modified (FREE, BUSY ...).

Resources

/telephony/basicCall

Methods
POST/telephony/basicCall
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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
MakeBasicCallRequestapplication/json
MakeBasicCallRequest
Response
codetypemedia typesdescription
201stringapplication/json
CREATED
204application/json
No Content Only for a call from a connected set which is not associated to an OpenTouch user
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Initiates a call to another user (the callee)

[+] : Initiates a call from any connected set which is not associated to an OpenTouch user.

Associated notifications

/telephony/basicCall/answer

Methods
POST/telephony/basicCall/answer
Responds to the incoming ringing call.
Licenses
The license TELEPHONY_BASIC or TELEPHONY_ADVANCED is required.
Request
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
AnswerRequestapplication/json
AnswerRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/basicCall/dropme

Methods
POST/telephony/basicCall/dropme
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
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/calls

Methods
GET/telephony/calls
Get information on all the calls in progress.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Callsapplication/json
OK
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
POST/telephony/calls
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
parametertypedescription
loginNamestring

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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
MakeCallRequestapplication/json
MakeCallRequest
Response
codetypemedia typesdescription
201stringapplication/json
CREATED
204application/json
No Content Only for a call from a connected set which is not associated to an OpenTouch user
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Initiates a call to another user (the callee)

[+] : Initiates a Private call.

[+] : Initiates a Business call.

[+] : Initiates a call from any connected set which is not associated to an OpenTouch user.

Associated notifications

/telephony/calls/{callRef}

Methods
GET/telephony/calls/{callRef}
Returns a description of a call.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callRefstringCall reference.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Callapplication/json
OK
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable
DELETE/telephony/calls/{callRef}
Hangs on an active call, all the parties are released.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callRefstringCall reference.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/calls/{callRef}/alternate

Methods
POST/telephony/calls/{callRef}/alternate
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
parametertypedescription
callRefstringreference of the held call.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
AlternateRequestapplication/json
AlternateRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/calls/{callRef}/answer

Methods
POST/telephony/calls/{callRef}/answer
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
parametertypedescription
callRefstringCall reference.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
AnswerRequestapplication/json
AnswerRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/calls/{callRef}/attachdata

Methods
POST/telephony/calls/{callRef}/attachdata
(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
parametertypedescription
callRefstringCall reference.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
SendAssociatedDataRequestapplication/json
SendAssociatedDataRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/telephony/calls/{callRef}/blindtransfer

Methods
POST/telephony/calls/{callRef}/blindtransfer
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
parametertypedescription
callRefstringReference of the active call.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
BlindTransferRequestapplication/json
BlindTransferRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/calls/{callRef}/callback

Methods
POST/telephony/calls/{callRef}/callback
(Standard user ONLY) Requests for call back during a call.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callRefstringReference of the active call.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/telephony/calls/{callRef}/deviceLegs

Methods
GET/telephony/calls/{callRef}/deviceLegs
Returns the legs involved in the call
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callRefstringCall reference.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Legsapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable

/telephony/calls/{callRef}/deviceLegs/{legId}

Methods
GET/telephony/calls/{callRef}/deviceLegs/{legId}
Returns the leg whose Id is legId
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callRefstringCall reference.
legIdstringLeg reference
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Legapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable
POST/telephony/calls/{callRef}/deviceLegs/{legId}
Translates the call from a user device to another device.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callRefstringCall reference.
legIdstringLeg reference
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
SwitchDeviceRequestapplication/json
SwitchDeviceRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/calls/{callRef}/dropme

Methods
POST/telephony/calls/{callRef}/dropme
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
parametertypedescription
callRefstringCall reference.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/calls/{callRef}/hold

Methods
POST/telephony/calls/{callRef}/hold
Holds a specified active call.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callRefstringCall reference.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
HoldRequestapplication/json
HoldRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/calls/{callRef}/merge

Methods
POST/telephony/calls/{callRef}/merge
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
parametertypedescription
callRefstringReference of the active call.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
MergeRequestapplication/json
MergeRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/calls/{callRef}/overflowToVoiceMail

Methods
POST/telephony/calls/{callRef}/overflowToVoiceMail
Redirects an outgoing ringing call to the voice mail of the called user.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callRefstringCall reference.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/calls/{callRef}/park

Methods
POST/telephony/calls/{callRef}/park
(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
parametertypedescription
callRefstringReference of the active call to park.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
ParkRequestapplication/json
ParkRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/calls/{callRef}/participants

Methods
GET/telephony/calls/{callRef}/participants
Returns the list of participants in a call.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callRefstringCall reference.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Participantsapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable
POST/telephony/calls/{callRef}/participants
(Multimedia user ONLY) Adds a participant into an active call.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callRefstringCall reference.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
AddParticipantRequestapplication/json
AddParticipantRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications
OnCallModified, OnParticipantAdded, OnParticipantModified

/telephony/calls/{callRef}/participants/{participantId}

Methods
GET/telephony/calls/{callRef}/participants/{participantId}
Returns information about a participant in a call.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callRefstringCall reference.
participantIdstringReference of the participant
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Participantapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable
DELETE/telephony/calls/{callRef}/participants/{participantId}
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
parametertypedescription
callRefstringCall reference.
participantIdstringReference of the participant
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/calls/{callRef}/recording

Methods
POST/telephony/calls/{callRef}/recording
Starts, stops, pauses or resumes the recording of a call.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callRefstringReference of the active call.
query parameters
parametertypedescription
loginNamestringLogin 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.
actionstringMandatory parameter. Possible values are start, stop, (Standard user ONLY) pause, (Standard user ONLY) resume.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/calls/{callRef}/redirect

Methods
POST/telephony/calls/{callRef}/redirect
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
parametertypedescription
callRefstringCall reference.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
RedirectRequestapplication/json
RedirectRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Redirect an incoming ringing call to DVA

Associated notifications

/telephony/calls/{callRef}/retrieve

Methods
POST/telephony/calls/{callRef}/retrieve
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
parametertypedescription
callRefstringCall reference.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
RetrieveRequestapplication/json
RetrieveRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/calls/{callRef}/sendDtmf

Methods
POST/telephony/calls/{callRef}/sendDtmf
(Standard user ONLY) Sends DTMF in an active call.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callRefstringCall reference.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
SendDtmfRequestapplication/json
SendDtmfRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable

/telephony/calls/{callRef}/transfer

Methods
POST/telephony/calls/{callRef}/transfer
Transfers a specified active call to a specified held call.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callRefstringReference of the active call
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
TransferRequestapplication/json
TransferRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/devices

Methods
GET/telephony/devices
Gets states of all user devices
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200DeviceStatesapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable

/telephony/devices/{deviceId}

Methods
GET/telephony/devices/{deviceId}
Gets a user device state
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
deviceIdstringDevice 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
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200DeviceStateapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable

/telephony/devices/{deviceId}/mute/{mute}

Methods
POST/telephony/devices/{deviceId}/mute/{mute}
Activate/deactivate ringing of a device
History
Since version 2.5
Request
path parameters
parametertypedescription
deviceIdstringdevice to mute/unmute
mutestring`true` to mute, `false` to unmute
cookie parameters
parametertypedescription
AlcUserIdstring
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/devices/{deviceId}/pickup

Methods
POST/telephony/devices/{deviceId}/pickup
Picks up an incoming call on another user.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
deviceIdstringDevice 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
PickupRequestapplication/json
PickupRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/devices/{deviceId}/unpark

Methods
POST/telephony/devices/{deviceId}/unpark
(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
parametertypedescription
deviceIdstringdevice from where the unpark request is requested.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
UnParkRequestapplication/json
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/telephony/incomingCallbacks

Methods
GET/telephony/incomingCallbacks
(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
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Callbacksapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
DELETE/telephony/incomingCallbacks
(Standard user ONLY) Deletes all callback requests.
History
Since version 2.1.1
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/telephony/incomingCallbacks/{callbackId}

Methods
DELETE/telephony/incomingCallbacks/{callbackId}
(Standard user ONLY) Deletes a callback request.
History
Since version 2.1.1
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callbackIdstringidentifier of the callback to delete
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/telephony/numbering/canonical

Methods
GET/telephony/numbering/canonical

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
parametertypedescription
loginNamestringLogin 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.
phoneNumberstringThe phone number to transform.
Note that a phone number is considered valid if it contains numbers potentially separated by any of the following characters: " ", "(", ")", "-", ".","/".
isPrefixIncludedbooleanSpecifies 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).
resultPatternstringThe 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Numberingapplication/json
OK
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/telephony/numbering/dialable

Methods
GET/telephony/numbering/dialable

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
parametertypedescription
loginNamestringLogin 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.
phoneNumberstringThe phone number to transform
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Numberingapplication/json
OK
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/telephony/outgoingCallbacks

Methods
POST/telephony/outgoingCallbacks
(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
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
CallbackRequestapplication/json
call back information
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/telephony/state

Methods
GET/telephony/state
Asks for the user telephonic state and capabilities.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200TelephonicStateapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

Representations

AddParticipantRequest
Request to add a participant.
NameTypeCardinalityDescription
calleestring[1]Called phone number.
anonymousboolean[0..1]Anonymous call (secret identity). This parameter is optional. If it is omitted, anonymous is not set for this call.
bypassboolean[0..1]Bypass routing rules and presentation rules according to the callee. This parameter is optional. If it is omitted, bypass is not done.
[+] : JSON Example
Associated method :
AlternateRequest
Request to switch between an active call and a held call.
NameTypeCardinalityDescription
deviceIdstring[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.
[+] : JSON Example
Associated method :
AnswerRequest
Request to answer a ringing incoming call.
NameTypeCardinalityDescription
deviceIdstring[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.
[+] : JSON Example
Associated methods :
BlindTransferRequest
Request to transfer an incoming call.
NameTypeCardinalityDescription
transferTostring[1]Phone number to which the call is transferred.
anonymousboolean[0..1]Anonymous call (secret identity). This parameter is optional. If it is omitted, anonymous is not set for this call.
bypassboolean[0..1]Bypass routing rules and presentation rules according to the callee. This parameter is optional. If it is omitted, bypass is not done.
[+] : JSON Example
Associated method :
boolean
'boolean' is a data type, having two values (true and false).
Call
Describes an user's call.
NameTypeCardinalityDescription
callRefstring[1]Reference of the call.
callDataCallData[0..1]Call data.
legsLeg[0..*]User's devices.
participantsParticipant[0..*]Participants.
[+] : JSON Example
Associated method :
Callback
Describes a callback.
NameTypeCardinalityDescription
callbackIdstring[1]Callback identifier
partyInfoPartyInfo[1]Participant identity card.
[+] : JSON Example
CallbackRequest
Callback Sender Message request data.
NameTypeCardinalityDescription
calleestring[1]Callee phone number of the called party for which a call back is requested.
[+] : JSON Example
Associated method :
Callbacks
Container for the callbacks.
NameTypeCardinalityDescription
callbacksCallback[0..*]List of callbacks
[+] : JSON Example
Associated method :
CallCapabilities
Describes the capabilities available on a call : the action that can be carried out on the call according to its state.
NameTypeCardinalityDescription
addMediasMediaCapability[0..*]Capability to add a media.
addDeviceboolean[0..1]Capability to add a participant or a user's device to this call.
addParticipantboolean[0..1]Capability to add a participant.
intrudedboolean[0..1]Capability to intrude this call by another user.
transferboolean[0..1]Capability to transfer this call with another one.
blindTransferboolean[0..1]Capability to blind transfer this call to an user, device, ...
mergeboolean[0..1]Capability to merge this call with another one.
redirectboolean[0..1]Capability to redirect this call to another user, device, ...
pickedUpboolean[0..1]Capability to pick up this call by another user.
redirectToVoiceMailboolean[0..1]Capability to redirect this call to the voice mail.
redirectToDVAboolean[0..1]Capability to redirect this call to the DVA.
overflowToVoiceMailboolean[0..1]Capability to overflow to the voice mail of the called user.
dropMeboolean[0..1]Capability to drop me from this call.
terminateboolean[0..1]Capability to terminate this call: call termiated on all users.
rejectboolean[0..1]Capability to reject this call.
callBackboolean[0..1]Capability to invoke a call back.
parkboolean[0..1]

Specifies whether the call can be parked.

Available only for Standard users.

startRecordboolean[0..1]Capability to start the record of the call.
stopRecordboolean[0..1]Capability to stop the record of the call.
pauseRecordboolean[0..1]Capability to pause the record of the call.
resumeRecordboolean[0..1]Capability to resume the record of the call.
dropParticipantboolean[0..1]Capability to drop a participant.
muteParticipantboolean[0..1]Capability to mute/unMute a particpant.

This capabilty is not available in this release.

holdParticipantboolean[0..1]Capability to hold/retrieve a participant.

This capabilty is not available in this release.

[+] : JSON Example
CallCause
Lists the different call causes.
ValueDescription
ABANDONEDCaller in a two-party call has disconnected before the call was answered.
ALL_TRUNK_BUSYThe call is receiving the network congestion tone.
BUSYThe call is receiving the busy tone.
CLEAREDOne party in a two-party call has disconnected after the call was answered.
CONFERENCEDThis is a multi-party call.
INVALID_NUMBERThe call is receiving the invalid number tone.
FORWARDEDThe call has been forwarded.
PICKED_UPThe call has been picked up.
REDIRECTEDThe call has been redirected.
TRANSFERREDThis is a transferred call.
UNKNOWNUnknown cause.
PICKED_UP_TANDEMPicked up tandem.
CALL_BACK

Since version 2.2.1

The call is a call back.
CallData
Describes data associated to a call.
NameTypeCardinalityDescription
initialCalledPartyInfo[0..1]Initial user called for this call.
deviceCallboolean[0..1]If true it's a device call else if not specified or false it's a user call.
anonymousboolean[0..1]If true it's a anonymous call.
callUUIDstring[0..1]CallUUID associated to this call (used to correlate RTSM events with SIP events for multimedia users only).
stateMediaState[0..1]Call state (computed from media state).
recordStateRecordState[0..1]Record state (only if recording is active).
tagsTag[0..*]Tags associated to this call.
capabilitiesCallCapabilities[0..1]Capabilities available on this call.
[+] : JSON Example
Calls
Container for the calls.
NameTypeCardinalityDescription
callsCall[0..*]List of call
[+] : JSON Example
Associated method :
DeviceCapabilities
Describes an user's device capabilities.
NameTypeCardinalityDescription
deviceIdstring[1]Device phone number.
makeCallboolean[0..1]Specifies whether a new call can be initiated.
makeBusinessCallboolean[0..1]

Specifies whether a business call can be initiated.

Available only for standard users.

makePrivateCallboolean[0..1]

Specifies whether a personal call can be initiated.

Available only for standard users.

unParkCallboolean[0..1]

Specifies whether a call can be an unparked call.

Available only for standard users.

[+] : JSON Example
DeviceState
Describes a user's device state.
NameTypeCardinalityDescription
deviceIdstring[1]Device phone number.
stateOperationalState[1]Device state.
mutableboolean[1]

Since version 2.5

Indicates whether a device can be muted or not
mutedboolean[1]

Since version 2.5

Indicates whether a device is muted or not
[+] : JSON Example
Associated method :
DeviceStates
Container for device state.
NameTypeCardinalityDescription
deviceStatesDeviceState[0..*]List of DeviceState
[+] : JSON Example
Associated method :
hexBinary
'hexBinary' is a built-in datatype that represents binary data encoded in hexadecimal format.
HoldRequest
Request to put an active call on hold.
NameTypeCardinalityDescription
deviceIdstring[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.
[+] : JSON Example
Associated method :
Identifier
Key information to help retrieving a participant.
NameTypeCardinalityDescription
loginNamestring[0..1]Login name.
phoneNumberstring[0..1]Company phone number.
instantMessagingIdstring[0..1]Instant messaging identity.
[+] : JSON Example
Leg
Describes a leg. A leg represents the user's device involved in a call for a dedicated media (audio or video).
NameTypeCardinalityDescription
deviceIdstring[1]Device phone number.
mediaMediaType[1]Media type.
stateMediaState[0..1]Media state.
capabilitiesLegCapabilities[0..1]Capabilities for this leg.
[+] : JSON Example
Associated method :
LegCapabilities
Describes the capabilities of a leg : The action that can be carried out on the leg according to its state.
NameTypeCardinalityDescription
answerboolean[0..1]Capability to answer to an incoming call.
dropboolean[0..1]Capability to drop this media device.
holdboolean[0..1]Capability to hold this call in order to retrieve it later.
retrieveboolean[0..1]Capability to retrieve an hold call.
reconnectboolean[0..1]Capability to retrieve an hold call and releasing the current active call.
muteboolean[0..1]Capability to enable mute for this leg.
unMuteboolean[0..1]Capability to disable mute for this device.
sendDtmfboolean[0..1]Capability to send DTMF codes for this leg.
switchDeviceboolean[0..1]Capability to switch this device to another one.
[+] : JSON Example
Legs
Container for Legs.
NameTypeCardinalityDescription
legsLeg[0..*]List of Leg.
[+] : JSON Example
Associated method :
MainType
Main participant type
ValueDescription
USERThe participant is a user of the system.
DEVICEThe participant is a device of the system.
SERVICEThe participant is a service of the system.
EXTERNALThe participant is not a user of the system.
UNKNOWNThe main participant type is unknown.
MakeBasicCallRequest
Request to initiate a new call.
NameTypeCardinality*1*2Description
deviceIdstring[1]XXDevice 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.
calleestring[1]XXCalled phone number.
autoAnswerboolean[0..1]XAutomatic 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.

[+] : JSON Example
Associated method :
MakeCallRequest
Request to initiate a new call.
NameTypeCardinality*1*2*3*4Description
deviceIdstring[0..1]XXXXDevice 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)
calleestring[1]XXXXCalled phone number.
autoAnswerboolean[0..1]XAutomatic 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.
bypassboolean[0..1]X
associatedDatahexBinary[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
pinstring[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
secretCodestring[0..1]X (Standard user ONLY) Secret code (Mandatory when making a Private Call). Don't use in conjonction with associatedData or businessCode parameter
businessCodestring[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.

[+] : JSON Example
Associated method :
MediaCapability
Describes a media capabilty.
NameTypeCardinalityDescription
typeMediaType[1]Type of media (audio, video, ...).
[+] : JSON Example
MediaState
Lists the different media states.
ValueDescription
UNKNOWNUnknown media state.
OFF_HOOKThe device is off-hook.
IDLECall is in idle state.
RELEASINGCall release is in progress.
DIALINGAn attempt to make a call is in progress.
HELDThe call has been placed on hold.
RINGING_INCOMINGThe incoming call is ringing.
RINGING_OUTGOINGThe outgoing call is ringing.
ACTIVEThe call is active (means in conversation).
MediaType
Lists the different type of medias.
ValueDescription
AUDIOAudio media.
VIDEOVideo media.
IMInstant message media.
MergeRequest
Request to merge two calls, the active one and the held one.
NameTypeCardinalityDescription
heldCallRefstring[1]Reference of the held call.
[+] : JSON Example
Associated method :
Numbering
Describes numbering response. Contains either a dialable or canonical phone number, depending on the request.
NameTypeCardinalityDescription
dialablestring[0..1]The dialable phone number, when requested.
canonicalstring[0..1]The canonical phone number, when requested.
[+] : JSON Example
Associated methods :
OnCallCreated
This notification indicates that a new call has been created.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnCallCreated'
loginNamestring[1]Login name of the user (identifier which can be used for filtering).
callRefstring[1]Reference of the call.
causeCallCause[0..1]Cause of the event.
callDataCallData[0..1]Call data.
initiatorstring[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.
legsLeg[0..*]Legs associated to this call.
participantsParticipant[0..*]Participants associated to this call.
deviceCapabilitiesDeviceCapabilities[0..*]Devices capabilities (if not specified, it means there is no modification).
[+] : JSON Example
Associated methods :
OnCallModified
This notification indicates that an existing call has been modified.

Modification of a call can be triggered for various reason: changes on legs, on participants, changes on states, ...
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnCallModified'
loginNamestring[1]Login name of the user (identifier which can be used for filtering).
callRefstring[1]Reference of the call.
causeCallCause[0..1]Cause of the event.
previousCallRefstring[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)
replacedByCallRefstring[0..1]This call reference appears when a call is released, the replacedByCallRef if present indicates that the "callRef" is replaced by this one.
callDataCallData[0..1]Call data modified (if not specified, it means there is no modification).
modifiedLegsLeg[0..*]Legs modified (if not specified, it means there is no modification).
addedLegsLeg[0..*]Legs added (if not specified, it means there is no added leg).
removedLegsLeg[0..*]Legs removed (if not specified, it means there is no removed leg).
modifiedParticipantsParticipant[0..*]Participants modified (if not specified, it means there is no modification).
addedParticipantsParticipant[0..*]Participants added (if not specified, it means there is no added participant).
removedParticipantIdsstring[0..*]Participants removed (if not specified, it means there is no removed participant).
deviceCapabilitiesDeviceCapabilities[0..*]Devices capabilities modified (if not specified, it means there is no modification).
[+] : JSON Example
Associated methods :

OnCallRemoved
This notification indicates that a call have been removed (hang up, transfer...).
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnCallRemoved'
loginNamestring[1]Login name of the user (identifier which can be used for filtering).
callRefstring[1]Reference of the call.
causeCallCause[0..1]Cause of the event.
newDestinationstring[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.
deviceCapabilitiesDeviceCapabilities[0..*]Devices capabilities (if not specified, it means there is no modification).
[+] : JSON Example
Associated methods :
OnDeviceMuteFailed
This notification indicates that a mute request failed.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnDeviceMuteFailed'
loginNamestring[1]Login name of a user
deviceIdstring[1]Directory number of a device
nativeCodestring[1]Native code of an error
infostring[1]Information about an error
[+] : JSON Example
Associated method :
OnDeviceMuteSuccess
This notification indicates that a mute request was successful.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnDeviceMuteSuccess'
loginNamestring[1]Login name of a user
deviceIdstring[1]Directory number of a device
muteboolean[1]Mute state of a device (true/false)
[+] : JSON Example
Associated method :
OnDeviceStateModified
This notification indicates that device's state have been modified.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnDeviceStateModified'
loginNamestring[1]Login name of the user (identifier which can be used for filtering).
deviceStatesDeviceState[1..*]Device state modified.
[+] : JSON Example
OnUserStateModified
This notification indicates that user's state have been modified (FREE, BUSY ...).
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnUserStateModified'
loginNamestring[1]Login name of the user (identifier which can be used for filtering).
stateUserState[1]User state.
[+] : JSON Example
Associated methods :
OperationalState
List the different operational states.
ValueDescription
IN_SERVICEOperational state is in service.
OUT_OF_SERVICEOperational state is out of service.
UNKNOWNOperational state is unknown.
ParkRequest
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
NameTypeCardinalityDescription
parkTostring[0..1]Phone number device where to park the call .
[+] : JSON Example
Associated method :
Participant
Detail about a kind of participant.
NameTypeCardinalityDescription
participantIdstring[1]Participant identifier (Should not be displayed).
identityPartyInfo[0..1]Participant identity card.
anonymousboolean[0..1]Participant identity is secret
undroppableboolean[0..1]If true this participant can not be dropped.
stateMediaState[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.
mediasMediaType[0..*]Medias involved for this participant.
mediaCapabilitiesMediaCapability[0..*]Media capabilities of the participant.
[+] : JSON Example
Associated method :
Participants
Container for Participants.
NameTypeCardinalityDescription
participantsParticipant[0..*]Container for Participants.
[+] : JSON Example
Associated method :
ParticipantType
Participant type description
NameTypeCardinalityDescription
mainMainType[1]Gives the main type of the participant: "user", "device", ...
subTypestring[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
PartyInfo
Full description of a party involved in a call log record.
NameTypeCardinalityDescription
idIdentifier[1]Identifier of the party.
firstNamestring[0..1]First name.
lastNamestring[0..1]Last name.
displayNamestring[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
vcardUrlstring[0..1]

DEPRECATED: use vcardPath instead

vcardPathstring[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

typeParticipantType[0..1]Type of participant.
[+] : JSON Example
PickupRequest
Request to pickup a call.
NameTypeCardinalityDescription
otherCallRefstring[0..1]Reference of the call to pickup (on the remote user).
otherPhoneNumberstring[1]Phone number on which the call is to pickup.
autoAnswerboolean[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).

[+] : JSON Example
Associated method :
RecordState
Lists the different state when recording.
ValueDescription
PAUSEDRecording is paused.
RECORDINGRecording is in progress.
RedirectRequest
Request to redirect a call.
NameTypeCardinalityDescription
redirectTostring[1]Phone number of the target of the redirection
anonymousboolean[0..1]Anonymous call (secret identity). This parameter is optional. If it is omitted, anonymous is not set for this call.
bypassboolean[0..1]
[+] : JSON Example
Associated method :
RetrieveRequest
[Tel]: Request to redirect a call.
NameTypeCardinalityDescription
deviceIdstring[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.
[+] : JSON Example
Associated method :
SendAssociatedDataRequest
Request to send associated data.
NameTypeCardinalityDescription
deviceIdstring[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.
associatedDatahexBinary[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.
[+] : JSON Example
Associated method :
SendDtmfRequest
Request to send DTMF
NameTypeCardinalityDescription
deviceIdstring[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.
numberstring[1]DTMF codes.
[+] : JSON Example
Associated method :
string
'string' represents character strings.
SwitchDeviceRequest
Request to switch between two devices.
NameTypeCardinalityDescription
otherDeviceIdstring[1]Device phone number on which to switch.
[+] : JSON Example
Associated method :
Tag
Describes a Tag (a defined name and a value).
NameTypeCardinalityDescription
namestring[1]Tag name.
valuestring[0..1]Tag value.
visibilitiesstring[0..*]Visibility of this tag : list of login name.
[+] : JSON Example
TelephonicState
Snapshot of the user's telephonic state.
NameTypeCardinalityDescription
callsCall[0..*]Gives the list of current calls.
deviceCapabilitiesDeviceCapabilities[0..*]Gives the list of device's capabilities.
[+] : JSON Example
Associated method :
TransferRequest
Request to transfer the held call to a new destination.
NameTypeCardinalityDescription
heldCallRefstring[1]Reference of the held call.
[+] : JSON Example
Associated method :
UnParkRequest
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.
NameTypeCardinalityDescription
unParkFromstring[0..1]Phone number of the device where the call has been parked.
[+] : JSON Example
Associated method :
UserState
Lists the different types of user state.
ValueDescription
FREEUser is free.
BUSYUser is busy.
UNKNOWNThe user state is unknown.

Directory search

Presentation

The directory resource is used to search for a contact in several directories:

Operations can be invoked using:

Resources summary

ResourceMethodDescription
/directory/directoriesGETRetrieves the list of the available directories.
/directory/searchPOSTInitiates a search
GETGets the next available results for the current search.
DELETEDeletes (stops) search query

Resources

/directory/directories

Methods
GET/directory/directories
Retrieves the list of the available directories.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringOptional login name of the user for whom an administrator wants to invoke the request.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Directoriesapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Retrieves the list of the available directories

/directory/search

Methods
POST/directory/search
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
parametertypedescription
loginNamestringOptional login name of the user for whom an administrator wants to invoke the request.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
SearchRequestapplication/json
SearchRequest
Response
codetypemedia typesdescription
201stringapplication/json
CREATED
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Initiates a search

GET/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
parametertypedescription
loginNamestringOptional login name of the user for whom an administrator wants to invoke the request.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200SearchResultapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Gets the next available results

[+] : Gets the next available results

DELETE/directory/search
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
parametertypedescription
loginNamestringOptional login name of the user for whom an administrator wants to invoke the request.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Deletes search query

Representations

Attribute
Lists the different types of attributes.
ValueDescription
lastNameLast name.
firstNameFirst 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.

id.emailEmail.
id.loginNameLogin name.
Criterion
Criterion descriptor.
NameTypeCardinalityDescription
fieldAttribute[0..1]Field name.
operationOperation[1]Operation.
operandstring[1]Operand.
Criterion[1..*]

[+] : JSON Example 1

[+] : JSON Example 2

[+] : JSON Example 3

Directories
List of directory objects
NameTypeCardinalityDescription
directoriesDirectory[0..*]List of directory objects.
[+] : JSON Example
Associated method :
Directory
Description of a directory
NameTypeCardinalityDescription
idstring[1]Directory identifier.
labelstring[1]Directory label.
typeDirectoryType[1]Directory type.
[+] : JSON Example
DirectoryType
The different types of supported directories.
ValueDescription
CALLSERVERPhone book of the call server.
LDAPLDAP directory.
OT_SYSTEM_DIRECTORYOT internal system directory.
MERGED_DIRECTORYMerged phone book: OT system is configured to merge all or part of defined phone books to a unique phone book.
UNKNOWNUnknown type.
Identifier
Description of Identifier
NameTypeCardinalityDescription
loginNamestring[0..1]Login name
instantMessagingIdstring[0..1]Instant messaging identifier
emailstring[0..1]Email
phoneNumberstring[0..1]Phone number
[+] : JSON Example
int
'int' is a 32-bit number (-2147483648 to 2147483647).
Operation
The types of operation
ValueDescription
OROR operation.
ANDAND operation.
EQUAL_IGNORE_CASEEQUAL_IGNORE operation.
BEGIN_WITHBEGIN_WITH operation.
CONTAINCONTAIN operation.
END_WITHEND_WITH operation.
PartyInfo
Description of PartyInfo
NameTypeCardinalityDescription
idIdentifier[0..1]PartyInfo identifier object
firstNamestring[0..1]First name
lastNamestring[0..1]Last name
vcardPathstring[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

[+] : JSON Example
ResultCode
This code is returned each time you try to retrieve responses after a search has been started (getNextResults operation).
ValueDescription
OKResponses are provided this time. You will have to continue to invoke getNextResults periodically to get the next response.
NOKNo responses this time. You will have to continue to invoke getNextResults periodically to get the next response.
FINISHSearch is finished. You no longer need to invoke getNextResults, there are no more responses.
TIMEOUTSearch is ended for timeout reason. You no longer need to invoke getNextResults, there are no more responses.
ResultElement
Gives a result which matches the criterion given in search operation. The records are obtained by periodically invoking the getNextResults operation.
NameTypeCardinalityDescription
directorySourcestring[1]The directory identifier from which the result has been found.
contactsPartyInfo[0..*]Array of ContactDTO objects
[+] : JSON Example
SearchRequest
This element is used to start an advanced search.
NameTypeCardinalityDescription
directoriesstring[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.
limitint[0..1]

Since version 2.0.2

Maximum number of results. Default value is 100. The range of supported values is [1 .. 100].
filterCriterion[1]searching criterion.
[+] : JSON Example
Associated method :
SearchResult
The result of a search
NameTypeCardinalityDescription
resultCodeResultCode[0..1]Search result status code.
resultElementsResultElement[0..*]Search result elements.
[+] : JSON Example
Associated method :
string
'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

ResourceMethodDescription
/routingGETAllows an application to know what the user is allowed to do.
POSTSets the specified routes and the currentDeviceId .
/routing/overflowroutePOSTSets the specified overflow routes.
DELETECancels the overflow routes.
/routing/profilesGETRetrieves the list of existing routing profiles.
DELETEDeletes all non default routing profiles.
PUTCreates a personal routing profile.
/routing/profiles/{profileId}GETRetrieves the specified routing profile.
DELETEDeletes non default specified routing profile.
PUTActivates the specified routing profile.
POSTUpdates an existing routing profile.
/routing/stateGETRetrieves the routing context state.

Notifications summary

NotificationDescription
OnRoutingManagementFailedThis notification indicates that a routing request has failed.
OnRoutingProfilesChangedThis notification indicate that a profile (or a set of profiles) is updated.
OnRoutingStateChangedThis notification indicate that routing state is changed.

Resources

/routing

Methods
GET/routing
Allows an application to know what the user is allowed to do.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Capabilitiesapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Get the routing capabilities of a user.

POST/routing
Sets the specified routes and the currentDeviceId .
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
SetRoutesRequestapplication/json
SetRoutesRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/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.)

[+] : Make a conditional forward (BUSY) to my voicemail for a STANDARD user. All routing profiles are automatically disabled.

[+] : Make an immediate forward for a MULTIMEDIA user to an OpenTouch user (external numbers are not authorized).

[+] : Make a conditional forward (BUSY) for a STANDARD user to an OpenTouch user (external numbers are not authorized).

[+] : Make an immediate forward for a STANDARD user to an external number.

[+] : Disable an immediate forward for a MULTIMEDIA user, in order to switch back to the previous routing state.

Associated notifications

/routing/overflowroute

Methods
POST/routing/overflowroute
Sets the specified overflow routes.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
SetOverflowRoutesRequestapplication/json
SetOverflowRoutesRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : If the user is busy, route the new calls to the voicemail.

Associated notifications
DELETE/routing/overflowroute
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
parametertypedescription
loginNamestringLogin 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.
requestIdstringthe requestId as a query parameter.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Cancels the overflow routes.

Associated notifications

/routing/profiles

Methods
GET/routing/profiles
Retrieves the list of existing routing profiles.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200RoutingStateapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/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.

DELETE/routing/profiles
Deletes all non default routing profiles.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications
PUT/routing/profiles
Creates a personal routing profile.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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.
detailsbooleanIf 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
CreateProfileRequestapplication/json
CreateProfileRequest
Response
codetypemedia typesdescription
201stringapplication/json
CREATED. The identifier of the profile is returned.
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/routing/profiles/{profileId}

Methods
GET/routing/profiles/{profileId}
Retrieves the specified routing profile.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
profileIdstringThe identifier of the profile.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Profileapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable
DELETE/routing/profiles/{profileId}
Deletes non default specified routing profile.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
profileIdstringThe identifier of the profile.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications
PUT/routing/profiles/{profileId}
Activates the specified routing profile.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
profileIdstringThe identifier of the profile.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
ApplyProfileRoutesRequestapplication/json
ApplyProfileRoutesRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications
POST/routing/profiles/{profileId}
Updates an existing routing profile.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
profileIdstringThe identifier of the profile.
query parameters
parametertypedescription
loginNamestringLogin 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.
detailsbooleanIf true, the modified profile is included in the response (200 OK). If not set (or false), returned response is 204 No Content.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
SetProfileRequestapplication/json
SetProfileRequest
Response
codetypemedia typesdescription
200Profileapplication/json
OK
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/routing/state

Methods
GET/routing/state
Retrieves the routing context state.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200RoutingStateapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Get the state of my routing, in term of presentation route, forward route and overflow route.

[+] : Get the state of my routing, in term of presentation route, forward route and overflow route.

Representations

ApplyProfileRoutesRequest
Request to apply a routing profile.
NameTypeCardinalityDescription
requestIdstring[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.

otherNumberstring[0..1]

Since version 2.1

For "OTHER" and "OTHER_AND_MOBILE" profiles only.
[+] : JSON Example
Associated method :
boolean
'boolean' is a data type, having two values (true and false).
Capabilities
Describes the routing management capabilities.
NameTypeCardinalityDescription
presentationRouteboolean[0..1]If true, the user is allowed to manage presentation routes.
forwardRouteboolean[0..1]If true, the user is allowed to manage forward routes.
overflowRouteboolean[0..1]If true, the user is allowed to manage overflow routes.
currentDeviceboolean[0..1]If true, the user is allowed to manage the device used for outbound actions.
manageProfileboolean[0..1]If true, the user is allowed to manage a profile (create, delete, update, rename).
applyProfileRoutesboolean[0..1]If true, the user is allowed to apply a profile.
maxProfilesint[0..1]Number of profiles: predefined and personal.
[+] : JSON Example
Associated method :
CreateProfileRequest
Request to create a new routing profile.
NameTypeCardinalityDescription
profileNamestring[1]The name of the profile to be created.
Only personal profiles can be renamed (name must be unique).
presentationRoutesPresentationRoute[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).

forwardRoutesForwardRoute[0..*]

List of forward routes (only one forward route can be set).

When this parameter is not provided, the forward routes are 'unselected'.

currentDeviceIdstring[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
Associated method :
Destination

Describes a destination.

NameTypeCardinalityDescription
typeDestinationType[1]Key used to identify the device or other destinations.
deviceIdstring[0..1]Filled by the system in routing state.
numberstring[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.

acceptableboolean[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.
selectedboolean[0..1]Filled by the system for predefined profiles (false by default).
Filled by the client : acceptable should be true.
informationUserInformation[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
DestinationType
Lists the different types of a destination.
ValueDescription
OFFICEDestination is office device.
MOBILEDestination is mobile device.
PCDestination is Personal Computer device.
TABLETDestination is tablet device.
VIDEODestination is video device.
HOMEDestination is home device.
OTHERDestination is other.
VOICEMAILDestination is the voice mail of the user.
USERDestination 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.
UNKNOWNUnknown destination type.
ForwardRoute

Describes a forward route.

The possible destination type for a forward route are:

  • VOICEMAIL
  • USER
  • NUMBER

NameTypeCardinalityDescription
forwardTypeForwardType[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).
destinationsDestination[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
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.
ValueDescription
BUSYIncoming calls are diverted to the destination when the phone is busy.
NO_ANSWERIncoming calls are diverted to the destination after a ringing duration.
BUSY_NO_ANSWERIncoming calls are diverted to the destination when the phone is busy or after a ringing duration.
int
'int' is a 32-bit number (-2147483648 to 2147483647).
OnRoutingManagementFailed
This notification indicates that a routing request has failed.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnRoutingManagementFailed'
loginNamestring[1]Login name of the user (identifier which can be used for filtering).
requestIdstring[0..1]Request identifier : used to correlate this event with a previous request.
resultCodeResultCode[0..1]Error code.
causestring[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
  • ...
destinationTypeDestinationType[0..1]Destination type that produce the error.
commentstring[0..1]Comment (in 'English').
[+] : JSON Example
OnRoutingProfilesChanged
This notification indicate that a profile (or a set of profiles) is updated.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnRoutingProfilesChanged'
loginNamestring[1]Login name of the user (identifier which can be used for filtering).
profilesProfile[1..*]All existing profiles.
[+] : JSON Example
Associated methods :
OnRoutingStateChanged
This notification indicate that routing state is changed.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnRoutingStateChanged'
loginNamestring[1]Login name of the user (identifier which can be used for filtering).
requestIdstring[0..1]Request identifier : used to correlate this event with a previous request.
routingStateRoutingState[1]Current routing state.
[+] : JSON Example
Associated methods :
OverflowRoute

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.

NameTypeCardinalityDescription
overflowTypeOverflowType[1]The overflow type.
destinationsDestination[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
Lists the different types of overflow
ValueDescription
BUSYIncoming calls are diverted to the destination when the phone is busy.
NO_ANSWERIncoming calls are diverted to the destination after a ringing duration.
BUSY_NO_ANSWERIncoming calls are diverted to the destination when the phone is busy or after a ringing duration.
PresentationRoute

Describes a presentation route.

The possible destination type for a presentation route are:

  • OFFICE
  • MOBILE
  • PC
  • TABLET
  • VIDEO
  • HOME
  • OTHER

NameTypeCardinalityDescription
destinationsDestination[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
Profile
Describes a routing profile.
NameTypeCardinalityDescription
idstring[1]Identifies the profile (predefined profiles : DEFAULT, with id = '0').
namestring[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.
defaultProfileboolean[0..1]This parameter is true for fall back profile.
activableboolean[0..1]Define whether the profile can be activated.
NOTE: always true for DEFAULT profile.
removableboolean[0..1]Specifies whether the profile can be removed (always false for default profile).
renameableboolean[0..1]Specifies whether the profile can be renamed (always false for default profile).
updatableboolean[0..1]Specifies whether the profile can be modified. NOTE: this filed is always false for the default profile.
presentationRoutesPresentationRoute[1..*]List of presentation (default) routes.
forwardRoutesForwardRoute[0..*]Unconditional forward routes to VOICEMAIL or USER.
currentDeviceIdstring[0..1]Specifies which device the user uses for outbound actions (such as making a call).
[+] : JSON Example
Associated methods :
Profiles
Container for profiles
NameTypeCardinalityDescription
profilesProfile[0..*]List of profiles.
[+] : JSON Example
Associated method :
ProfileSummary
Describes a routing profile summary.
NameTypeCardinalityDescription
idstring[1]Identifies the profile. The id of the default profile is '0'.
namestring[0..1]The application can use this attribute to display the profile.
The name of the default profile is 'DEFAULT'.
defaultProfileboolean[0..1]This parameter is true for default profile.
[+] : JSON Example
ResultCode
Result code returned by every operation invoked on a service.
ValueDescription
SUCCESSThe operation succeeded.
ERROR_BAD_FRAMEWORK_SESSION_IDENTIFIERThe operation failed because the given session identifier is not valid.
ERROR_INVALID_OPERATIONThe invoked operation is not valid.
ERROR_LICENSE_REQUIREDA license is required to invoke this operation.
ERROR_SERVICE_UNAVAILABLEAn internal service, needed to answer the operation, is not available.
ERROR_BAD_PARAMETER_VALUEA parameter given in the operation is not valid or is missing.
ERROR_UNAUTHORIZEDThe user is not authorized to invoke this operation.
ERROR_SERVICEAn internal service raised an error.
ERROR_UNEXPECTEDAn unexpected error has been raised.
ERROR_INCOMPLETE_PHONE_NUMBERThe phone number is incomplete.
ERROR_MAX_PROFILE_REACHEDThe maximum of profiles has been reached.
ERROR_UNKNOWN_PHONE_NUMBERThe phone number is unknown.
ERROR_UNKNOWN_PROFILEThe profile is unknown.
RoutingState
Describes the routing state.
NameTypeCardinalityDescription
appliedProfileProfileSummary[0..1]

Since version 2.1

activableProfilesProfileSummary[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).
presentationRoutesPresentationRoute[1..*]List of presentation routes.
forwardRoutesForwardRoute[0..*]List of forward routes.
overflowRoutesOverflowRoute[0..*]List of overflow routes.
currentDeviceIdstring[0..1]

Since version 2.1

Device used for outbound actions (such as making a call).
[+] : JSON Example
Associated methods :
SetOverflowRoutesRequest
Request to set the overflow routes.
NameTypeCardinalityDescription
overflowRoutesOverflowRoute[1..*]New overflow routes (only one overflow route can be set).
requestIdstring[0..1]

Since version 2.1

[+] : JSON Example
Associated method :
SetProfileRequest
Request to set a profile.
NameTypeCardinalityDescription
profileNamestring[1]The name of the profile.
Only personal profiles can be renamed (name must be unique).
presentationRoutesPresentationRoute[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).

forwardRoutesForwardRoute[0..*]

List of forward routes (only one forward route can be set).

When this parameter is not provided, the forward routes are 'unselected'.

currentDeviceIdstring[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
Associated method :
SetRoutesRequest
Request to select current routes for the user.
NameTypeCardinalityDescription
presentationRoutesPresentationRoute[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).

forwardRoutesForwardRoute[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'.

currentDeviceIdstring[0..1]

Since version 2.1

requestIdstring[0..1]

Since version 2.1

[+] : JSON Example
Associated method :
string
'string' represents character strings.
UserInformation
Describes information about an user.
NameTypeCardinalityDescription
phoneNumberstring[0..1]User phone number.
loginNamestring[0..1]User login name.
lastNamestring[0..1]User last name.
firstNamestring[0..1]User first name.
emailstring[0..1]User email.
[+] : JSON Example

Communication log

History

Since version 2.0.1

Resources summary

ResourceMethodDescription
/comlog/recordsPUTEither Acknowledge/Unacknowledge the incoming missed communication records specified by their IDs.
GETGet all the communication log records.
DELETEDelete all (or only the specified) communication log records.
/comlog/records/recordIdsGETGet the whole list of communication log record Ids.
/comlog/records/{recordId}GETGet a communication log record.
DELETEDelete a record.
/comlog/records/{recordId}/imGETGet the IM thread associated to the comLog record.

Notifications summary

NotificationDescription
OnComRecordCreatedNotification sent when a new comlog entry has been created.
OnComRecordModifiedNotification sent when one or more records have been modified.
OnComRecordsAckNotification sent when one or more unanswered comlog records have been acknowledged.
OnComRecordsDeletedNotification sent when one or more call log records have been destroyed.
OnComRecordsUnAckNotification sent when one or more unanswered comlog records have been unacknowledged.

Resources

/comlog/records

Methods
PUT/comlog/records
Either Acknowledge/Unacknowledge the incoming missed communication records specified by their IDs.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
acknowledgestringtrue to acknowledge the list of communication records, false to unacknowledge.
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
UpdateComRecordsRequestapplication/json
UpdateComRecordsRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications
GET/comlog/records
Get all the communication log records.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
recordIdListstringThis 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.
unansweredbooleanThis 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.
unacknowledgedbooleanThis 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.
withAttachmentstringThis 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.
afterDatestringThis 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.
beforeDatestringThis 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.
roleRoleThis 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.
comRefstringThis parameter is optional. The comref of the com we want to retrieve.
remotePartyIdstringThis parameter is optional. Ask to apply the operation on the records in which the user is engaged with this remote party.
offsetintThis 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.
limitintThis 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).
optimizedboolean

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.
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200ComHistoryRecordsapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Get all unanswered communication log records.

DELETE/comlog/records
Delete all (or only the specified) communication log records.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
recordIdListstringThis 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.
unansweredstringThis 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.
unacknowledgedstringThis 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.
withAttachmentstringThis 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.
afterDatestringThis 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.
beforeDatestringThis 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.
rolestringThis 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.
comRefstringThis parameter is optional. The comref of the com we want to delete.
remotePartyIdstringThis parameter is optional. Ask to apply the operation on the records in which the user is engaged with this remote party.
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/comlog/records/recordIds

Methods
GET/comlog/records/recordIds
Get the whole list of communication log record Ids.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200ComHistoryRecordIdsapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/comlog/records/{recordId}

Methods
GET/comlog/records/{recordId}
Get a communication log record.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
recordIdstringIdentifier of the record
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200ComHistoryRecordapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable
DELETE/comlog/records/{recordId}
Delete a record.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
recordIdstringIdentifier of the record
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/comlog/records/{recordId}/im

Methods
GET/comlog/records/{recordId}/im
Get the IM thread associated to the comLog record.
History
Since version 2.3
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
recordIdstringIdentifier of the record
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200ImHistoryRecordapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable

Representations

Attachment
An 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
NameTypeCardinalityDescription
typeAttachmentType[1]Type of attachment which is restricted to a voice record or a conferencing VCS reference.
descriptionstring[0..1]Describes the content of the attachment.
valuestring[1]URI or reference of the attachment.
[+] : JSON Example
AttachmentType
Type of attachment linked with the record.
ValueDescription
VOICEMAILType of attachment is a voice record
AUDIORECType of attachment is a audio online record or a voice record
CONFREFType of attachment is a conferencing
boolean
'boolean' is a data type, having two values (true and false).
ComHistoryRecord
Communication history ticket (ComLog).
NameTypeCardinalityDescription
recordIdlong[0..1]unique identifier of the record.
comRefstring[1]Communication reference identifier.
acknowledgedboolean[0..1]False indicates that the ticket corresponds to a non answered incoming call that has not been later acknowledged.
participantsParticipant[0..*]List of participants involved in the communication. The list may be null for a scheduled conference that has not yet started.
beginDatedateTime[0..1]Begin date of the communication (when the call is launched).
endDatedateTime[0..1]End date of the conversation (when the call is terminated or canceled).
mediasMediaType[1..*]The list of medias involved in the communication.
attachmentsAttachment[0..*]The list of documents or media resources attached to the communication.
extensionsTagValuePair[0..*]For evolution of this element, can contain supplementary information (tag/value pair).
[+] : JSON Example
Associated method :
ComHistoryRecordIds
Container for the list of history record ids (ComLog).
NameTypeCardinalityDescription
recordIdslong[0..*]The list the IDs of the com log records.
[+] : JSON Example
Associated method :
ComHistoryRecords
List of ComHistoryRecord (ComLog).
NameTypeCardinalityDescription
comHistoryRecordsComHistoryRecord[0..*]List of ComHistoryRecord.
offsetint[0..1]The offset of the first record which is returned.
limitint[0..1]Defines the maximum number of records returned.
totalCountint[0..1]Defines the total number of records without pagination.
[+] : JSON Example
Associated method :
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).
Identifier
Key information to help retrieving a participant (ComLog).
NameTypeCardinalityDescription
loginNamestring[0..1]Login name.
phoneNumberstring[0..1]Company phone number.
instantMessagingIdstring[0..1]Instant messaging identity.
companyEmailstring[0..1]Company email.
[+] : JSON Example
ImHistoryRecord
ImHistoryRecord = List of ImMessage.
NameTypeCardinalityDescription
idstring[0..1]The id of the IM thread record.
titlestring[0..1]The title of the IM thread record.
imMessagesImMessage[0..*]List of ImMessage.
[+] : JSON Example
Associated method :
ImMessage
An IM message is defined by its sender identifier, a date and the message content
NameTypeCardinalityDescription
senderstring[0..1]The sender of the message.
contentstring[0..1]Describes the content of the message.
datedateTime[0..1]date of the message (when the message is sent).
[+] : JSON Example
int
'int' is a 32-bit number (-2147483648 to 2147483647).
long
'long' is a 64-bit number (-9223372036854775808 to 9223372036854775807).
MainType
Main participant type.
ValueDescription
USERThe participant is a user of the system.
DEVICEThe participant is a device of the system.
SERVICEThe participant is a service of the system.
EXTERNALThe participant is not a user of the system.
UNKNOWNThe main participant type is unknown.
MediaType
A media can be:
ValueDescription
AUDIOThe media is an audio.
VIDEOThe media is a video.
IMThe media is an instant messaging.
SHARINGThe media is a data sharing.
RECORDThe media is a record.
WHITEBOARDThe media is a white board.
DOCUMENTThe media is a document.
POLLThe media is a poll.
UNKNOWNThe media is unknown.
OnComRecordCreated
Notification sent when a new comlog entry has been created.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnComRecordCreated'
loginNamestring[1]Login name of the user (identifier which can be used for filtering).
recordComHistoryRecord[1]Contains all the fields of a call log record.
[+] : JSON Example
OnComRecordModified
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)

NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnComRecordModified'
loginNamestring[1]Login name of the user (identifier which can be used for filtering).
recordComHistoryRecord[1]Contains all or part of the modified fields of a modified com log record.(example: acknowledged).
[+] : JSON Example
OnComRecordsAck
Notification sent when one or more unanswered comlog records have been acknowledged.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnComRecordsAck'
loginNamestring[1]Login name of the user (identifier which can be used for filtering).
recordIdslong[0..*]A list of IDs of records which have been acknowledged.
[+] : JSON Example
Associated method :
OnComRecordsDeleted
Notification sent when one or more call log records have been destroyed.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnComRecordsDeleted'
loginNamestring[1]Login name of the user (identifier which can be used for filtering).
recordIdslong[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.
[+] : JSON Example
Associated methods :
OnComRecordsUnAck
Notification sent when one or more unanswered comlog records have been unacknowledged.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnComRecordsUnAck'
loginNamestring[1]Login name of the user (identifier which can be used for filtering).
recordIdslong[0..*]A list of IDs of records which have been acknowledged.
[+] : JSON Example
Associated method :
Participant

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.

NameTypeCardinalityDescription
roleRole[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).
answeredboolean[0..1]defines whether the participant has really entered in the conversation. Can be omitted if the value is not known.
identityPartyInfo[1]Full description of a party involved in an history record.
anonymousboolean[0..1]Indicate if the participant identity is anonymous or not.
initialCalledPartyInfo[0..1]The number that has been initially called when this participant has been entered in the call.
reasonReason[0..1]The reason why the call has been established, rerouted, terminated ...
pilotstring[0..1]

Since version 2.5

Pilot name if the call was distributed by a pilot
[+] : JSON Example
ParticipantType
Detail about a kind of participant (ComLog).
NameTypeCardinalityDescription
mainMainType[1]Gives the main type of the participant: "user", "device", ...
subTypestring[0..1]The subType string gives a supplementary information and can contain "manager", "assistant", "voicemail",...
[+] : JSON Example
PartyInfo
Full description of a party involved in an history record (ComLog).
NameTypeCardinalityDescription
idIdentifier[1]Key information to help retrieving a participant.
firstNamestring[0..1]First name.
lastNamestring[0..1]Last name.
displayNamestring[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.
vcardUrlstring[0..1]

Subject to change: DO NOT USE.

typeParticipantType[0..1]Participant's type.
[+] : JSON Example
Reason
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 ...
ValueDescription
ALL_TRUNK_BUSYThe call was released because all trunk are busy.
INVALID_NUMBERThe call was refused because the dialed number is not valid.
ABANDONEDThe call was canceled by the caller.
BUSYThe call failed because the called party is busy.
CONFERENCEDThe call was set to be a conference.
PICKUPThe call was picked up.
FORWARDEDThe call was forwarded to another destination.
REDIRECTEDThe call was redirected to another destination.
RELEASED_ON_REDIRECTThe call was released since redirection to another destination fails.
TRANSFERREDThe call was transferred.
RELEASED_ON_TRANSFERThe call was released since transfer to another destination fails.
VOICEMAILThe call ended on voicemail.
NORMALThe call normally ended.
UNKNOWNThe reason is unknown.
Role
role of a participant in the communication.
ValueDescription
CALLERThe participant is a caller party.
CALLEEThe participant is a called party.
CONFLEADERThe participant is a leader of the conference.
CONFPARTICIPANTThe participant is a participant in a conference.
UNKNOWNThe role is unknown.
string
'string' represents character strings.
TagValuePair
Key / value structure.
NameTypeCardinalityDescription
namestring[1]Key
valuestring[1]Value
[+] : JSON Example
UpdateComRecordsRequest
Request sent for updating communication history records (ComLog).
NameTypeCardinalityDescription
recordIdslong[0..*]The list the IDs of the com log records to update.
[+] : JSON Example
Associated method :

Event summary

Resource summary

ResourceMethodDescription
/eventSummaryGETRetrieves main counters of the user's event log.

Notification summary

NotificationDescription
OnEventSummaryUpdatedNotification sent each time the user's counters have changed.

Resource

/eventSummary

Methods
GET/eventSummary
Retrieves main counters of the user's event log.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200EventSummaryapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Retrieves main counters of the user's event log.

Representations

boolean
'boolean' is a data type, having two values (true and false).
EventSummary
Describes an event summary.
NameTypeCardinalityDescription
missedCallsNbnonNegativeInteger[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.
voiceMessagesNbnonNegativeInteger[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.
callBackRequestsNbnonNegativeInteger[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.
faxNbnonNegativeInteger[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.
eventWaitingboolean[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.
forResynchronizationboolean[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).
[+] : JSON Example
Associated method :
nonNegativeInteger
'nonNegativeInteger' is all positive integer numbers and zero. Negative integers are excluded.
OnEventSummaryUpdated
Notification sent each time the user's counters have changed.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnEventSummaryUpdated'
loginNamestring[1]Login name of the user (identifier which can be used for filtering).
eventSummaryEventSummary[1]The new event summary.
[+] : JSON Example
string
'string' represents character strings.

Maintenance

Notification summary

NotificationDescription
OnChannelInformationNotification sent for information to the user :error, info, keepalive.

Representations

OnChannelInformation
Notification sent for information to the user :error, info, keepalive.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnChannelInformation'
textstring[0..1]Details about the information sent.
[+] : JSON Example
string
'string' represents character strings.

Instant Messaging

History

Since version 2.1.1

Resources summary

ResourceMethodDescription
/im/callsGETList all the currently active IM sessions of the user.
POSTCreate a new instant messaging session.
/im/calls/{callRef}DELETEDelete an instant messaging session.
/im/calls/{callRef}/participantsGETList all the participants of an IM session.
POSTAdd a list of participants into an IM session.
DELETERemove (drop) a list of participants from an IM session.
/im/calls/{callRef}/sendPOSTSend an instant message to a list of participants in a given IM session.
/im/calls/{callRef}/statePOSTSet the user's state as 'typing a message'.
/im/deferredGETRetrieve all the deferred messages stored on the server.
DELETEDelete the deferred messages stored on the server.
PUTUpdate the status of the deferred messages stored on the server.
/im/deferred/countersGETWhen user is offline, messages sent to him can not be delivered.

Notifications summary

NotificationDescription
OnDeferredMessageCountersChangedEvent received indicating that an instant message has been left on the server.
OnImParticipantAddedEvent sent when a participant is added in an IM session.
OnImParticipantDroppedEvent sent when a participant is dropped from an IM session.
OnImParticipantTypingEvent sent when a participant has set its typing state (i.
OnImReceivedEvent received containing the instant message.

Resources

/im/calls

Methods
GET/im/calls
List all the currently active IM sessions of the user.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200IMSessionsapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
POST/im/calls
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
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
201application/json
Created
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/im/calls/{callRef}

Methods
DELETE/im/calls/{callRef}
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
parametertypedescription
callRefstringreference of the session.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/im/calls/{callRef}/participants

Methods
GET/im/calls/{callRef}/participants
List all the participants of an IM session.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callRefstringCall reference.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Participantsapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
POST/im/calls/{callRef}/participants
Add a list of participants into an IM session.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callRefstringthe reference of the IM session.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
ParticipantIdsthe container for the list of participants to add (list of instantMessagingIds).
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications
DELETE/im/calls/{callRef}/participants
Remove (drop) a list of participants from an IM session.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
callRefstringthe reference of the IM session.
query parameters
parametertypedescription
partIdsstringlist of comma separated participants Ids to remove (list of instantMessagingIds).
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/im/calls/{callRef}/send

Methods
POST/im/calls/{callRef}/send
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
parametertypedescription
callRefstringreference of the session.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
IMMessageIMMessage the message info to send (message and optional list of recipients).
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/im/calls/{callRef}/state

Methods
POST/im/calls/{callRef}/state
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
parametertypedescription
callRefstringthe reference of the IM session.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
IMStateapplication/json
the typing state, including a filter on recipients.
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/im/deferred

Methods
GET/im/deferred
Retrieve all the deferred messages stored on the server.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200DeferredMessagesapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
DELETE/im/deferred
Delete the deferred messages stored on the server.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
msgIdsstringlist of comma separated deferred messages to delete.
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications
PUT/im/deferred
Update the status of the deferred messages stored on the server.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
readstringtrue to set the messages as read, false to set them as unread.
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
DeferredMessagesIdsapplication/json
DeferredMessagesIdsDTO DeferredMessagesIds contains list of deferred messages to update.
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/im/deferred/counters

Methods
GET/im/deferred/counters
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
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200DeferredMsgCountersapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/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).
DeferredMessage
Deferred message description.
NameTypeCardinalityDescription
messageIdstring[1]Identifier of the message.
fromPartyInfo[1]Party info of the sender.
datedateTime[0..1]Date and time of deposit of the message, in ISO8601 compatible format.
unreadboolean[1]Indicates If this message has been read or not.
messagestring[1]Content of the message.
[+] : JSON Example
DeferredMessages
Container for a list of deferre messages.
NameTypeCardinalityDescription
messagesDeferredMessage[0..*]List of DeferredMessages.
[+] : JSON Example
Associated method :
DeferredMessagesIds
Container for a list of deferred messages ids.
NameTypeCardinalityDescription
idsstring[0..*]List of DeferredMessagesIds.
[+] : JSON Example
Associated method :
DeferredMsgCounters
Description of deferred messages left on the server.
NameTypeCardinalityDescription
waitingboolean[1]Indicates there are deferred messages left on the server (read or unread).
readint[1]Number of deferred messages remaining on the server that have been marked as read (i.e. acknowledged).
unreadint[1]Number of deferred messages remaining on the server that have been marked as unread (i.e. unacknowledged).
[+] : JSON Example
Associated method :
Identifier
Key information to help retrieving a participant.
NameTypeCardinalityDescription
loginNamestring[0..1]Login name.
phoneNumberstring[0..1]Company phone number.
instantMessagingIdstring[0..1]Instant messaging identity.
companyEmailstring[0..1]Company email.
[+] : JSON Example
IMMessage
Instant message descriptor.
NameTypeCardinalityDescription
recipientsstring[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.
messagestring[1]Content of the message to send.
[+] : JSON Example
Associated method :
IMSession
Describes an instant messaging session.
NameTypeCardinalityDescription
ownerPartyInfo[1]Party Info of the user who has created the session.
callRefstring[1]Reference of the IM session.
confNamestring[0..1]If the IM session has been initiated as part of a scheduled conference, this field indicates the name of the conference.
participantsParticipant[0..*]List of Participants.
[+] : JSON Example
IMSessions
Container for list of IM sessions.
NameTypeCardinalityDescription
imSessionsIMSession[0..*]List of IM sessions.
[+] : JSON Example
Associated method :
IMState
State indication of an IM session.
NameTypeCardinalityDescription
imTypingStateboolean[1]Set the typing state of the user.
recipientsstring[0..*]List of recipients of the typing state (instantMessagingIds). If not set, all the participants will receive the state change.
[+] : JSON Example
Associated method :
int
'int' is a 32-bit number (-2147483648 to 2147483647).
OnDeferredMessageCountersChanged
Event received indicating that an instant message has been left on the server.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnDeferredMessageCountersChanged'
loginNamestring[1]Login of the user receiving the event.
waitingboolean[0..1]Indicates if there is still some deferred messages on the server, whatever the state (read or unread).
readint[1]Number of messages stored on the server that have been read.
unreadint[1]Number of messages stored on the server that have not been read.
[+] : JSON Example
Associated methods :
OnImParticipantAdded
Event sent when a participant is added in an IM session.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnImParticipantAdded'
loginNamestring[1]Login name of the user receiving the event.
callRefstring[1]Reference of the IM session.
participantPartyInfo[1]Added participant information.
[+] : JSON Example
Associated method :
OnImParticipantDropped
Event sent when a participant is dropped from an IM session.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnImParticipantDropped'
loginNamestring[1]Login of the user receiving the event.
callRefstring[1]Reference of the IM session.
participantIdstring[1]Dropped participantId.
[+] : JSON Example
Associated methods :
OnImParticipantTyping
Event sent when a participant has set its typing state (i.e. just starting typing).
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnImParticipantTyping'
loginNamestring[1]Login of the user receiving the event.
callRefstring[1]Reference of the IM session.
participantIdstring[1]Typing participantId.
imTypingStateboolean[0..1]True if the participant is typing.
[+] : JSON Example
Associated method :
OnImReceived
Event received containing the instant message.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnImReceived'
loginNamestring[1]Login of the user receiving the event.
callRefstring[1]Reference of the IM session.
fromPartyInfo[1]Participant information of the sender.
tostring[0..*]List of participantId (i.e. recipients)of the message. If not set, all participants of a session receive the message.
messagestring[1]Received message.
[+] : JSON Example
Associated method :
Participant
Describes a participant referenced in instant messaging (IM).
NameTypeCardinalityDescription
participantIdstring[1]Identifier of the participant. Equivalent to instantMessagingId.
identityPartyInfo[1]Party info contains additional fields about the participant.
leaderboolean[1]Indicate if the given participant is leader in the referring IM session or not.
ownerboolean[0..1]Indicate if the participant is the creator of the IM session.
[+] : JSON Example
ParticipantIds
Container for a list of participant Ids.
NameTypeCardinalityDescription
participantIdsstring[0..*]Container for a list of participants.
[+] : JSON Example
Associated method :
Participants
Container for a list of participants.
NameTypeCardinalityDescription
participantsParticipant[0..*]Container for Participants.
[+] : JSON Example
Associated method :
PartyInfo
Full description of a party (i.e. participant's description).
NameTypeCardinalityDescription
idIdentifier[1]Key information to help retrieving a participant.
firstNamestring[0..1]First name of the participant.
lastNamestring[0..1]Last name of the participant.
displayNamestring[0..1]Display name of the participant.
[+] : JSON Example
string
'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: 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:

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:

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

ResourceMethodDescription
/presence/contactsGETRetrieves contacts presences.
/presence/contacts/subscribePOSTSubscribe to a list of contacts for which we want to receive presence updates.
/presence/contacts/unsubscribePOSTUnsubscribe a list of contacts for which we no longer want to receive presences updates.
/presence/userGETRetrieves all the user presences types in a single operation.
/presence/user/basicGETRetrieves the user's basic presence.
PUTSet the user's basic presence.
/presence/user/calendarGETRetrieves the user's calendar presence.
PUTSet the user's calendar presence.
/presence/user/imGETRetrieves the user's IM presence.
/presence/user/noteGETRetrieves the user's note presence.
PUTSet the user's note presence.
/presence/user/phoneGETRetrieves the user's phone presence.

Notifications summary

NotificationDescription
OnContactPresenceUpdatedEvent received on contact's presence changed.
OnUserPresenceUpdatedEvent received on user's presence changed.

Resources

/presence/contacts

Methods
GET/presence/contacts
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
parametertypedescription
imIdsstringcomma separated list of instantMessagingIds.
phoneNumbersstringcomma separated list of company phone numbers.
detailsbooleanIf 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).
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200ContactsPresencesapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/presence/contacts/subscribe

Methods
POST/presence/contacts/subscribe
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
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
ContactsInfoapplication/json
container for the list of instantMessagingIds or phoneNumbers to subscribe to.
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/presence/contacts/unsubscribe

Methods
POST/presence/contacts/unsubscribe
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
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
ContactsInfoapplication/json
container for list of instantMessagingIds or phoneNumbers to unsubscribe from.
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/presence/user

Methods
GET/presence/user
Retrieves all the user presences types in a single operation.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Presencesapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/presence/user/basic

Methods
GET/presence/user/basic
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
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Presenceapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
PUT/presence/user/basic
Set the user's basic presence.
See GET /presence/user/basic for values.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
Presenceapplication/json
Presence the presence type and value.
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/presence/user/calendar

Methods
GET/presence/user/calendar
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
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Presenceapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
PUT/presence/user/calendar
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
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
Presenceapplication/json
The calendar presence to set.
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/presence/user/im

Methods
GET/presence/user/im
Retrieves the user's IM presence.
Values are 'online', 'offline'.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Presenceapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/presence/user/note

Methods
GET/presence/user/note
Retrieves the user's note presence.

This is also known as the mood phrase

Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Presenceapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
PUT/presence/user/note
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
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
Presenceapplication/json
Presence the presence type and value.
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/presence/user/phone

Methods
GET/presence/user/phone
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
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Presenceapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

Representations

CalendarInfos
Calendar presence supplementary information.
NameTypeCardinalityDescription
endDatestring[0..1]Date and time (ISO8601 format) of the end of the meeting. Example: '2015-07-10T10:15:00Z'
[+] : JSON Example
ContactsInfo
Container for a list of contacts identifiers. A contact is mainly identified by its instantMessagingId, but could also be by its phone number.
NameTypeCardinalityDescription
instantMessagingIdsstring[0..*]List of contacts instantMessagingId.
phoneNumbersstring[0..*]List of contacts phoneNumber.
[+] : JSON Example
Associated methods :
ContactsPresences
Container for a list of presence..
NameTypeCardinalityDescription
contactsPresences[0..*]The list of different contact presences.
[+] : JSON Example
Associated method :
Identifier
Key information to help retrieving a participant.
NameTypeCardinalityDescription
loginNamestring[0..1]Login name.
phoneNumberstring[0..1]Company phone number.
instantMessagingIdstring[0..1]Instant messaging identity.
companyEmailstring[0..1]Company email.
[+] : JSON Example
OnContactPresenceUpdated
Event received on contact's presence changed.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnContactPresenceUpdated'
loginNamestring[1]Login of the user receiving the event.
partyPartyInfo[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).
presencesPresence[1..*]Presence types.
[+] : JSON Example
Associated methods :
OnUserPresenceUpdated
Event received on user's presence changed.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnUserPresenceUpdated'
loginNamestring[1]Login of the user receiving the event.
presencesPresence[1..*]Presence types.
[+] : JSON Example
Associated methods :
PartyInfo
Full description of a party (i.e. participant's description).
NameTypeCardinalityDescription
idIdentifier[1]Key information to help retrieving a participant.
firstNamestring[0..1]First name of the participant.
lastNamestring[0..1]Last name of the participant.
displayNamestring[0..1]Display name of the participant.
[+] : JSON Example
Presence
Presence descriptor.
NameTypeCardinalityDescription
typestring[1]The type / category of presence: im, phone, basic, calendar, ...
valuestring[1]Value of the presence: online, busy, ...
calendarInfosCalendarInfos[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).
[+] : JSON Example
Associated methods :
Presences
Container for a list of presence..
NameTypeCardinalityDescription
partyPartyInfo[0..1]The party.
presencesPresence[0..*]The list of different presences.
[+] : JSON Example
Associated method :
string
'string' represents character strings.

Messaging

Resources summary

ResourceMethodDescription
/messaging/mailboxesGETGet all the user's mailboxes.
/messaging/mailboxes/{mailboxId}GETGet a specific mailbox information.
/messaging/mailboxes/{mailboxId}/playerPOSTStart or resume playing a voice message.
DELETETerminate a player session with the media server.
/messaging/mailboxes/{mailboxId}/player/pausePOST

Pause the current voice message being played.

/messaging/mailboxes/{mailboxId}/player/stopPOSTStop a currently playing on a message.
/messaging/mailboxes/{mailboxId}/recorderPOSTStart or restart a record of a new voice message.
GETGet the previously recorded message.
DELETETerminate a recorder session with the media server.
/messaging/mailboxes/{mailboxId}/recorder/cancelPOSTCancel a currently recording message, or the previously created message.
/messaging/mailboxes/{mailboxId}/recorder/resumePOSTResume recording of a message.
/messaging/mailboxes/{mailboxId}/recorder/sendPOSTSend a recorded message to a list of recipients.
/messaging/mailboxes/{mailboxId}/recorder/stopPOSTStop currently recording on a message.
/messaging/mailboxes/{mailboxId}/voicemailsGETRetrieve all user's voicemails, or only those specified by the filter parameters offset / limit / newOnly.
DELETEDelete specified voicemails.
/messaging/mailboxes/{mailboxId}/voicemails/{voicemailId}DELETE

Delete the specified voicemail.

GET

Retrieve a given user's voicemail, containing the full details (including the URL).

/messaging/mailboxes/{mailboxId}/voicemails/{voicemailId}/callbackPOST

Call back the sender of a voice message.

/messaging/mailboxes/{mailboxId}/voicemails/{voicemailId}/forwardPOST

Forward an existing message with recording an introduction.

Notifications summary

NotificationDescription
OnMessageAddedEvent sent when a new voice message has been stored in the user's mailbox.
OnMessageDeletedEvent sent when a voice message has been deleted from the user's mailbox.
OnMessageUpdatedEvent sent when a voice message status has been updated.

Resources

/messaging/mailboxes

Methods
GET/messaging/mailboxes
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
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200MailBoxesapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/messaging/mailboxes/{mailboxId}

Methods
GET/messaging/mailboxes/{mailboxId}
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
parametertypedescription
mailboxIdstringIdentifier of the mailbox.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200MailBoxInfoapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/messaging/mailboxes/{mailboxId}/player

Methods
POST/messaging/mailboxes/{mailboxId}/player
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
parametertypedescription
mailboxIdstringIdentifier of the mailbox.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
PlayVoiceMessageRequestapplication/json
PlayVoiceMessageRequest contains message to play, phone to use, ...
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications
DELETE/messaging/mailboxes/{mailboxId}/player
Terminate a player session with the media server.
Licenses
The license MESSAGING is required.
Request
path parameters
parametertypedescription
mailboxIdstringIdentifier of the mailbox.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/messaging/mailboxes/{mailboxId}/player/pause

Methods
POST/messaging/mailboxes/{mailboxId}/player/pause

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
parametertypedescription
mailboxIdstringIdentifier of the mailbox.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/messaging/mailboxes/{mailboxId}/player/stop

Methods
POST/messaging/mailboxes/{mailboxId}/player/stop
Stop a currently playing on a message.
Licenses
The license MESSAGING is required.
Request
path parameters
parametertypedescription
mailboxIdstringIdentifier of the mailbox.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/messaging/mailboxes/{mailboxId}/recorder

Methods
POST/messaging/mailboxes/{mailboxId}/recorder
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
parametertypedescription
mailboxIdstringIdentifier of the mailbox.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
RecordVoiceMessageRequestapplication/json
RecordVoiceMessageRequest contains the phone to use for the media session.
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
GET/messaging/mailboxes/{mailboxId}/recorder
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
parametertypedescription
mailboxIdstringIdentifier of the mailbox.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200VoiceRecordapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
DELETE/messaging/mailboxes/{mailboxId}/recorder
Terminate a recorder session with the media server.
Licenses
The license MESSAGING is required.
Request
path parameters
parametertypedescription
mailboxIdstringIdentifier of the mailbox.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/messaging/mailboxes/{mailboxId}/recorder/cancel

Methods
POST/messaging/mailboxes/{mailboxId}/recorder/cancel
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
parametertypedescription
mailboxIdstringIdentifier of the mailbox.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/messaging/mailboxes/{mailboxId}/recorder/resume

Methods
POST/messaging/mailboxes/{mailboxId}/recorder/resume
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
parametertypedescription
mailboxIdstringIdentifier of the mailbox.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/messaging/mailboxes/{mailboxId}/recorder/send

Methods
POST/messaging/mailboxes/{mailboxId}/recorder/send
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
parametertypedescription
mailboxIdstringIdentifier of the mailbox.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
SendMessageRequestapplication/json
descriptor containing the list of recipients and the url of the message.
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/messaging/mailboxes/{mailboxId}/recorder/stop

Methods
POST/messaging/mailboxes/{mailboxId}/recorder/stop
Stop currently recording on a message.
Licenses
The license MESSAGING is required.
Request
path parameters
parametertypedescription
mailboxIdstringIdentifier of the mailbox.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/messaging/mailboxes/{mailboxId}/voicemails

Methods
GET/messaging/mailboxes/{mailboxId}/voicemails
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
parametertypedescription
mailboxIdstringIdentifier of the mailbox.
query parameters
parametertypedescription
offsetintthe offset from which to start retrieving the voicemail list (Default value is 0).
limitintthe maximum number of items to return (Default value is -1: no limit).
newOnlybooleanfilter only unread voicemail if set to 'true' (Default value is 'false').
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Voicemailsapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
DELETE/messaging/mailboxes/{mailboxId}/voicemails
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
parametertypedescription
mailboxIdstringIdentifier of the mailbox.
query parameters
parametertypedescription
msgIdsstringlist of voice message Ids to delete (comma separated list of voicemailIds)
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/messaging/mailboxes/{mailboxId}/voicemails/{voicemailId}

Methods
DELETE/messaging/mailboxes/{mailboxId}/voicemails/{voicemailId}

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
parametertypedescription
voicemailIdstringIdentifier of the message.
mailboxIdstringIdentifier of the mailbox.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications
GET/messaging/mailboxes/{mailboxId}/voicemails/{voicemailId}

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
parametertypedescription
mailboxIdstringIdentifier of the mailbox.
voicemailIdstringIdentifier of the message.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Voicemailapplication/json
OK
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/messaging/mailboxes/{mailboxId}/voicemails/{voicemailId}/callback

Methods
POST/messaging/mailboxes/{mailboxId}/voicemails/{voicemailId}/callback

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
parametertypedescription
mailboxIdstringIdentifier of the mailbox.
voicemailIdstringIdentifier of the message.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
CallbackRequestcall back information.
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/messaging/mailboxes/{mailboxId}/voicemails/{voicemailId}/forward

Methods
POST/messaging/mailboxes/{mailboxId}/voicemails/{voicemailId}/forward

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
parametertypedescription
mailboxIdstringIdentifier of the mailbox.
voicemailIdstringIdentifier of the message.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
ForwardRequestforward request information.
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

Representations

boolean
'boolean' is a data type, having two values (true and false).
CallbackRequest
Callback Sender Message request data.
NameTypeCardinalityDescription
phoneNumberstring[0..1]Phone number to use for the callback, if different from the default one.
[+] : JSON Example
Associated method :
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).
ForwardRequest
ForwardRequest Message request data.
NameTypeCardinalityDescription
phoneNumberstring[0..1]Phone number to use for the forward, if different from the default one.
[+] : JSON Example
Associated method :
Identifier
Key information to help retrieving a participant.
NameTypeCardinalityDescription
loginNamestring[0..1]Login name.
phoneNumberstring[0..1]Company phone number.
instantMessagingIdstring[0..1]Instant messaging identity.
companyEmailstring[0..1]Company email.
[+] : JSON Example
int
'int' is a 32-bit number (-2147483648 to 2147483647).
MailBox
Descriptor of a mailbox.
NameTypeCardinalityDescription
idstring[0..1]Identifier of the mailbox.
namestring[0..1]Name of the mailbox.
capabilitiesMailBoxCapabilities[0..1]Capabilities supported by the mailbox.
[+] : JSON Example
MailBoxCapabilities
List the capabilities supported by a mailbox.
NameTypeCardinalityDescription
listMessagesboolean[0..1]Voicemail server can return the list of messages.
getMessagesboolean[0..1]Voice messages can be downloaded.
getRecordboolean[0..1]Recorded message can be downloaded.
playboolean[0..1]Voicemail server is capable of playing voice messages.
pauseboolean[0..1]Playing voice message can be paused and resumes from the position it has been paused.
hangupboolean[0..1]Media session can be terminate.
recordboolean[0..1]The voicemail server is capable of recording voice messages.
resumeboolean[0..1]Voice message recording can be resumed after being stopped.
cancelboolean[0..1]The current recording can be cancelled.
forwardboolean[0..1]The voicemail server is capable of forwarding voice messages.
callbackboolean[0..1]The voicemail server can call back the originator of the voice message.
sendboolean[0..1]Voice message or record can be sent to recipients.
eventsboolean[0..1]Voicemail server is capable to send events in case of message deposit / removal.
[+] : JSON Example
MailBoxes
Container for a list of Mailbox
NameTypeCardinalityDescription
mailboxesMailBox[0..*]List of user mailboxes.
[+] : JSON Example
Associated method :
MailBoxInfo
Descriptor of a MailboxInfo.
NameTypeCardinalityDescription
totalVoiceMsgint[0..1]Number of voice messages.
newVoiceMsgint[0..1]Number of new (unread) voice messages.
storageUsageint[0..1]Threshold indicating mailbox usage ratio. 100 mean 100% full. No more message deposit is allowed. -1 means information not available.
[+] : JSON Example
Associated method :
OnMessageAdded
Event sent when a new voice message has been stored in the user's mailbox.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnMessageAdded'
loginNamestring[1]Login name of the user receiving the event.
mailboxIdstring[1]Identifier of the user's mailbox for which the event was generated.
messageVoicemail[1]Newly added message in user's mailbox.
[+] : JSON Example
OnMessageDeleted
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.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnMessageDeleted'
loginNamestring[1]Login name of the user receiving the event.
mailboxIdstring[1]Identifier of the user's mailbox for which the event was generated.
messageIdstring[1]Id of the deleted message.
[+] : JSON Example
Associated methods :
OnMessageUpdated
Event sent when a voice message status has been updated. The update mostly concern the read / unread status of the voice message.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnMessageUpdated'
loginNamestring[1]Login name of the user receiving the event.
mailboxIdstring[1]Identifier of the user's mailbox for which the event was generated.
messageVoicemail[1]Updated message in user's mailbox.
[+] : JSON Example
Associated methods :
PartyInfo
Full description of a party (i.e. participant's description).
NameTypeCardinalityDescription
idIdentifier[1]Key information to help retrieving a participant.
firstNamestring[0..1]First name of the participant.
lastNamestring[0..1]Last name of the participant.
displayNamestring[0..1]Display name of the participant.
[+] : JSON Example
PlayVoiceMessageRequest
Play message Descriptor.
NameTypeCardinalityDescription
voicemailIdstring[0..1]Identifier of the voicemail to play.
phoneNumberstring[0..1]Phone number on which to play the message.
offsetstring[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.
[+] : JSON Example
Associated method :
RecordVoiceMessageRequest
Callback sender request data.
NameTypeCardinalityDescription
phoneNumberstring[0..1]Phone number to use for the callback, if different from the default one.
[+] : JSON Example
Associated method :
SendMessageRequest
Descriptor of a voice message.
NameTypeCardinalityDescription
destinationsIdentifier[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.
highPriorityboolean[0..1]Normal (default=false) high (true)..
urlstring[0..1]If specified, send the given url file instead of the newly recorded message.
[+] : JSON Example
Associated method :
string
'string' represents character strings.
Voicemail
Descriptor of a voice message.
NameTypeCardinalityDescription
voicemailIdstring[1]Identifier of the voicemail.
fromPartyInfo[0..1]Originator of the voicemail.
durationint[1]Duration, in seconds, of the voicemail.
datedateTime[1]Date and time (ISO-8601) of the message.
unreadboolean[1]Indicates if this message has been read or not.
highPriorityboolean[1]Indicate if the message has been tagged as urgent or not.
urlstring[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
Associated method :
Voicemails
List of voicemails.
NameTypeCardinalityDescription
voicemailsVoicemail[0..*]List of voicemails.
[+] : JSON Example
Associated method :
VoiceRecord
Record message Descriptor.
NameTypeCardinalityDescription
urlstring[0..1]The Url of the wav file of the newly recorded voice message.
[+] : JSON Example
Associated method :

Groups

Presentation

The REST groups service covers the Supervision service and the Hunting Group service.

Supervision

 

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

 

 

Hunting Group (HG)

History

Since version 2.1.1

Resources summary

ResourceMethodDescription
/groupsGETGet information on all the groups of the user.
/groups/refreshPOSTAsk to be refreshed by notification on all the calls which happened on the groups of the user.
/groups/{groupId}GETReturns a description of one group.
/groups/{groupId}/changeRolePOSTChange the role of member(s) of a group.

Notifications summary

NotificationDescription
OnGroupCreatedThis notification indicates to a user that it is inserted in a new group.
OnGroupLoggedFailedThis notification indicates to a member of a group that the group logged request failed.
OnGroupModifiedThis notification indicates to a member of a group that this group has been modified: members added, members removed or members changed (right or role).
OnGroupRemovedThis notification indicates that a user is removed from a group
OnSupervisedUpdatedThis notification indicates to a supervisor user that some of its supervised users have changed.

Resources

/groups

Methods
GET/groups
Get information on all the groups of the user.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Groupsapplication/json
OK
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/groups/refresh

Methods
POST/groups/refresh
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
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/groups/{groupId}

Methods
GET/groups/{groupId}
Returns a description of one group.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
groupIdstring
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Groupapplication/json
OK
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable

/groups/{groupId}/changeRole

Methods
POST/groups/{groupId}/changeRole
Change the role of member(s) of a group.
Licenses
The license TELEPHONY_ADVANCED is required.
Request
path parameters
parametertypedescription
groupIdstring
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
ChangeRoleRequestChangeRoleRequest
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
404application/json
Not Found
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

Representations

boolean
'boolean' is a data type, having two values (true and false).
Call
Describes an user's call.
NameTypeCardinalityDescription
callRefstring[1]Reference of the call.
callDataCallData[0..1]Call data.
participantsParticipant[0..*]Participants.
[+] : JSON Example
CallData
Detail about data associated to a call.
NameTypeCardinalityDescription
initialCalledPartyInfo[0..1]Initial called identifier.
anonymousboolean[0..1]If true it's a anonymous call.
[+] : JSON Example
ChangeRoleRequest
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
NameTypeCardinalityDescription
newMemberRolesNewMemberRole[0..*]The list of the members and their new role to update.
[+] : JSON Example
Associated method :
Group
Describes an user's group.
NameTypeCardinalityDescription
identifierstring[1]Group unique identifier.
namestring[0..1]Group unique identifier.
propsGroupProps[1]Group properties.
membersGroupMember[0..*]Group members.
[+] : JSON Example
Associated method :
GroupMember
Detail about a groupMember.
NameTypeCardinalityDescription
partyInfoPartyInfo[1]GroupMember identifier.
rightsGroupMemberRight[0..*]GroupMember rights
rolesGroupMemberRole[0..*]GroupMember roles (! could be empty!)
[+] : JSON Example
GroupMemberRight
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
ValueDescription
SUPERVISORThe group member is a supervisor.
SUPERVISEDThe group member is a supervised.
MANAGERThe group member is a manager.
ASSISTANT_MAINThe group member is a main assistant.
ASSISTANT_BACKUPThe group member is a backup assistant.
AGENTThe group member is an agent in a Hunting group
GroupMemberRole
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.
ValueDescription
SUPERVISORThe group member is logged as supervisor.
SUPERVISEDThe group member is logged as supervised.
AGENT

Since version 2.4

Hunting Group: the HG member is active in the call distribution.
FULLall types of group: default logging mode (only usable in changeMode request)
GroupMode
Indicate the working mode of a Supervision group.
ValueDescription
REGULARIn a regular group, supervised only users should only care about the supervisors.
COLLABORATIONIn a collaboration group, supervised only users could care about all group members.
GroupProps
Describes the properties of a group.
NameTypeCardinalityDescription
typeGroupType[1]Group type.
userManagedboolean[0..1]Group manageable by user. Only for Supervision groups (always False)
modeGroupMode[0..1]Group mode. For supervision group only !
[+] : JSON Example
Groups
List of Group.
NameTypeCardinalityDescription
groupsGroup[0..*]List of groups
[+] : JSON Example
Associated method :
GroupType
Lists the different types of group.
ValueDescription
SUPERVISIONSupervision group.
HUNTING_GROUP

Since version 2.4

Hunting group.
Identifier
Key information to help retrieving a participant.
NameTypeCardinalityDescription
loginNamestring[0..1]Login name.
phoneNumberstring[0..1]Company phone number.
instantMessagingIdstring[0..1]Instant messaging identity.
companyEmailstring[0..1]Company email.
[+] : JSON Example
NewMemberRole
Contain the new role of a group member, used when the role of a member is changed.
NameTypeCardinalityDescription
memberIdIdentifier[1]Group member unique identifier. Restriction: only the loginName is accepted
rolesGroupMemberRole[0..*]New Group member roles
[+] : JSON Example
OnGroupCreated
This notification indicates to a user that it is inserted in a new group.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnGroupCreated'
loginNamestring[1]Login name of the user (identifier which can be used for filtering).
identifierstring[1]Unique identifier of the group.
namestring[0..1]name of the group.
propsGroupProps[1]Properties of the group.
membersGroupMember[0..*]Members of the group.
[+] : JSON Example
OnGroupLoggedFailed
This notification indicates to a member of a group that the group logged request failed.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnGroupLoggedFailed'
loginNamestring[1]Login name of the user receiving the event.
identifierstring[1]Unique identifier of the group.
namestring[0..1]Name of the group.
propsGroupProps[1]Properties of the group.
deviceNumberstring[1]Device number.
causeIdstring[0..1]Cause of failed request.
descriptionstring[0..1]Description of failed request.
[+] : JSON Example
Associated method :
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).
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnGroupModified'
loginNamestring[1]Login name of the user (identifier which can be used for filtering).
identifierstring[1]Unique identifier of the group.
namestring[0..1]name of the group.
propsGroupProps[1]Properties of the group.
addedMembersGroupMember[0..*]AddedMembers in the group.
modifiedMembersGroupMember[0..*]ModifiedMembers in the group.
removedMembersGroupMember[0..*]RemovedMembers from the group.
[+] : JSON Example
OnGroupRemoved
This notification indicates that a user is removed from a group
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnGroupRemoved'
loginNamestring[1]Login name of the user (identifier which can be used for filtering).
identifierstring[1]Unique identifier of the group.
propsGroupProps[0..1]Properties of the group.
[+] : JSON Example
OnSupervisedUpdated
This notification indicates to a supervisor user that some of its supervised users have changed.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnSupervisedUpdated'
loginNamestring[1]Login name of the supervisor user (identifier which can be used for filtering).
supervisedUsersSupdUser[0..*]supervised users list that have changed.
[+] : JSON Example
Associated method :
Participant
Detail about a participant in a remote call
NameTypeCardinalityDescription
participantIdstring[1]Participant identifer (Should not be displayed).
identityPartyInfo[0..1]Participant identity card.
[+] : JSON Example
PartyInfo
Full description of a party (i.e. participant's description).
NameTypeCardinalityDescription
idIdentifier[1]Key information to help retrieving a participant.
firstNamestring[0..1]First name of the participant.
lastNamestring[0..1]Last name of the participant.
displayNamestring[0..1]Display name of the participant.
[+] : JSON Example
string
'string' represents character strings.
SupdUser
Describes a supervised.
NameTypeCardinalityDescription
loginNamestring[1]loginName of the supervised user.
phoneNumberstring[0..1]phoneNumber of the supervised user.
telPresenceStateTelPresenceState[1]tel Presence state.
callsCall[0..*]incoming calls.
[+] : JSON Example
TelPresenceState
Lists the telephonic presence state of group supervised member.
ValueDescription
FREEThe supervised is free.
RINGING_INCOMINGThe supervised receives an incoming ringing call (or more).
BUSYThe supervised is engaged in one or several call.
BUSY_RINGING_INCOMINGThe supervised receives an incoming ringing call (or more) while it is already busy with another call.
UNKNOWNUNKNOWN 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:


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:

A restart of the OpenTouch solution is recommended.

Restrictions / limitations

When creating a conference from an existing iCalendar file, some limitations may be found:

History

Since version 2.2

Resources summary

ResourceMethodDescription
/conferencesGETGet all the user conferences.
GETGet all the conferences in iCalendar format.
POSTCreate a conference from the given descriptor.
POSTCreate or update a conference from a given iCalendar file.
/conferences/delegatesGETRetrieve the delegates.
POSTSet delegation to participant(s).
DELETEUnset delegation to participant(s).
/conferences/{conferenceId}GETGet a specific conference.
PUTModify a specific conference.
GETGet a specific conference, as iCalendar format.
DELETEDelete a conference.
/conferences/{conferenceId}/documentsPOSTAdd a document to a conference.
/conferences/{conferenceId}/documents/{documentId}DELETERemove a document from a conference.
/conferences/{conferenceId}/joinPOSTJoin the conference.
/conferences/{conferenceId}/participantsPOSTAdd participant(s) to a conference.
DELETERemove participant(s) from a conference.
/conferences/{conferenceId}/participants/promotePOSTPromote participant(s) as leader(s).
DELETEDemote participants from leader role.

Notifications summary

NotificationDescription
OnConferenceCreatedEvent sent when a new conference has been created.
OnConferenceDeletedEvent sent when a conference has been deleted.
OnConferenceModifiedEvent sent when a conference has been modified.

Resources

/conferences

Methods
GET/conferences
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
parametertypedescription
loginNamestringLogin 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.
expiredbooleanIf true, response will include also expired conferences (default is false).
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Conferencesapplication/json
OK
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Retrieve all user conferences

GET/conferences
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
parametertypedescription
loginNamestringLogin 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.
expiredbooleanIf true, response will also include expired conferences (default is false).
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200iCalendartext/calendar
OK
400text/calendar
Bad Request
401text/calendar
Unauthorized
403text/calendar
Forbidden
500text/calendar
Internal Server Error
503text/calendar
Service Unavailable
Examples

[+] : Retrieve all user conferences in iCalendar format

POST/conferences
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
parametertypedescription
loginNamestringLogin 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.
detailsbooleanIf 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.
delegatorstringIf specified, indicate the conference owner. Delegation must have been set previously.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
ConferenceRequestapplication/json
Contains mandatory parameters and potentially optional ones to create a conference.
Response
codetypemedia typesdescription
201stringapplication/json
CREATED
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Create a conference

Associated notifications
POST/conferences
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
parametertypedescription
detailsbooleanIf 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.
loginNamestringLogin 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.
delegatorstringIf specified, indicate the conference owner. Delegation must have been set previously.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
iCalendartext/calendar
Represents the iCalendar stream.
Response
codemedia typesdescription
201application/json
CREATED
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Examples

[+] : Create a conference from an uploaded iCalendar

Associated notifications

/conferences/delegates

Methods
GET/conferences/delegates
Retrieve the delegates.
Licenses
The license CONFERENCE is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200ConferenceParticipantIdsapplication/json
OK
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
POST/conferences/delegates
Set delegation to participant(s).
Licenses
The license CONFERENCE is required.
Request
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
ConferenceParticipantIdsapplication/json
the participant Ids (ConferenceParticipantIds) to set as delegate.
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
DELETE/conferences/delegates
Unset delegation to participant(s).
Licenses
The license CONFERENCE is required.
Request
query parameters
parametertypedescription
partIdsstringlist of comma separated participants Ids to unset.
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/conferences/{conferenceId}

Methods
GET/conferences/{conferenceId}
Get a specific conference.
Licenses
The license CONFERENCE is required.
Request
path parameters
parametertypedescription
conferenceIdstringthe Id of the conference to retrieve.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200Conferenceapplication/json
OK
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
PUT/conferences/{conferenceId}
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
parametertypedescription
conferenceIdstringthe Id of the conference to modify.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
ConferenceRequestthe conference parameters to modify.
Response
the modified conference.
codetypemedia typesdescription
200Conferenceapplication/json
OK
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications
GET/conferences/{conferenceId}
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
parametertypedescription
conferenceIdstringthe Id of the conference to retrieve.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codetypemedia typesdescription
200iCalendartext/calendar
OK
400text/calendar
Bad Request
401text/calendar
Unauthorized
403text/calendar
Forbidden
500text/calendar
Internal Server Error
503text/calendar
Service Unavailable
DELETE/conferences/{conferenceId}
Delete a conference.
Licenses
The license CONFERENCE is required.
Request
path parameters
parametertypedescription
conferenceIdstring
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/conferences/{conferenceId}/documents

Methods
POST/conferences/{conferenceId}/documents
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
path parameters
parametertypedescription
conferenceIdstringthe conference Id.
query parameters
parametertypedescription
docTypeConferenceDocumentTypeThe type of document to upload.
loginNamestringLogin 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.
detailsbooleanIf true, the modified conference is included in the response (200 OK). If not set (or false), returned response is 204 No Content.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/conferences/{conferenceId}/documents/{documentId}

Methods
DELETE/conferences/{conferenceId}/documents/{documentId}
Remove a document from a conference.
Licenses
The license CONFERENCE is required.
Request
path parameters
parametertypedescription
conferenceIdstringthe conference Id.
documentIdstringthe Id of the document to remove.
query parameters
parametertypedescription
loginNamestringLogin 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.
detailsbooleanIf true, the modified conference is included in the response (200 OK). If not set (or false), returned response is 204 No Content.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/conferences/{conferenceId}/join

Methods
POST/conferences/{conferenceId}/join
Join the conference.
Licenses
The license CONFERENCE is required.
Request
path parameters
parametertypedescription
conferenceIdstringthe Id of the conference to join.
query parameters
parametertypedescription
loginNamestringLogin 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
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
JoinConferenceRequestthe parameters needed to join the conference.
Response
codemedia typesdescription
200application/json
No Content
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable

/conferences/{conferenceId}/participants

Methods
POST/conferences/{conferenceId}/participants
Add participant(s) to a conference.
Licenses
The license CONFERENCE is required.
Request
path parameters
parametertypedescription
conferenceIdstringthe conference Id.
query parameters
parametertypedescription
loginNamestringLogin 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.
detailsbooleanIf true, the modified conference is included in the response (200 OK). If not set (or false), returned response is 204 No Content.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
ConferenceParticipantsapplication/json
the participants (ConferenceParticipants) to add.
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications
DELETE/conferences/{conferenceId}/participants
Remove participant(s) from a conference.
Licenses
The license CONFERENCE is required.
Request
path parameters
parametertypedescription
conferenceIdstringthe conference Id.
query parameters
parametertypedescription
loginNamestringLogin 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.
partIdsstringlist of comma separated participants Ids to remove.
detailsbooleanIf true, the modified conference is included in the response (200 OK). If not set (or false), returned response is 204 No Content.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

/conferences/{conferenceId}/participants/promote

Methods
POST/conferences/{conferenceId}/participants/promote
Promote participant(s) as leader(s).
Licenses
The license CONFERENCE is required.
Request
path parameters
parametertypedescription
conferenceIdstringthe conference Id.
query parameters
parametertypedescription
loginNamestringLogin 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.
detailsbooleanIf true, the modified conference is included in the response (200 OK). If not set (or false), returned response is 204 No Content.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
body parameter
typemedia typesdescription
ConferenceParticipantIdsapplication/json
the participant Ids (ConferenceParticipantIds) to promote.
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications
DELETE/conferences/{conferenceId}/participants/promote
Demote participants from leader role.
Licenses
The license CONFERENCE is required.
Request
path parameters
parametertypedescription
conferenceIdstringthe conference Id.
query parameters
parametertypedescription
partIdsstringlist of comma separated participants Ids to demote.
loginNamestringLogin 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.
detailsbooleanIf true, the modified conference is included in the response (200 OK). If not set (or false), returned response is 204 No Content.
cookie parameters
parametertypedescription
AlcUserIdstringIdentifier of the Session
Response
codemedia typesdescription
204application/json
No Content
400application/json
Bad Request
401application/json
Unauthorized
403application/json
Forbidden
500application/json
Internal Server Error
503application/json
Service Unavailable
Associated notifications

Representations

boolean
'boolean' is a data type, having two values (true and false).
Conference
Descriptor of a conference. Contains all relevant information concerning a conference.
NameTypeCardinalityDescription
conferenceIdstring[0..1]Unique identifier of a conference. When creating a conference, this parameter should be null (will be ignored on server side).
callIdstring[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).
subjectstring[0..1]Subject of the conference. This is a brief description of the topic of a conference.
joinOnlineUrlstring[0..1]URL for joining the web conference (e.g. via a web browser).
leaderAccessCodestring[0..1]Leaders have to provide a specific access code when joining the conference.
participantAccessCodestring[0..1]Participant access code.
typeConferenceType[0..1]The type of the conference.
profileConferenceProfile[0..1]Profile of the conference. A profile is used to group a set of options.
ownerPartyInfo[0..1]Owner of the conference.
startDatestring[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.
endDatestring[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.
durationstring[0..1]Duration (ISO8601) of the conference, relative to the start date. Example: 'PT01H30M'
participantsConferenceParticipant[0..*]List of participants to the conference.
documentsConferenceDocument[0..*]List of the documents uploaded for the conference.
audioPasswordstring[0..1]If set, the user will have to enter the requested password when joining the audio conference.
webPasswordstring[0..1]If set, the user will have to enter the requested password when joining the web conference.
recurrenceRecurrence[0..1]The recurrence of this conference.
[+] : JSON Example
Associated methods :
ConferenceDocument
Descriptor for a conference document.
NameTypeCardinalityDescription
idstring[0..1]The Identifier of the document.
namestring[0..1]The name of the document.
typeConferenceDocumentType[0..1]The document type. Only supported types of document can be presented.
urlstring[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
ConferenceDocumentType
Conference document type.
ValueDescription
ATTACHMENTThe document is not one of the supported presentation format. It can be downloaded by participants.
PRESENTATIONThe 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_PRESENTATIONThe file can be downloaded as an attachment, but also be accessed slide by slide (presentation).
ConferenceParticipant
Conference Member descriptor. A conference member can be either a simple participant, or a leader.
NameTypeCardinalityDescription
partyPartyInfo[1]Party Info of the participant of a conference.
leaderboolean[0..1]Indicate if this is a simple participant (false) or a leader (true).
statusstring[0..1]This optional field can indicate the participant status (accepted / declined). It can be filled in case of interaction with other calendar providers.
[+] : JSON Example
ConferenceParticipantIds
Container for a list of members Ids of a conference.
NameTypeCardinalityDescription
participantIdsstring[0..*]List of participant Ids.
[+] : JSON Example
Associated methods :
ConferenceParticipants
Container for a list of members of a conference.
NameTypeCardinalityDescription
participantsConferenceParticipant[0..*]List of members of a conference.
[+] : JSON Example
Associated method :
ConferenceProfile
Conference profile is a convenient way of grouping a set of options on the conference server.
ValueDescription
MEETINGThe 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).
WEBINARThis 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).
TRAININGThis 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).
CONFCALLThis profile correspond to an audio only conference session.
ConferenceRequest
Descriptor of a conference request, used to create or modify a conference.
NameTypeCardinalityDescription
typeConferenceType[0..1]The type of the conference.
subjectstring[0..1]Subject of the conference. This is a brief description of the topic of a conference.
profileConferenceProfile[0..1]Profile of the conference. A profile is used to group a set of options.
startDatestring[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.
endDatestring[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.
durationstring[0..1]Duration (ISO8601) of the conference, relative to the start date. Example: 'PT01H30M'
recurrenceRecurrence[0..1]The recurrence of this conference.
All needed fields must be provided for conference creation or modification.
participantsConferenceParticipant[0..*]List of participants to the conference.
audioPasswordstring[0..1]If set, the user will have to enter the requested password when joining the audio conference.
webPasswordstring[0..1]If set, the user will have to enter the requested password when joining the web conference.
[+] : JSON Example
Associated methods :
Conferences
Container for a list of conferences.
NameTypeCardinalityDescription
conferencesConference[0..*]List of conferences
[+] : JSON Example
Associated method :
ConferenceType
Indicates the kind of conference the user wants to program.
ValueDescription
SCHEDULEDThis 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.
RESERVATIONLESSThis kind of conference can cover a larger period (e.g. 6 months). Refer to system administrator for the maximum duration of such conference.
iCalendar
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.
Identifier
Key information to help retrieving a participant.
NameTypeCardinalityDescription
loginNamestring[0..1]Login name.
phoneNumberstring[0..1]Company phone number.
instantMessagingIdstring[0..1]Instant messaging identity.
companyEmailstring[0..1]Company email.
[+] : JSON Example
int
'int' is a 32-bit number (-2147483648 to 2147483647).
JoinConferenceRequest
Container used for passing parameters to join a conference.
NameTypeCardinalityDescription
audioOnlyboolean[0..1]Join only the audio conference. Default is false.
webOnlyboolean[0..1]Join only the web conference. Default is false.
phonestring[1]Device phone number on which the audio conference bridge will call.
webPasswordstring[0..1]The password to join the web conference. If set during conference creation, audioPassword will be requested at TUI level.
[+] : JSON Example
Associated method :
OnConferenceCreated
Event sent when a new conference has been created.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnConferenceCreated'
loginNamestring[1]Login name of the user receiving the event.
conferenceConference[0..1]The newly created conference.
[+] : JSON Example
Associated methods :
OnConferenceDeleted
Event sent when a conference has been deleted.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnConferenceDeleted'
loginNamestring[1]Login name of the user receiving the event.
conferenceIdstring[0..1]The conferenceId of the deleted conference.
[+] : JSON Example
Associated method :
OnConferenceModified
Event sent when a conference has been modified.
NameTypeCardinalityDescription
eventNamestring[1]The name of the event : 'OnConferenceModified'
loginNamestring[1]Login name of the user receiving the event.
conferenceConference[0..1]The modified conference.
[+] : JSON Example
Associated methods :
PartyInfo
Full description of a party (i.e. participant's description).
NameTypeCardinalityDescription
idIdentifier[1]Key information to help retrieving a participant.
firstNamestring[0..1]First name of the participant.
lastNamestring[0..1]Last name of the participant.
displayNamestring[0..1]Display name of the participant.
[+] : JSON Example
Recurrence
NameTypeCardinalityDescription
typeRecurrenceType[1]DAILY, WEEKLY, MONTHLY, MONTHLY_BY_WEEK.
intervalint[1]Interval. Means 'every x days / weeks / months
daysOfTheWeekstring[0..*]List of named days used in weekly and monthly by week types. Named days are monday, tuesday, ... sunday.
dayOfTheMonthint[0..1]Day of the month used in monthly recurrence. E.g. Meeting every 15th of the month.
weekOfTheMonthint[0..1]Week of the month for monthly by week type. E.g. Meeting every month on monday of the 2nd week.
nbOfOccurencesint[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
RecurrenceType
The recurrence type.
ValueDescription
DAILYRecurrence is daily. Use in conjunction with interval. E.g. everyday, or every 2 days.
WEEKLYRecurrence is weekly. Use in conjunction with interval, daysOfTheWeek. E.g. every week on monday, or every 2 weeks on mondays and tuesday ...
MONTHLYRecurrence is monthly. Use in conjunction with interval, dayOfTheMonth. E.g. every month the 14th, or every 2 months the 15th.
MONTHLY_BY_WEEKRecurrence is monthly by week. Use in conjunction with interval, weekOfTheMonth, daysOfTheWeek. E.g. every 2nd month, the 3rd week, on monday and friday.
string
'string' represents character strings.