Introduction

Overview

• Some types can't have the right A4980 (Example: ANALOG).
• Directory number must be only digits to be monitored (Numbers without #, *, A, B, C or D char).

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

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

• CCD_LOAD_OPE_CCA: Indicates that devices with parameters ACT_Type=AGENT and Ope_Cca=TRUE are taken into account
• HOTEL_LOAD_Z_GUESTS: Indicates that devices with parameters Station_Type=ANALOG, Teleservice=Phone, Function=Room and Occupation_Type=Client are taken into account

History

• modified feature 'Session management'
  • added in representation 'SessionInfo' :
    • creationDate
    • otherSessions
• modified feature 'User information'
  • added in representation 'User' :
    • externalLogin
• modified feature 'Call control'
  • added methods :
    • Get pilot transfer information
• modified feature 'Maintenance'
  • added notifications :
    • OnServerStart
• modified feature 'Call Center Agent'
  • added notifications :
    • OnAgentSkillChanged
• modified feature 'Call Center RSI'
  • added in representation 'RouteRequest' :
    • hexaBinaryAssociateData
  • added in representation 'RouteSelect' :
    • hexaBinaryAssociatedData
• added feature 'Call Center Management'
• added feature 'Call Center Pilot'

• modified feature 'Call control'
  • added methods :
    • Push MICRO/ITH key
  • added in representation 'MakeCallRequest' :
    • secretIdentity
• modified feature 'Communication log'
  • added in representation 'ComHistoryRecord' :
    • convDate
• modified feature 'Call Center RSI'
  • added in representation 'RouteEnd' :
    • cause
  • added in representation 'RouteSelect' :
    • secretIdentity

Change logs

Authentication mechanism

• For a user, the QMCDU of the OXE subscriber prefixed by "oxe" (Ex: oxe70120)
• For an administrator, a login found (managed) in the configuration file

• For a user, the secret code of the OXE subscriber
• For an administrator, a password found (managed) in the configuration file

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

  Response :
  	200 OK 

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

Session creation

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

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

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

O2G Services Through Websocket

Error management

The complete list of REST API errors is the following:

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

{
	"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
}

{
	"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
}

High Availability (HA)

Client code samples

• JAVA samples
• JAVA Script (client side) sample
• PHP (server side) sample

Representations

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

{
   "httpStatus": "CONTINUE | SWITCHING_PROTOCOLS | PROCESSING | OK | CREATED | ACCEPTED | ...",
   "code": int,
   "helpMessage": "string",
   "type": "string",
   "innerMessage": "string",
   "canRetry": boolean,
   "routing": {
      "errorType": "UNKNOWN | BAD_PARAMETER_VALUE | UNAUTHORIZED | INVALID_OPERATION | ...",
      "destinationType": "OFFICE | MOBILE | VOICEMAIL | NUMBER | UNKNOWN",
      "errorCause": "UNKNOWN | BAD_PHONE_NUMBER_FORMAT | INVALID_CURRENT_DEVICE | ...",
      "message": "string"
   },
   "telephony": {
      "errorType": "UNKNOWN | CALL_REFERENCE_NOT_FOUND | LEG_NOT_FOUND | BAD_PARAMETER_VALUE | ...",
      "errorCause": "UNKNOWN | INVALID_CALLING | INVALID_DESTINATION | INVALID_CALL_ID | ...",
      "message": "string"
   },
   "userPreferences": {
      "errorType": "UNKNOWN | WRONG_VALUE | WRONG_NUMBER_FORMAT",
      "parameter": "GUI_LANGUAGE"
   }
}

{
   "errorType": "UNKNOWN | BAD_PARAMETER_VALUE | UNAUTHORIZED | INVALID_OPERATION | ...",
   "destinationType": "OFFICE | MOBILE | VOICEMAIL | NUMBER | UNKNOWN",
   "errorCause": "UNKNOWN | BAD_PHONE_NUMBER_FORMAT | INVALID_CURRENT_DEVICE | ...",
   "message": "string"
}

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

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

{
   "errorType": "UNKNOWN | CALL_REFERENCE_NOT_FOUND | LEG_NOT_FOUND | BAD_PARAMETER_VALUE | ...",
   "errorCause": "UNKNOWN | INVALID_CALLING | INVALID_DESTINATION | INVALID_CALL_ID | ...",
   "message": "string"
}

{
   "errorType": "UNKNOWN | WRONG_VALUE | WRONG_NUMBER_FORMAT",
   "parameter": "GUI_LANGUAGE"
}

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

Session management

Presentation

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

Resources summary

Resources

/sessions

Methods

POST https://server/api/rest/1.0/sessions
  Content-Type: application/json
  {
  "applicationName":"TESTS_API"
  }

200 OK
  Content-Type:  application/json
	{
  "timeToLive": 1800,
  "publicBaseUrl": "http://public-server/api/rest/1.0",
  "privateBaseUrl": "https://server/api/rest/1.0",
  "services": [
    {
      "serviceName": "Users",
      "serviceVersion": "1.0",
      "relativeUrl": "/users"
    },
    {
      "serviceName": "Telephony",
      "serviceVersion": "1.0",
      "relativeUrl": "/telephony/calls"
    },
    {
      "serviceName": "Logins",
      "serviceVersion": "1.0",
      "relativeUrl": "/logins"
    },
    {
      "serviceName": "Devices",
      "serviceVersion": "1.0",
      "relativeUrl": "/telephony/devices"
    },
    {
      "serviceName": "State",
      "serviceVersion": "1.0",
      "relativeUrl": "/telephony/state"
    },
    {
      "serviceName": "Directory",
      "serviceVersion": "1.0",
      "relativeUrl": "/directory"
    },
    {
      "serviceName": "EventSummary",
      "serviceVersion": "1.0",
      "relativeUrl": "/eventSummary"
    },
    {
      "serviceName": "Routing",
      "serviceVersion": "1.0",
      "relativeUrl": "/routing"
    },
    {
      "serviceName": "Subscriptions",
      "serviceVersion": "1.0",
      "relativeUrl": "/subscriptions"
    },
    {
      "serviceName": "Comlog",
      "serviceVersion": "1.0",
      "relativeUrl": "/comlog/records"
    }
  ]
  }

POST https://server/api/rest/1.0/sessions
  Content-Type: application/json
  {
   "applicationName":"TESTS_API"
  }

200 OK
  Content-Type:  application/json
  {
   "admin": true,
    "timeToLive":"1800",
    "publicBaseUrl":"https://public-server/api/rest/1.0",
    "privateBaseUrl":"https://server/api/rest/1.0",
    "Services":
   [
     {
       "serviceName":"Users",
       "serviceVersion":"1.0",
       "relativeUrl":"/logins"
     },
     
     .....
     
     {
       "serviceName":"Telephony",
       "serviceVersion":"1.0",
       "relativeUrl":"/telephony/calls"
     }
   ]
 }

POST https://server/api/rest/1.0/sessions
  Content-Type: application/json
  {
    "applicationName":"TESTS_API",
    "supervisedAccount":
    {
     "id":"oxe70020",
     "type":"LOGIN_NAME"
    }
  }

200 OK
  Content-Type:  application/json
  {
    "timeToLive":"1800",
    "publicBaseUrl":"https://public-server/api/rest/1.0",
    "privateBaseUrl":"https://server/api/rest/1.0",
    "Services":
   [
     {
       "serviceName":"Users",
       "serviceVersion":"1.0",
       "relativeUrl":"/logins"
     },
     
     .....
     
     {
       "serviceName":"Telephony",
       "serviceVersion":"1.0",
       "relativeUrl":"/telephony/calls"
     }
   ]
 }

POST https://server/api/rest/1.0/sessions
  Content-Type: application/json
  {
   "applicationName":"[clear part]f80fumpxLtf71YqxWNcu6PyW+1PvPTq2sZeR+Z+8c9IAgu7KkIhfAEIgpXx+ADbhM..."
  }

200 OK
  Content-Type:  application/json
  {
    "timeToLive":"1800",
    "publicBaseUrl":"https://public-server/api/rest/1.0",
    "privateBaseUrl":"https://server/api/rest/1.0",
    "Services":
   [
     {
       "serviceName":"Users",
       "serviceVersion":"1.0",
       "relativeUrl":"/logins"
     },
     
     .....
     
     {
       "serviceName":"Telephony",
       "serviceVersion":"1.0",
       "relativeUrl":"/telephony/calls"
     }
   ],"expirationDate":"2018-12-07"
 }

POST https://server/api/rest/1.0/sessions
  Content-Type: application/json
  {
   "applicationName":"TESTS_API"
  }

200 OK
  Content-Type:  application/json
  {
   "admin": true,
    "timeToLive":"1800",
    "publicBaseUrl":"https://public-server/api/rest/1.0",
    "privateBaseUrl":"https://server/api/rest/1.0",
    "Services":
   [
     {
       "serviceName":"Users",
       "serviceVersion":"1.0",
       "relativeUrl":"/logins"
     },
     
     .....
     
     {
       "serviceName":"Telephony",
       "serviceVersion":"1.0",
       "relativeUrl":"/telephony/calls"
     }
   ],
    "creationDate": "2023-08-07T14:13:36Z",
 "otherSessions": [
 	{
 		"sessionId": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJpbnRlcm5hbDI5IiwiaWF0IjoxNjkxNDE1OTYxfQ.CfGGFrfNuy46spQww6mw_bd6wqaRdpetPXHGZheKUi8",
 		"creationDate": "2023-08-07T13:46:14Z",
 		"timeToLive": 1426
 	},
 	{
 		"sessionId": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJpbnRlcm5hbDI5IiwiaWF0IjoxNjkxNDEyNTU0fQ.TmVCsB6goObhgoZ9evDe9X1SNFnNOV5PVYiIwOTQ_X0",
 		"creationDate": "2023-08-07T13:29:21Z",
 		"timeToLive": 1607
 	}
 ]
 }

/sessions/keepalive

Methods

POST https://server/api/rest/1.0/sessions/keepalive

204 No Content

Representations

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

Session information.

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

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

Associated methods :

• GET /sessions
• POST /sessions

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

{
   "expirationDate": "string"
}

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

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

User information

Presentation

The User service allows

• an administrator to retrieve the list of O2G users.
• a user to get information on another user account.
• a user to change its password or some parameter like supported language.

Resources summary

Notifications summary

Resources

/logins

Methods

GET https://server/api/rest/1.0/logins

200 OK
 Content-Type:  application/json
 {
   {"loginNames":["oxe70020"]}
 }

GET https://server/api/rest/1.0/logins

200 OK
 Content-Type:  application/json
 {
  {"loginNames":["oxe70020","oxe70021","oxe70022"]}
 }

GET https://server/api/rest/1.0/logins?nodeIds=7,8

200 OK
 Content-Type:  application/json
 {
  {"loginNames":["oxe70020","oxe70021","oxe70022"]}
 }

GET https://server/api/rest/1.0/logins?onlyACD

200 OK
 Content-Type:  application/json
 {
  {"loginNames":["oxe60114","oxe60113","oxe60112"]}
 }

GET https://server/api/rest/1.0/logins?nodeIds=5,7&onlyACD

200 OK
 Content-Type:  application/json
 {
  {"loginNames":["oxe60114","oxe60113"]}
 }

/users

Methods

GET https://server/api/rest/1.0/users?companyPhone=70121

200 OK
 Content-Type:  application/json
 {
  "companyPhone":"70121",
  "firstName":"N70121",
  "lastName":"L70121",
  "loginName":"oxe70121",
  "apiRights":[],"nodeId":"7"
  }

/users/{loginName}

Methods

GET https://server/api/rest/1.0/users/oxe70120

200 OK
 Content-Type:  application/json
 {
 	"companyPhone":"70120",
 	"firstName":"F70120",
 	"lastName":"L70120",
 	"loginName":"oxe70120",
 	"devices":[{"type":"DESKPHONE","id":"70120","label":"POC","subType":"NOE_C_Color_IP"}],
 	"apiRights":[],"nodeId":"7"
 }

/users/{loginName}/password

Methods

/users/{loginName}/preferences

Methods

GET https://server/api/rest/1.0/users/oxe70020/preferences

200 OK
 Content-Type:  application/json
 {
   "guiLanguage":"en_GB"
 }

POST https://server/api/rest/1.0/users/oxe70020/preferences
 
 Content-Type:  application/json
 {
 	 "guiLanguage":"en_GB"
 }

204 No Content

/users/{loginName}/preferences/supportedLanguages

Methods

GET https://server/api/rest/1.0/users/oxe70020/preferences/supportedLanguages

200 OK
 Content-Type:  application/json
 {"supportedLanguages":["fr","en-gb","de","es","pt","it"]}

Representations

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

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

{
   "loginNames": [ "string" ]
}

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

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

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

{
   "supportedLanguages": [ "string" ],
   "supportedGuiLanguages": [ "string" ]
}

The description of a user

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

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

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

Associated methods :

• GET /users
• GET /users/{loginName}

{
   "guiLanguage": "string",
   "oxeLanguage": "string"
}

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

Subscription management

Presentation

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

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

• Have an opened framework session.
• Have subscribed to the set of events he wants to be notified on.
• Have received an ACCEPTED subscription response from the server.

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

• telephony [OnCallCreated, OnCallModified, OnCallRemoved, OnUserStateModified, OnDeviceStateModified, OnTelephonyState, OnDynamicStateChanged ]: ROXE_API_TEL_ADVANCED license required
• eventSummary [OnEventSummaryUpdated]: ROXE_API_TEL_ADVANCED license required
• unifiedComLog [OnComRecordCreated, OnComRecordModified, OnComRecordsDeleted, OnComRecordsAck, OnComRecordsUnAck]: ROXE_API_TEL_ADVANCED license required
• user [OnUserInfoChanged]: no license required
• userManagement [OnUserCreated, OnUserDeleted]: no license required
• routingManagement [OnRoutingStateChanged]: ROXE_API_TEL_ADVANCED license required
• agent [OnAgentStateChanged, OnSupervisorHelpRequested, OnSupervisorHelpCancelled, OnAgentSkillChanged]: ROXE_API_CONTACTCENTER_AGENT license required
• rsi [OnRouteRequest,OnRouteEnd,OnToneGeneratedStart,OnToneGeneratedStop,OnDigitCollected] The required licenses will only be taken by invocations of the methods associated with this feature
• pilot [OnPilotCallCreated,OnPilotCallQueued,OnPilotCallRemoved] The required licenses will only be taken by invocations of the methods associated with this feature
• system [OnLicenseExpiration,OnPbxLoaded,OnCtiLinkDown,OnCtiLinkUp]: no license required
• pbxManagement [OnPbxObjectInstanceCreated,OnPbxObjectInstanceModified,OnPbxObjectInstanceDeleted]: no license required

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

• For pbxManagement and system packages, a selector contains the "names" attribute which is either the event package name or a list of corresponding events. The "ids" attributes MUST be absent.
• For rsi package, no license will be taken. The licenses will be taken upon invoking the methods of this feature. The "ids" are RSI directory numbers.
• For pilot package, no license will be taken. The licenses will be taken upon invoking the methods of this feature. The "ids" are acd pilot object phone numbers.
• For the other packages, a selector MUST contain a list of "ids" (i.e. logins), and either a list of "names" corresponding to one or several event names of the same package or an event package name.

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

A subscription request includes other fields such as:

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

A subscription response will provide following information to the user:

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

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

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

NOTE1: License count check for administrator session.
An administrator can subscribe to event notification concerning a subset of users. Only one license per package will be taken, but the amount of supervised users can not exceed the number of TELEPHONY_ADVANCED licenses installed on the server.
The following rules apply when checking if the limit is reached or not:

• The counter is increased when a user is part of an administrator's subscription for the first time.
• The counter is decreased when the last administrator's subscription is removed for a given user.
• The whole subscription is refused if the content will make the counter exceed the installed number of licenses.

Resources summary

Resources

/subscriptions

Methods

POST https://server/api/rest/1.0/subscriptions
 	Content-Type: application/json
 	{
  "filter": {
	  "selectors": [ 
       {"ids": [ "userA" ],"names": [ "telephony" ]},
       {"ids": [ "userA" ],"names": [ "eventSummary" ]}
     ]
  },
  "version":"1.0"
 }

200 OK
 	{
 		"subscriptionId":"...93231353535373132393",
 		"publicPollingUrl":"https://public.server:8016/OTEvents?subscriptionId=...93231353535373132393",
 		"privatePollingUrl":"https://server:8016/OTEvents?subscriptionId=...93231353535373132393",
 		"status":"ACCEPTED",
 		"mode":"CHUNK", "format":"JSON"
 	}

POST https://server/api/rest/1.0/subscriptions
  Content-Type: application/json
  {
  "filter":{"selectors":[
  	{"ids":["userA","userB","userC"],"names":["telephony"],"families":[],"origins":[]},
  	{"ids":["userA","userB","userC"],"names":["eventSummary"],"families":[],"origins":[]},
  	{"ids":["userA","userB","userC"],"names":["user"],"families":[],"origins":[]}]
  },
  "sessionId":"...2303639373638343","version":"1.0",
  "timeout":60}
  }

400 BadRequest
	{
 		"subscriptionId":"...2303639373638343", 
 		"message":"SUBSCRIPTION_NOT_DONE: Max nb of license used for notification.",
 		"status":"REFUSED","mode":"CHUNK","format":"JSON"
  }

POST https://server/api/rest/1.0/subscriptions
  Content-Type: application/json
  {
  	"filter":{"selectors":[
  		{"ids":["*"],"names":["telephony"],"families":[],"origins":[]}
  	},
  	"sessionId":"...2303639373638343","version":"1.0",
  	"timeout":60
  }
  }

POST https://server/api/rest/1.0/subscriptions
  Content-Type: application/json
  {
		"filter": {
		 "selectors": [ 
			  {"names": [ "system" ]}
		]
		},
		"version":"1.0"
	}

POST https://server/api/rest/1.0/subscriptions
  Content-Type: application/json
  {
		"filter": {
		 "selectors": [ 
			  {"names": [ "pbxManagement" ]}
		]
		},
		"version":"1.0"
	}

POST https://server/api/rest/1.0/subscriptions
  Cookie: AlcUserId=eyJhbGciOiJIUzI.....
  Content-Type: application/json
  {
		"filter": {
		 "selectors": [ 
			  {"names": [ "pbxManagement" ]}
		]
		},
		"version":"1.0",
  	"webHookUrl": "https://[@IP address]:8091/webHookOTEvent"
	}

