Session Methods

http://[WebServerHost]/softdial/scc/[tenantName]/SessionProperties?Blocking=false&ReceiveEvents=Callback&CallbackURI=<CallbackURI> or ReceiveEvents=LongPolling

Element	Description
[WebServerHost]	Name of the host server running Softdial CallGem™
[tenantName]	Name of the tenant for which the request is being sent

Name	Description	Allowed values	Mandatory
Blocking	If true, uses the blocking version of the API which delivers instance methods that block until completion. See The Blocking API	true false (default)	No
ReceiveEvents	Defines how the Proxy will handle CallGem events and return them to the client. This method has no application for the blocking version of the API which does not deliver SDMP events directly.	Callback LongPolling (default) For a full explanation of these behaviours, see Receiving message events below.	No
CallbackUrl	The caller is listening on this URL in order to receive responses or unsolicited events.	The URL to return messages to the caller.	Yes, if parameter ReceiveEvents = Callback

HTTP Status Code	Description	Data
200 (OK)	Success	None
400 (Bad Request)	Badly formed request	An error response code will be accompanied by a textual message describing the error in the Status Description field of the Response object.
401 (Unauthorized)	Supplied authentication code failed authorisation

This mechanism allows server-to-server communication via HTTP callbacks. It allows full-duplex messaging and is typically used for a server-side integration where the remote server is either on the same network segment or connected through a VPN.

When the session property ReceiveEvents is set to Callback, a callback URL must also be supplied on which the client is listening. The format must be that of a standard URL with no parameters, e.g:

http://mydomain.com/myserver

This will be used to notify the client of new messages from CallGem which result from a request made on this session. The messages are sent in the same order in which they are received. They contain a sequence number which indicates the order in which they were received by the proxy. This sequence number can be used to check for lost messages (see Lost messages below).

The HTTP Proxy uses the callback URL in an HTTP POST to forward on one or more new messages and waits for an acknowledgement before continuing. If the wait times out, the Proxy will pause for a limited amount of time and then retry the POST. If this again fails the Proxy doubles the wait time and tries again, this will continue until a maximum wait time has been reached, at which point the client is assumed to have gone away and the session closes. The authentication code will continue to be valid and could be reused.

The initial and maximum wait times are controlled by these Registry settings:

• MinCallbackRetryPause (default - 1 sec)
• MaxCallbackRetryPause (default - 8 secs)

This mechanism allows server-to-server communication via long polling for events originating from Softdial Contact Center™ core services. It allows server-to-server integration over a wide area network without VPN use. This kind of mechanism would normally be used with HTTPS. See Configuring HTTPS.

When the session property ReceiveEvents is set to LongPolling, the GetMessages request is sent to the Proxy by the client to retrieve the list of events since the last GetMessages request was made or the Session was started.

Typically, LongPolling is used to ensure a client receives immediate notification of a new message and should be implemented by the client in such a fashion that the request is resent immediately the previous request returns, but not before.

The request will only return immediately if there is one or more new messages cached by the Proxy. If there are no new messages, the Proxy will wait for a period of time, controlled by registry setting LongPollingPause. If a new message arrives from CallGem during this period the Proxy returns it to the client immediately, or it will return when the wait period is up. 200 (OK) indicates one or more messages are being returned, 204 (No Content) indicates there are no new messages.

Payload data of both GetMessages responses and Callback pushes are in the following JSON format:

{
Specifies how many more messages are cached by the Proxy Session when there were more messages than could be placed in a single HttpResponse
  "q": 0,
The array of messages
  "Messages": [
  {
A Timestamp indicating when the Proxy received the message
    "ts": "2015-12-07T13:39:47.5794002+00:00",
Zero based serial number created by the HTTP Proxy and unique within the current HTTP Proxy session
    "sn": 1234,
The native SDMP message as received from CallGem
    "raw": "RI:DE:R0\MSCallGem",
Current version of the Proxy
    "version": "1.0",
The type of service
    "service": "RI",
The interface Id
    "iface": "DE",
The SDMP message code
    "code": "R0",
The list of parameters. These are described in the API Message Guide
    "params":
    {
      "MS": "CallGem"
    },
If CallGem is reporting on an error condition, indicated by "code": "ER", this field will contain the original SDMP message which produced the error
    "fm": null
  }]
}

If a Token (TK) parameter is included in a request for an SDMP code (please see the API Message Reference), the Proxy acknowledges the request without waiting for CallGem to respond. However, if a TK parameter is not included, the Proxy waits for CallGem to acknowledge.

CallGem messages are not cached by the Proxy indefinitely. If no GetMessages request is received by the Proxy then it will eventually start flushing out old messages. The age at which messages get flushed is determined by the registry key MessageTTLInMinutes. When the amount of time a CallGem message has been in the cache exceeds this limit it is removed and discarded. It is the responsibility of the Client to ensure it is sending a GetMessages request often enough to prevent this happening.

Note that this also applies to a Callback Session. As CallGem events are sent in batch to the Client and no new messages are processed until the Proxy receives the Client’s acknowledgement, messages will back up in the cache and will also be flushed if MessageTTLInMinutes is exceeded.

Note that the GetMessages method delivers all messages queued for a session. The method is a session method and requires no tenant, type of service or interface ID in the path.

Inactive sessions do not persist indefinitely. They are closed down if they have been inactive for a period exceeding the registry setting InactiveThresholdInMinutes (defaults to 10 mins).

In all cases, any request made by a client will reset the inactivity counter. In the absence of subsequent requests, the period of inactivity is determined differently depending on how the Proxy is communicating with the client:

Callback	This session type will execute a Push on the CallbackUrl containing no messages, the client’s acknowledgement of which will result in the inactivity counter being reset. Note that if there is no acknowledgement, the standard retry mechanism will kick in, as described above
LongPolling	This session type has its inactivity counter reset on each receipt of a GetMessages request

A HTTP proxy Session can also be closed explicitly using the Close request. This request will result in the immediate termination of the session. This results in any resources in CallGem associated with this session being cleaned up. The SCC session does not get closed and so can be used to address other services in the SCC ecosystem.