Introduction

Overview

• Required license : No license required (free).

• Required license : [license name] - True.

• Required license : [license name] - one license per user.

• Required license : [license name] - number of licenses greater than or equal to total number of OXE users on all OXE nodes.
• Required license : [license name] - number of licenses must be equal to total OXE users.

• Required license : [license name] - N licenses required.

• <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

• added feature 'User Management'
• modified feature 'Call control'
  • added in representation 'Identifier' :
    • multiLine
• modified feature 'Maintenance'
  • added in representation 'DRLink' :
    • initiator
  • added in representation 'SystemStatus' :
    • recordingStatus
• modified feature 'Call Center Agent'
  • added methods :
    • Cancel Agent Permanent listening
  • added in representation 'IntrusionMode' :
    • STOP
• modified feature 'Call Center Management'
  • added methods :
    • Get advanced pilot information

• modified feature 'Call control'
  • added in representation 'DeviceState' :
    • cause
• modified feature 'Call Center Pilot'
  • added methods :
    • MonitorStart pilot
    • MonitorStop pilot
  • added in notification 'OnPilotCallCreated' :
    • callData

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

• modified feature 'Session management'
  • added in representation 'SessionInfo' :
    • creationDate
    • otherSessions
• modified feature 'User information'
  • added in representation 'User' :
    • externalLogin
• modified feature 'User Management'
  • 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
• added feature 'Call Center Management'
• added feature 'Call Center Pilot'

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: (server address)
Cookie: AlcUserId=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJpbnRlcm5...
...
{
[body] : refer to Session Management section
}

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

O2G Services Through Websocket

Error management

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

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

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

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

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

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

User Management

Presentation

The User Management service allows an administrator to create/delete/get the O2G users.
O2G allows to create O2G users according to different methods:

• automatically when O2G starts, according to automatic user creation mode (through roxe-config.sh) which be can be:
  • ALL : all the OXE subscribers are taken in account without any filter.
  • 4980 : only the OXE subscribers with A4980 attribute set with a value different from NO_4980 are taken in account. This is the default mode.
  • NONE : no user is automatically created from OXE subscriber.
• through provisioning files. They have to be uploaded, one file per oxe node in /var/data/roxe/userprov/oxe.[nodeNbr], where [nodeNbr] is the unique node number of the oxe. One or several files respecting this naming may be set.
  Example:
  - /var/data/roxe/userprov/oxe.5
  - /var/data/roxe/userprov/oxe.101
  In order to take in account all the subscribers of an oxe, create an empty file.
  To define a list of devices to create, the content of the file MUST respect the following format CSV text on one or several lines, each element is:
  • a single device_Number
  • or a range [first number of the device range]-[size of the range]
  Example:
  40000-1000,50000-50
  60001,60002,60003,70000-10,80000-100
  90001,90002
  
  (The subscriber numbers which are not valid are ignored)
• or on demand through this REST service: the service allows to create one user, a list of users or all the users.

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

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

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

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

GET https://server/api/rest/1.0/usermanagement?deviceNumber=70124

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

POST https://server/api/rest/1.0/usermanagement
 {"nodeId":"7","deviceNumbers":["70120"]}

200 Ok : the new created user
 Content-Type:  application/json
 {
 	"companyPhone":"70120",
 	"firstName":"F70120",
 	"lastName":"L70120",
 	"loginName":"oxe70120",
 		"voicemail": {
 		"number": "885",
		"voicemailtype": "VM_4645"
		},
 	"devices":[{"type":"DESKPHONE","id":"70120","label":"POC","subType":"NOE_C_Color_IP"}],
 	"nodeId":"7",
 	"externalLogin":"user70120@my.domain.com"
 }

POST https://server/api/rest/1.0/usermanagement
 {"nodeId":"7","deviceNumbers":["70124"]}

200 Ok : the new created user
 Content-Type:  application/json
 {
 "users": [
 {
   "companyPhone": "70123",
   "firstName": "F70123",
     "lastName": "L70123",
      "loginName": "oxe70123",
      "voicemail": {
			"number": "885",
		 	"voicemailtype": "VM_4645"
  	},
    "devices": [
        {
              "type": "DESKPHONE",
              "id": "70124",
             	"subType": "NOE_C_Color_IP"
         },

         {
         "type": "DESKPHONE",
         "id": "70125",
         "subType": "NOE_C_Color_IP"
         },
         {
         "type": "DESKPHONE",
         "id": "70123",
         "subType": "NOE_C_Color_IP"
         }
 	],
   "nodeId": "7",
   "externalLogin": ""
  }
 ]
}

POST https://server/api/rest/1.0/usermanagement
 {"nodeId":"7","deviceNumbers":["70120",70121,70122,70123]}

200 Ok : the new created users
 Content-Type:  application/json
 {
 "users": [
 {
   "companyPhone": "70120",
   ...

POST https://server/api/rest/1.0/usermanagement
 {"nodeId":"7","all":true}

200 Ok : the new created users
 Content-Type:  application/json
 {
 "users": [
 {
   "companyPhone": "70120",
   ...

GET https://server/api/rest/1.0/usermanagement/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"
 }

DELETE https://server/api/rest/1.0/usermanagement/oxe1000

204 No Content

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

{
   "loginNames": [ "string" ]
}

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

{
   "nodeId": int,
   "deviceNumbers": [ "string" ],
   "all": boolean
}

{
   "users": [ {
      "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"
   } ]
}

{
   "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 ]
• eventSummary [OnEventSummaryUpdated]
• unifiedComLog [OnComRecordCreated, OnComRecordModified, OnComRecordsDeleted, OnComRecordsAck, OnComRecordsUnAck]
• user [OnUserInfoChanged]
• userManagement [OnUserCreated, OnUserDeleted, OnUserInfoChanged ]
• routingManagement [OnRoutingStateChanged]
• agent [OnAgentStateChanged, OnSupervisorHelpRequested, OnSupervisorHelpCancelled , OnAgentSkillChanged ]
• rsi [OnRouteRequest,OnRouteEnd,OnToneGeneratedStart,OnToneGeneratedStop,OnDigitCollected]
• pilot [OnPilotCallCreated,OnPilotCallQueued,OnPilotCallRemoved]
• system [ OnLicenseExpiration,OnPbxLoaded,OnCtiLinkDown,OnCtiLinkUp]
• pbxManagement [OnPbxObjectInstanceCreated,OnPbxObjectInstanceModified,OnPbxObjectInstanceDeleted]

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 not possible to mix event names of different packages inside the same selector: different selectors must be used in such case.

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

A subscription request includes other fields such as:

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

A subscription response will provide following information to the user:

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

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

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

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

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

Resources

/subscriptions

Methods

POST/subscriptions

Create a subscription for event notification.

Licenses

Required in CAPEX mode (FlexLM server): ROXE_API_TEL_ADVANCED or/and ROXE_API_CONTACTCENTER_AGENT - one license per user.
Required in OPEX mode (LMS server): api-tel-f - one license per user.

Request

header parameters

parameter	type	description
Authorization	string

cookie parameters

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

body parameter

type	media types	description
SubscriptionRequest	application/json

Response

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

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

Examples

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

request :

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

response :

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

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

request :

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

response :

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

request :

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

response :

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

request :

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

response :

[+] : Create a subscription with webhook on https address (and port=8091)

request :

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

response :

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

[+] : Create a subscription to pilot and rsi event packages.

request :

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

response :

Associated notifications

OnCallCreated, OnCallModified, OnUserStateModified

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, ...).

Licenses

Required in CAPEX mode (FlexLM server): ROXE_API_TEL_ADVANCED or/and ROXE_API_CONTACTCENTER_AGENT - one license per user.
Required in OPEX mode (LMS server): api-tel-f - one license per user.

Request

cookie parameters

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

body parameter

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

Response

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

Examples

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

request :

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

response :

204 No Content

/subscriptions/{subscriptionId}

Methods

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

Required in CAPEX mode (FlexLM server): No license required (free).
Required in OPEX mode (LMS server): No license required (free).

Request

path parameters

parameter	type	description
subscriptionId	string	The identifier of the subscription.

cookie parameters

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

Response

The result code.

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

Examples

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

request :

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

response :

204 No Content

Representations

Filter

High level container of event selector.

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

[+] : JSON Example { "selectors": [ { "ids": [ "string" ], "names": [ "string" ] } ] }

Associated method :

• PUT /subscriptions

int

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

Selector

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

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

[+] : JSON Example { "ids": [ "string" ], "names": [ "string" ] }

string

'string' represents character strings.

Subscription

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

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

[+] : JSON Example { "subscriptionId": "string", "message": "string", "publicPollingUrl": "string", "privatePollingUrl": "string", "status": "UNKNOWN | ACCEPTED | REFUSED" }

Associated method :

• POST /subscriptions

SubscriptionRequest

Contains all information needed for subscription to event notification.

Name	Type	Cardinality	Default	Description
filter	Filter	[0..1]		List of selector used to filter events.
sessionId	string	[0..1]		Reserved: DO NOT USE.
version	string	[1]		The version of the events the user wants to subscribe to.
timeout	int	[0..1]	10	Default lifetime of the channel opened between the server and the client. After that time, in minutes, the server closes the connection in case of no activity. 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. A KeepAlive event is sent by the server to maintain the connection.
webHookUrl	string	[0..1]		If specified, the events corresponding to this subscription will be sent on this URL by callback

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

Associated method :

• POST /subscriptions

SubscriptionState

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

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

Call control

Presentation

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

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

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

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

GET https://server/api/rest/1.0/telephony/calls/0ba25a675f050700?loginName=oxe70121

200 OK
 {
 "callRef":"0ba25a675f050700","callData":{"initialCalled":{"id":
 ....
 }