POST /webHookOTEvent HTTP/1.1
  Cookie: AlcUserId%3DeyJhbGciOiJIUzI...
  Content-type: application/json
  {"eventName":...

POST https://server/api/rest/1.0/subscriptions
  Content-Type: application/json
  {
		"filter": {
		 "selectors": [ 
			{"ids": [ "60141" ],"names": [ "pilot"]},
      	{"ids": [ "65000" ],"names": [ "rsi"]}
		]
		},
		"version":"1.0"
	}

PUT https://server/api/rest/1.0/subscriptions
 	Content-Type: application/json
 	{
 		"selectors":[
 			{"ids":["userA","userB"],"names":["telephony"]},
 			{"ids":["userA","userB"],"names":["eventSummary"]}
 		]
 	}

204 No Content

/subscriptions/{subscriptionId}

Methods

DELETE https://server/api/rest/1.0/subscriptions/...35373132393

204 No Content

Representations

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

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

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

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

Call control

Presentation

The Telephony service allows a user to initiate a call and to activate any kind of pbx telephony service.

Resources summary

Notifications summary

Resources

/telephony/basicCall

Methods

POST https://server/api/rest/1.0/telephony/basicCall
 Content-Type:  application/json
 {
   "deviceId": "70021",
   "callee": "70022",
   "autoAnswer": true
 }

201 Created
 Location: http://server/api/rest/1.0/telephony/basicCall/2db0a05647030100

POST https://server/api/rest/1.0/telephony/basicCall
 Content-Type:  application/json
 {
   "deviceId": "70060",
   "callee": "70022"
 }

204 No Content

/telephony/basicCall/answer

Methods

/telephony/basicCall/dropme

Methods

/telephony/calls

Methods

POST https://server/api/rest/1.0/telephony/calls
 Content-Type:  application/json
 {
   "deviceId": "70021",
   "callee": "70022",
   "autoAnswer": true
 }

201 Created
 Location: http://server/api/rest/1.0/telephony/calls/49bfa0564a030100

POST https://server/api/rest/1.0/telephony/calls
 Content-Type:  application/json
 {
   "deviceId": "70021",
   "callee": "70022",
   "pin": "01222",
   "secretCode": "0124"
 }

201 Created
 Location: http://server/api/rest/1.0/telephony/calls/e4c3a0564c030100

POST https://server/api/rest/1.0/telephony/calls
 Content-Type:  application/json
 {
   "deviceId": "70021",
   "callee": "70022",
   "businessCode": "0124"
 }

201 Created
 Location: http://server/api/rest/1.0/telephony/calls/e5c3a0564c030100

POST https://server/api/rest/1.0/telephony/calls
 Content-Type:  application/json
 {
   "deviceId": "70060",
   "autoAnswer": true,
   "acdCall": {
   	"callToSupervisor": true
   }
 }

204 No Content

POST https://server/api/rest/1.0/telephony/calls
 Content-Type:  application/json
 {
   "deviceId": "70060",
   "callee": "60112",
   "autoAnswer": true,
   "associatedData": "unechaine"
 }

204 No Content

POST https://server/api/rest/1.0/telephony/calls
 Content-Type:  application/json
 {
   "deviceId": "70060",
   "callee": "60112",
   "autoAnswer": true,
   "hexaBinaryAssociatedData": "f1f200a0b3"
 }

204 No Content

/telephony/calls/{callRef}

Methods

/telephony/calls/{callRef}/alternate

Methods

/telephony/calls/{callRef}/answer

Methods

/telephony/calls/{callRef}/attachdata

Methods

POST https://server/api/rest/1.0/telephony/calls/e4c3a0564c030100/attachdata
 Content-Type:  application/json
 {
 	"deviceId": "70125",
  "associatedData":"this is my data"
 }

204 No Content

POST https://server/api/rest/1.0/telephony/calls/e4c3a0564c030100/attachdata
 Content-Type:  application/json
 {
 	"deviceId": "70125",
  "associatedData": "unechaine",
 }

204 No Content

POST https://server/api/rest/1.0/telephony/calls/e4c3a0564c030100/attachdata
 Content-Type:  application/json
 {
 	"deviceId": "70125",
  "hexaBinaryAssociatedData": "f0a4f900b3"
 }

204 No Content

/telephony/calls/{callRef}/blindtransfer

Methods

/telephony/calls/{callRef}/callback

Methods

/telephony/calls/{callRef}/deviceLegs

Methods

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

Methods

POST https://server/api/rest/1.0/telephony/calls/e4c3a0564c030100/deviceLegs/70123
 Content-Type:  application/json
 {
 	"otherDeviceId": "70125"
 }

204 No Content

/telephony/calls/{callRef}/dropme

Methods

/telephony/calls/{callRef}/hold

Methods