Sockets Integration

The SDMP API is stateful. If you log in an agent through a particular connection all agent API communication is made through that socket. In this way Softdial CallGem™ works as a message router. If the connection is closed, any resources associated with that connection are deemed to have been lost, and Softdial CallGem™ performs housekeeping on this basis.

It is possible, and may be desirable, to re-use socket connections. Say for example that a customer writes a web service proxy to marshal agent communication, rather than use our own, it is possible to have the proxy open and maintain a single socket connection to Softdial CallGem™ through which all agent communication is handled. Messages coming from Softdial CallGem™ for a particular logical API may in turn be routed by the customer's web service proxy based on the token values for the following parameters:

An integrator app may be a trusted application authenticating using the landlord SYSTEM user or may create several socket connections and have each of these connections authenticate using a particular user's credentials.

Using SYSTEM account keeps things simple but it does mean that the integrator is responsible to avoid creating an open relay to Softdial CallGem™ which represents a security and reliability hole. If using this approach, we would strongly recommend a single connection and the integrator's service implementing its own message routing based on parameter tokens.

Using socket connections that authenticate with individual user credentials means that Softdial CallGem™ will be responsible for the security of the socket connection. If a socket connection is authenticated as a particular tenant user, Softdial CallGem™ will only process messages relating to that tenant and the scope of authorisation that the user has.

The general pattern that all of SCC services conform to, and that third party native integrations must conform to is:

1. Maintain an open connection during the session/ application lifetime.
2. Set the following socket options using setsockopt (BSD) or equivalent:
   • SO_RCVBUF - set to 262144 bytes
   • SO_SNDBUF - set to 262144 bytes
   • TCP_NODELAY - set to TRUE (1)
   This will ensure that the receive and transmit buffers are big enough to handle the largest message frames that are sent using SDMP without lots of TCP ack handshaking to get a complete message frame. It will also disable the Nagle algorithm allowing SDMP messages to be sent immediately rather than being queued which means that several messages smaller than the network MTU size can be sent at once.
3. Keepalives
   2-way keepalives are necessary to ensure that connection failure can be spotted by both ends of the socket if they are on different hosts. We would suggest 2-way keepalives as the default pattern regardless of whether the application is on the same host as Softdial CallGem™ or not.
   
   To establish 2-way keepalives the integrator application should
   1. send Verify Status [VS] messages - e.g. VS\VI60 ensures that Softdial CallGem™ sends Dialer Advise [DA] messages on a 60-second timer (as specified by the Verify Interval (VI) parameter)
   2. run its own timer and send plain Verify Status [VS] messages every 60 seconds. A permanent send failure indicates that the socket should be closed
4. Reconnection on socket connection closure
   Regardless of whether the integrator's application is deployed on the same host or on a separate host the following reconnect pattern should be employed: On disconnect, do not reconnect immediately. Instead, spin a repeatable timer with 10 second resolution, and on fire of this timer attempt reconnect. If connection is successful, cancel the timer.

Be aware of limits of socket-per-agent. A fully-fledged Softdial Contact Center™ system will maintain around 300 open socket connections to Softdial CallGem™ for 1000 agents using our standard software.

Using a socket-per-agent model for integration would push the number of socket connections to around 1300. In Softdial Contact Center™ V10.6, Softdial CallGem™ runs 32-bit native which means that the nonpaged pool limit is 1.5GB. Softdial CallGem™ has to allocate significant amounts of nonpaged memory per socket connection to limit the need for TCP acknowledgements (see General Pattern #2 above).

Adopting a socket-per-agent model places severe restrictions on the number of agents Softdial CallGem™ can support. Integrators adopting such a model should note that SCC V10.6 will be limited to only 100 agents, rather than 1000-3000 depending on topology.

All SDMP messages contain two component types, in the following order:

1. A message identifier, consisting of two alphabetic characters, e.g. Agent Connect [AC] is a message that can be sent from Softdial CallGem™ to the CRM application telling it that a live call has just been put through to an agent by Softdial CallGem™. Message Identifiers are not case sensitive.
2. Relevant message parameters, if any. Parameter codes are not case sensitive. Parameter values are case sensitive.

SDMP message parameters are also made up of three components, in the following order:

1. A parameter start character ("\").
2. A parameter identifier, consisting of two alphabetic characters, e.g. CN (Campaign Name).
3. The ASCII characters of the parameter value, if any.

Format options and restrictions on SDMP message parameters are as follows:

• Unless there are explicit instructions to the contrary, (e.g. parameter defined as numeric only) the following ASCII characters (in red) must not be used in parameters:
  • ~
  • |
  • \
  • CR
  • LF
  • null
• In general, it is strongly recommended not to include any characters with ASCII code below 32. For the latest information on this - see 'Invalid Characters' in Configuration Issues.
• Length restrictions exist for individual parameters and are set out in the message definitions in the API Guide.

The SDMP message

AC\TDTenant1\CNCustCare\AN2\TN01992783287\ASEx100

is comprised of the following components:

Choice of presentation

Parameters may be presented in a SDMP message in any order. So the following formats of the above example are equally valid:

AC\CNCustCare\AN2\TN01992783287\ASEx100

or

AC\TN01992783287\ASEx100\AN2\CNCustCare

Quite apart from the resiliency built into SDMP message passing protocols, some hosts may look for additional assurance that SDMP messages sent by them were received by Softdial CallGem™.

They can do this at their election, by including a user-defined token as a parameter in any host SDMP message. This takes the form:

\TK<string>

where <string> is the token with a length of from 1 to 30 characters.

Once any SDMP host message with a token has been error checked, Softdial CallGem™ will respond with a Message Verify [MV] message.

Softdial CallGem™ references agents using the following three parameters, as follows: