You can use the Communications Enabled Applications (CEA) feature to integrate either web telephony or web collaboration into applications using a Representational State Transfer (REST) API. REST is a network architecture that defines how resources on the Internet are accessed. REST is not a standard, but uses common Internet standards such as HTTP and HTML.
The following tables show the REST APIs and commands used in CEA, including a generic list of each aspect of the requests and responses. Also see the information on accessing telephony and data sharing browser sessions using REST APIs.
HTTP Method and URI | Description |
---|---|
PUT /collaborationSession | Enable collaboration |
GET /collaborationSession; <encodedSession> | Get collaboration status |
GET /collaborationSession; <encodedPeerAddressOfRecord> | Start a collaboration session with a peer |
DELETE /collaborationSession; <encodedSession> | End a collaboration session |
POST /collaborationSession/data; <encodedSession> | Send data to the collaboration peer |
GET /event; <encodedSession> | Retrieve event data (call status, collaboration status, collaboration data) |
PUT /call | Make a call |
GET /call; <encodedSession> | Get status on an active call |
DELETE /call; <encodedSession> | End a call |
PUT /callNotification | Register for call notification |
GET /callNotification; <encodedSession> | Get call notification information |
DELETE /callNotification; <encodedSession> | Unregister for call notification |
http://host:port/commsvc.rest/CommServlet/collaborationSession?JSON=true&addressOfRecord=tel:987654321
Parameter | Applicable HTTP Method and URI | Description |
---|---|---|
JSON | All | Optional parameter that you can use on any REST request. When the JSON parameter is detected and set to true, the REST response is formatted as JSON; otherwise XML. The presence of this parameter does not affect the format of the request. |
addressOfRecord | PUT /collaborationSession | Optional parameter when enabling collaboration. It allows the specified value to be used as an identifier of the session. This identifier gets exposed to other users of collaboration. If absent, a random identifier is created. Whether specified or not, the identifier is returned in the response as the collaborationId. |
peerAddressOfRecord | GET /collaborationSession | Required parameter when starting a collaboration session with a peer. It represents the identifier of the peer to which a collaboration must be established. This identifier is the collaborationId that was returned to the peer when the peer enabled collaboration. |
returnAllEvents | GET /event; <encodedSession> | Optional parameter used to get new events. If set to true, all available events are returned. Otherwise, only the next single event is returned. If this parameter is not used, the default is to return a single event. |
ceaVersion | All | Required parameter used to declare the version of the client sending the request. It is used to support backward compatibility. |
replaceRequest | GET /event; <encodedSession> | Optional parameter used to force a new GET /event request to replace an outstanding GET /event request. The outstanding request gets a 304 error response. |
With some REST APIs, additional information is provided in the body of the HTTP message, which must be formatted as either XML or JSON. The following table explains those request fields. Some fields are specific to web telephony or web collaboration while others apply to both. As another reference, see the schema that describes the REST requests and response format. It is called CommServletSchema.xsd and can be found in the WebSphere® Application Server installation directory under /etc/cea/schema.
Request fields | Applicable HTTP Method and URI | Description |
---|---|---|
addressOfRecord | PUT /call |
Required when making a call or registering for call notification. It represents the address of record of the phone making the call, or the phone registering for call notification. Common to all address of record references in this REST API, the values can be either SIP or TEL URIs. |
peerAddressOfRecord | PUT /call | This field is required when making a call. It represents the address of record of the phone to be called. |
collaborationData | POST /event; <encodedSession> | This field is required when sending data to a collaboration peer. It represents the data being sent. |
enableCollaboration | PUT /call |
Optional when either making a call or registering for call notification. It allows collaboration to be enabled at the same time. |
peerDeviceControlled | PUT /call | By default, PUT /call causes the device associated with the addressOfRecord to be controlled and originate the call. When peerDeviceControlled is set to true, the device associated with the peerAddressOfRecord is controlled and originates the call. |
The response to the REST API is described in the following table. As with the request fields, some response fields are specific to web telephony or web collaboration, while others apply to both. Many of the response fields include URIs that can be used in follow on REST requests. They are encoded to ensure that subsequent requests, related to the originally passed in address of record, remain associated with the same session. As another reference, see the schema that describes the REST requests and response format. It is called CommServletSchema.xsd and can be found in the WebSphere Application Server installation directory under /etc/cea/schema.
Response field | Applicable HTTP Method and URI | Description |
---|---|---|
infoMsg | All | Message indicating the results of the requested operation. |
returnCode | All | Number that represents the result of the requested operation. For example, when a request operation completes successfully, the response is 200. This full list of return codes can be seen in the REST interface schema. See table 5 for a complete list. |
eventList | GET /event | Array of events (web collaboration data available,
web collaboration status or call status changes) used in response
to GET /event. Each event has three fields: type, data, and infoMsg.
The different types include call status, collaboration status and
collaboration data. The data is dependent on the event type, but is
similar to the REST response fields of callStatus and collaborationStatus,
or the data sent with POST /event. The infoMsg is additional information
about the event. The following is a JSON formatted eventList: [{"type":2, "data": "information from peer", "infoMsg": "Successfully fetched data"}] Possible event types based on their
enum values include:
0: Data Event |
eventUri | All except GET /event | This encoded URI is returned from multiple REST APIs. It can be used to post new data in a collaboration session or to poll an event, such as a change in call status, change in collaboration status, or new data becoming available in a collaboration session. It doesn't return immediately. It will wait for an event to occur before a response is sent, or when a configured amount of time transpires. You can configure the time from the administrative console and is called the Maximum hold time. |
callerAddressOfRecord | All including /call or /callNotification in the URI | Address of record for the calling phone. |
calleeAddressOfRecord | All including /call or /callNotification in the URI | Address of record for the phone that was called. |
callServiceUri | All including /call or /callNotification in the URI | Encoded URI is returned from the make a call request, used for getting status on, or ending a call. |
callNotifyUri | All except GET /event | This encoded URI is returned from registering for call notification, used for monitoring a phone to see if a call has arrived or to unregister call notification. |
callId | All including /call or /callNotification in the URI when a call is active | Call ID associated with the current active call. |
callFailureReason | GET /call | Upon a failed call, this is a message indicating the reason for the failure. |
callStatus | GET /call | Represents the status of the call (initiated, established, failed, cleared). |
collaborationStatus | All except GET /event | Represents the status of a web collaboration session. Valid states are as follows: ESTABLISHED, NOT_ESTABLISHED, STARTING, and READY. |
collaborationServiceUri | All except GET /event when collaboration is enabled | This encoded URI is returned from the enable collaboration request, used for getting status or ending a web collaboration session. |
collaborationId | All except GET /event when collaboration is enabled | Unique identifier of a user collaboration session. If an optional address of record is provided when enabling collaboration, then the collaborationId matches that value. |
forPeerCollaborationUri | All except GET /event when collaboration is enabled | URI that a user can send to a peer. The peer uses it to establish a web collaboration session. It includes the peerAddressOfRecord parameter. |
peerCollaborationUri | All except GET /event when collaboration is enabled and the peer in the collaboration session has been found | This encoded URI can be used to establish a web collaboration with the other user on the phone call. |
ceaVersion | All | This string represents the version of the server. |
The following table lists the possible return codes seen in the REST response returnCode field.
Code number | Description |
---|---|
200 | Similar to an HTTP 200 OK. No problems were detected. |
201 | Response to the GET /event request if no new events are found. This return does not imply an error because an event might not have been generated. |
300 | REST request was invalid. For example, the HTTP method and URI did not match what is supported by the API. |
301 | REST request was a follow-on request, such as getting call or collaboration status, but no existing session information was found. |
302 | An error occurred when trying to parse the REST request. An error exists in the format of the JSON or XML provided. |
303 | For telephony-related REST requests, a user name was not found in the credentials. This would only happen if the configuration indicates that the user name associated with a caller should be retrieved from the request credentials. |
304 | Response to an outstanding GET /event request if, before a response is sent, a redundant GET /event request is received. |
305 | REST request is missing required parameters or fields. For example, this return results if the API makes a call that was sent without providing an addressOfRecord identifying the caller. |
306 | An unexpected error occurred. |
307 | A telephony related REST request was made that did not locate a call. |
308 | A collaboration-related REST request was made, but collaboration was not enabled for in the session. |
REST Request: PUT http://host:port/commsvc.rest/CommServlet/collaborationSession?JSON=true&ceaVersion=1.0.0.1 REST Response: { "returnCode":200, "infoMsg":"Successfully enabled collaboration", "collaborationId":"local.1242138965934_1", "callNotifyUri":"CommServlet/callerNotification;ibmappid=local.1242138965934_1", "collaborationStatus":"NOT_ESTABLISHED", "collaborationServiceUri":"CommServlet/collaborationSession;ibmappid=local.1242138965934_1", "forPeerCollaborationUri":"CommServlet/collaborationSession?addressOfRecord=local.1242138965934_1", "eventUri":"CommServlet/event;ibmappid=local.1242138965934_1" "ceaVersion":"1.0.0.1" }
REST Request: PUT http://host:port/commsvc.rest/CommServlet/collaborationSession?ceaVersion=1.0.0.1 REST Response: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <CommRestResponse xmlns="http://jaxb.servlet.commsvc.ws.ibm.com/"> <returnCode>200</returnCode> <infoMsg>Successfully enabled collaboration</infoMsg> <callNotifyUri>CommServlet/callerNotification;ibmappid=local.1242140626552_1</callNotifyUri> <collaborationId>local.1242140626552_1</collaborationId> <collaborationStatus>NOT_ESTABLISHED</collaborationStatus> <collaborationServiceUri>CommServlet/collaborationSession;ibmappid=local.1242140626552_1</collaborationServiceUri> <forPeerCollaborationUri>CommServlet/collaborationSession?addressOfRecord=local.1242140626552_1</forPeerCollaborationUri> <eventUri>CommServlet/event;ibmappid=local.1242140626552_1</eventUri> <ceaVersion>1.0.0.1</ceaVersion> </CommRestResponse>
REST Request PUT http://host:port/commsvc.rest/CommServlet/call?JSON=true&ceaVersion=1.0.0.1 { "enableCollaboration": false, "addressOfRecord":"sip:phone1@192.168.1.100", "peerAddressOfRecord":"sip:phone2@192.168.1.100" } REST Response: { "returnCode":200, "infoMsg":"Call attempted between sip:phone1@192.168.1.100 and sip:phone2@192.168.1.100.", "callerAddressOfRecord":"sip:phone1@192.168.1.100", "calleeAddressOfRecord":"sip:phone2@192.168.1.100", "callServiceUri":"CommServlet/call;ibmappid=local.1242140626552_42", "callNotifyUri":"CommServlet/callerNotification;ibmappid=local.1242140626552_42", "collaborationStatus":"NOT_ESTABLISHED", "eventUri":"CommServlet/event;ibmappid=local.1242140626552_42" "ceaVersion":"1.0.0.1" }
REST Request PUT http://host:port/commsvc.rest/CommServlet/call?ceaVersion=1.0.0.1 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <CommRestRequest xmlns="http://jaxb.servlet.commsvc.ws.ibm.com/"> <addressOfRecord>sip:phone1@192.168.1.100</addressOfRecord> <peerAddressOfRecord>sip:phone2@192.168.1.100</peerAddressOfRecord> <enableCollaboration>true</enableCollaboration> </CommRestRequest> REST Response <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <CommRestResponse xmlns="http://jaxb.servlet.commsvc.ws.ibm.com/"> <returnCode>200</returnCode> <infoMsg>Call attempted between sip:phone1@192.168.1.100 and sip:phone2@192.168.1.100.</infoMsg> <callerAddressOfRecord>sip:phone1@192.168.1.100</callerAddressOfRecord> <calleeAddressOfRecord>sip:phone2@192.168.1.100</calleeAddressOfRecord> <callServiceUri>CommServlet/call;ibmappid=local.1242140626552_33</callServiceUri> <callNotifyUri>CommServlet/callerNotification;ibmappid=local.1242140626552_33</callNotifyUri> <collaborationStatus>NOT_ESTABLISHED</collaborationStatus> <eventUri>CommServlet/event;ibmappid=local.1242140626552_33</eventUri> <ceaVersion>1.0.0.1</ceaVersion> </CommRestResponse>