In this tutorial session we will connect several instances of Dialer Chat to the Softdial CallGem™ service, create a simulated telephony service with trunks, create a predictive campaign and log on an agent via the simulated switch. We will then simulate the Campaign Interface sending numbers to Softdial CallGem™ for the predictive campaign and connecting the resultant calls to the agent. The agent will disposition the calls and you will see the mechanism for returning call outcomes and data to the Campaign Interface.
The tutorial is designed to provide a broad overview of the four main Softdial interfaces:
and to demonstrate how these layers communicate with each other. In doing so you will learn how to analyse the Softdial CallGem™ message logs and error messages and interrogate Softdial CallGem™ to discover the status of the various resources:
You should also become familiar with navigating the API and other documentation that is available.
Each interface is accessed with a Dialer Chat instance. The procedure involves sending SDMP messages from each interface and observing how Softdial CallGem™ and the other interfaces respond. All messages to be entered can be copied directly from the text.
An abbreviated Message Log file from this exercise can be found at the end of this tutorial together with a link to the full original log file.
Follow the step by step procedure described below:
First confirm that the
Fig. 1 - Service Status window
If either of these services is not running, start the service. If the Softdial Telephony Gateway™ service is showing in your list of services and it is running, stop it for the purpose of this tutorial. Other services can remain running although only the
When Softdial Contact Center™ is installed it creates a default tenant. All tenant specific services are shown in the Service Status dialog with a tenant suffix.
Open a new instance of Dialer Chat by double clicking the DialerChat.exe from the Softdial folder and click Connect to connect to the local Softdial CallGem™ service (Fig. 2). Note you can enter the IP Address of any accessible server in the Host field if the Softdial CallGem™ instance you are connecting to is not on the same server as Dialer Chat.
Before Softdial CallGem™ will accept any SDMP commands relating to a tenant, the tenant must first be commissioned. Tenants are automatically commissioned by Softdial CallGem™ as soon as a default telephony service is registered with it.
In order to start communication with Softdial CallGem™, a telephony service issues a Trunks Open [TO] command to Softdial CallGem™ with a Number of Trunks (NT) parameter advising the number of trunks that are available. You can simulate a telephony service by issuing a Trunks Open [TO] command to Softdial CallGem™ from Dialer Chat e.g.
TO\NT10\IC__singlecti\SL
The Identify CTI (IC) parameter specifies the ID of the telephony (CTI) service that is connecting. The default CTI identifier is __singlecti. If no IC parameter is included in the Trunks Open [TO] message, Softdial CallGem™ will assume the CTI identity is __singlecti.
The Switch Login (SL) parameter informs Softdial CallGem™ that the telephony service will service agent login requests (i.e. when an agent logs in the telephony service will manage connection to the agent extension.)
When you send the Trunks Open [TO] message with the SL parameter, Softdial CallGem™ will respond with a Switch Login [SL] command to the Telephony Interface for the Reception agent on the System campaign . This message is asking the Telephony Interface to call the Reception agents extension (201) to log them in.
SL\TDdefault\CNsystem\ANReception\AE201\RI30
Note the Ring Timeout (RI) parameter - this sets a timeout in seconds for a response from the Telephony Interface to Softdial CallGem™, in this case the Telephony Interface should respond within 30 seconds with a Login Status [LS] to confirm that the Reception agent extension is logged in. If no Login Status [LS] is received by Softdial CallGem™ within the time specified in the RI parameter, Softdial CallGem™ will issue an alert with Error Code 57 (Login request denied).
Enter the following message into the telephony Dialer Chat text message field and click Send:
LS\TDdefault\CNsystem\ANReception\AE201\RS0
The Resource Status (RS) parameter indicates the success or failure of the Switch Login [SL] request - RS0 indicates success.
The telephony Dialer Chat window should look like Fig. 3.
Fig. 3 - Dialer Chat telephony 0
If you check the SysLog after sending the Trunks Open [TO] message you will see the Commission Tenant [C1] message for the default tenant appears immediately afterwards e.g.
CG:MA:C1\TDdefault\IC__singlecti\MSInternal
The CG:MA: part means that the message is for the Softdial CallGem™ service from the Management interface layer (see SDMP Routing ). MSInternal means that the command is internally generated by Softdial CallGem™.
Softdial CallGem™ provides a Management Interface supporting a range of Enumeration messages that provide information on activity on the other interfaces (Telephony, Campaign and Agent). To keep the Management Interface messages separate from the Telephony Interface messages, open a new instance of Dialer Chat to handle all Management commands and responses.
Using this new Management Dialer Chat instance, confirm that the simulated telephony service is recognised by Softdial CallGem™ by sending an Enumerate Switches [ES] message to Softdial CallGem™ with a TX parameter. If any telephony services have registered with Softdial CallGem™ (by sending a Trunks Open [TO] message), Softdial CallGem™ will respond with a Switch Data [SZ] message for each telephony service indicating switch details as shown in the example below. See Switch Data [SZ] for parameter details.
If you have a Workflow Server service running you will also see a telephony service with an IC__Administrator parameter. This is a dummy telephony service used to facilitate the Administrator console. (See Workflow Server ).
Your Management Dialer Chat should now show the following messages (Fig. 4):
Fig. 4 - Dialer Chat Management 1
We can also check tenant status by sending an Enumerate Tenants [E1] message to Softdial CallGem™. Softdial CallGem™ will respond with a TenantData [Z1] message for each commissioned tenant. The Service State (SS) parameter indicates the state of each tenant as described in the tenant Data API . In this case the default tenant is shown as Active (SS2).
Your Management Dialer Chat should now look like Fig. 5.
Now that we have a telephony service registered with Softdial CallGem™ and the default tenant is commissioned, we can simulate opening a campaign by issuing a Open Campaign [OC] message. We could send this message from the same Dialer Chat instance that we used to send the Trunks Open [TO] message but this would mean that both telephony and campaign instance messages would be returned to this Dialer Chat.
For the purpose of this tutorial we want to keep the interface messages separate (for clarity) so we will open another instance of Dialer Chat and connect to Softdial CallGem™ using the same procedure as for the Telephony Interface.
The Open Campaign [OC] message CN parameter specifies the campaign name, the DM parameter specifies the Dialing Method
Dialing Method | DM value |
Predictive | 0 |
Progressive | 3 |
Preview | 4 |
Inbound | 5 |
Agentless | 6 |
The system campaign is specified by dialing method DM101.
OC\TDdefault\CNTestCampaign\DM0
Copy the above message text to the campaign Dialer Chat and click Send.
When Softdial CallGem™ receives this message it responds with a Campaign Open [CO] message.
The YC parameter is a Softdial CallGem™ generated unique identifier for this campaign. Softdial CallGem™ will associate the socket connection to this Dialer Chat instance with the Campaign Interface and will return all Campaign Interface messages to this socket.
Your campaign Dialer Chat should now look like Fig. 6.
With the TestCampaign open we can now log on an agent with the Agent Login [AL] command. Again we will open another instance of Dialer Chat to handle the Agent Interface messages. We identify the campaign to which the agent is to be logged on with the tenant and campaign identifiers.
The Agent Login [AL] command also requires three agent parameters:
The NailedUp (NU) parameter indicates that the connection to the agent extension should be held open i.e. the agent extension is reserved for use by Softdial CallGem™.
Copy the message text below to the agent Dialer Chat and click Send.
AL\TDdefault\CNTestCampaign\AN1\ADagent1\AE100\NU
Since the Trunks Open [TO] command was sent with a Switch Login (SL) parameter and the Agent Login [AL] command is being sent with a Nailed Up (NU) parameter, Softdial CallGem™ will immediately send a Switch Login [SL] command to the Telephony Interface requesting that the agent extension be called and, when connected, the connection be held open. Copy the Login Status [LS] response message below to the telephony Dialer Chat and click Send.
LS\TDdefault\CNTestCampaign\AN1\AE100\RS0
CallGem will respond with a Logged In [LI] message to the Agent Interface as confirmation of the Agent Login [AL] request. Note: the YA parameter is an Softdial CallGem™ generated unique identifier for this agent.
LI\TDdefault\CNTestCampaign\AN1\YA{11732d40-27e8-4ed2-8684-1a587420b038}
Your agent Dialer Chat should now look like Fig. 7.
Your telephony Dialer Chat should now look like Fig. 12.
Fig. 8 - Dialer Chat telephony 1
Since we have opened a predictive campaign (DM0) we can make the agent ACD Available on the campaign by issuing an Agent Available [AA] command. Again we identify the agent by specifying the tenant, campaign and agent identifier parameters:
AA\TDdefault\CNTestCampaign\AN1
Softdial CallGem™ responds with a Now Available [NA] message to the Agent Interface and an Agent Ready [AR] message to the Agent Interface and an Agent Ready [AR] message to the Telephony Interface which means the agent is now in the predictive pool ready to receive calls (Fig. 9):
You will notice another message appears in the Campaign Interface Dialer Chat (Fig. 10):
Fig. 10 - Dialer Chat campaign 2
This is a Call Request [CR] message issued by Softdial CallGem™ to the Campaign Interface requesting numbers to dial for the agent that has just entered the predictive pool. The Number of Numbers (NN) parameter tells the Campaign Interface how many numbers Softdial CallGem™ is requesting from the campaign list, by default this is set at 3 numbers for each agent. The Queue Length (QL)_ parameter Indicates how many numbers Softdial CallGem™ is currently waiting for in order to fill its predial queue. Since no numbers have yet been sent, these are both set to 3.
Now we can interrogate Softdial CallGem™ using Enumeration commands to check campaign and agent status information. We do this with the Enumerate Campaigns [EC] and Enumerate Agents [EA] commands which we will send from the Management Dialer Chat. Note the Transaction Identifier (TX) parameter must always be unique.
EC\TDdefault\TX3
CallGem responds with Campaign Data [CZ] messages for every campaign that is active on the specified tenant, e.g. the system campaign and the TestCampaign campaign:
CZ\TX3\TDdefault\CNsystem\YC{8c3de0d5-1637-4d37-8574-b661f4e94cea}\ZC1\ZO0\TS41045.703151\DM101
CZ\TX3\TDdefault\CNTestCampaign\YC{aea7eb5a-6ac7-479e-b9ec-08e0ec063ae4}\ZC1\ZO0\TS41045.703151\DM0
If you have the Workflow Server service running you will also see the following message:
CZ\TX3\TDdefault\CNAdministrator\YC{73d9bd3b-2fcc-44ee-b801-8087b55bf5fb}\ZC1\ZO0\TS41045.703151\DM3
The ZC and ZO parameters indicate the current and previous (old) state of each campaign as described in Campaign Data [CZ] .
We will now send the Enumerate Agents [EA] message:
EA\TDdefault\CNTestCampaign\TX4
CallGem responds to the Enumerate Agents [EA] command with Agent Data [AZ] messages for every agent that is active on the specified campaign, in this case the TestCampaign campaign:
AZ\TX4\TDdefault\CNTestCampaign\DM0\YC{...}\AN1\YA{...}\ADagent1\AE100\ZA1\TS41045.702810\W041045.696827\W141045.702810\NU
The NU parameter indicates that the agent is Nailed Up. The ZA parameter indicates the current state of each agent, the TS, W0 and W1 parameters record timestamps for state changes as described in Agent Data [AZ] .
For more detailed information about the agent state, the Enumerate Agents [EA] command may also be sent specifying a Level of Detail (LD) parameter.
EA\TDdefault\CNTestCampaign\ LD3 \TX5
When this parameter is specified, Softdial CallGem™ will return additional state and timestamp information depending on the parameter value specified - see Enumerate Agents [EA] for more details. Here is an example of the Agent Data [AZ] message returned after specifying a LD parameter value of 3 (maximum detail):
AZ\TX5\TDdefault\CNTestCampaign\DM0\YC{...}\AN1\YA{...}\ADagent1\AE100\ZA1\TS41043.671776\W041043.659064\W141043.671776\NU\ DS3 \ OS2 \ Z3 41043.659064\ Z4 0.012713\ Z0 41043.671776\ Z1 41043.671776\ Z2 0.000000
The Management Dialer Chat should now look like Fig. 11.
As we saw in Fig. 11, Softdial CallGem™ is requesting numbers from the campaign layer. We will now send Make Call [MC] messages to Softdial CallGem™ from the Campaign Interface but first we will set up the response that will be required from the Telephony Interface Dialer Chat.
If you were running this tutorial with a real Telephony Interface, with Trunks connected to a configured TDM or IP service, you could send the Make Call [MC] messages with live telephone numbers and make actual calls. Since we are using a simulated Telephony Interface we will use a dummy Telephone Number (TN) parameter value.
In the campaign Dialer Chat we will enter the following Make Call [MC] command. Do not send this yet.
MC\CNTestCampaign\TN1
When Softdial CallGem™ receives this command, it will generate a Call Initiate [CI] command and send this to the Telephony Interface. This message will appear on the Telephony Interface Dialer Chat.
The response we will send from the Telephony Interface will simulate a connected call. We can do this with the following Line Connected [LC] message which we will enter in the message text field of the Telephony Interface Dialer Chat. Do not press Send yet.
LC\TDdefault\CNTestCampaign\TN1\SI1\TI1234
The Session Identifier (SI) and Trunk Identifier (TI) parameters are mandatory parameters. You can use the values as shown.
Your telephony Dialer Chat should look like Fig. 12:
Fig. 12 - Dialer Chat telephony 1
On the campaign Dialer Chat, click Send to send the Make Call [MC] command to Softdial CallGem™. You will see an Error Report [ER] appear in the campaign Dialer Chat window:
ER\EC128\FM"MC\CNTestCampaign\TN1"
You can ignore this message - it is sent by Softdial CallGem™ when it does not receive Make Call [MC] messages fast enough from the Campaign Interface to keep the agents in the agent pool busy. You will also see another Call Request [CR] message from Softdial CallGem™ - every time a number is sent to the Telephony Interface Softdial CallGem™ will request a replacement from the Campaign Interface.
The following Call Initiate [CI] message appears on the telephony Dialer Chat. Note the Ring Timeout (RI) parameter default value of 16. This parameter sets the Ring No Answer (RNA) time that the telephony service will wait for a connect response from the network before issuing a Call Failed [CF] response to Softdial CallGem™ with a Reason Code (RE) value of 2 (No Answer). See Managing Ring Timeouts and Dialing Cycle Outcomes for more information on optimising RNA settings.
CI\TDdefault\CNTestCampaign\SI1\YS{615e5f7a-1cee-4f96-a8af-e6a0098180a3}\TN1\RI16\DO0
When you see the Call Initiate [CI] message appear on the telephony Dialer Chat, click Send to issue the Line Connected [LC] command.
On the telephony Dialer Chat you will see that Softdial CallGem™ has now issued a Call Transfer [CT] command to the Telephony Interface. This message is requesting the telephony service to transfer the connected call to the agent AN1 that we have recently logged in.
[Top]
Your telephony Dialer Chat should look like Fig. 13:
Fig. 13 - Dialer Chat telephony 3
Notice that the agent Dialer Chat has been updated with an Agent Connect [AC] message (Fig. 15), indicating that the call has now been connected to agent AN1 (Fig. 14).
The new agent status information is reported in the Management Dialer Chat window which should now look like Fig. 15.
Fig. 15 - Dialer Chat Management 4
Extend the window to see the full Agent Data [AZ] message as shown below. Note the new Detail State (DS) parameter value of 6 denotes the agent is Talking.
AZ\TX5\TDdefault\CNTestCampaign\DM0\YC{...}\AN1\YA{...}\ADagent1\AE100\ZA1\TS41045.716288\W041045.696827\W141045.702810\TN1\NU\DS6\OS3\Z341045.702810\Z40.013478\Z041045.716288\Z141045.716288\Z20.000000
At this point the call is normally ended in one of three ways:
For the purpose of this tutorial we will use the first method and issue a Start Wrap [SW] command. Copy the following message to the Agent Interface Dialer Chat and click Send
SW\TDdefault\CNTestCampaign\AN1
CallGem should respond with Call Ended [CE] message to the Agent Interface and a Call Disconnect [CD] command to the Telephony Interface (Fig. 16).
The agent is now in Wrap, the call has been disconnected by the Telephony Interface but the call session is still active while the agent updates the contact details, for example in Softdial Scripter. The next thing to do is to complete the call session by sending a Transaction Complete [TC] message back to Softdial CallGem™ with an Outcome Code , any other information that may be included in a Data (DT) parameter and/or instructions such as an arranged call back time.
We will now complete the call session by sending the following command from the Agent Interface. In this case we will set up a call back to the same agent:
TC\TDdefault\CNTestCampaign\AN1\AO101\BA1\BT41046.583333
The AO parameter contains a 3 digit agent outcome code - 101 means that a call back to this contact has been arranged.
If a BA parameter is included in the message it means that this is an agent specific call back i.e. when the call back is made it should be connected to the agent whose ID is specified in the BA parameter.
The BT parameter contains a timestamp in OLE DateTime format specifying when the call back should be made.
If a BN parameter is present this means that the call back should be made to a number specified in this parameter - in this case there is no BN parameter so the call back will be made to the same number as the original call.
Copy the Transaction Complete [TC] message to the agent Dialer Chat and click Send.
This results in the following response from Softdial CallGem™:
The call back information is used by the Campaign Manager application to schedule the call back. This would result in a Make Call [MC] message being sent to Softdial CallGem™ at the appropriate time. For agent specific call backs, the Make Call [MC]message will include an AN parameter specifying the agent who should receive the call.
Fig. 17 shows all four Interfaces just after the above Transaction Complete [TC] message has been sent.
Next we will send another Make Call [MC] message and disposition the call with an Agent Outcome (AO) code 105, Commitment (Fig. 18).
We will also add some text e.g. "Sale Agreed" in the Data (DT) parameter of the Transaction Complete [TC] message and see how this is passed back to the Campaign Interface.
This time we will send two Make Call [MC] messages together to Softdial CallGem™, but since there is only one agent in the predictive pool, Softdial CallGem™ will only issue one Call Initiate [CI] message and cache the other one until the agent becomes ready again. Any number of Make Call [MC] messages can be sent at any time to Softdial CallGem™ - the Queue Length (QL) parameter in the Call Request [CR] message just informs the Campaign Interface how many numbers Softdial CallGem™ requires to service its current predictive pool - any excess numbers are cached until needed.
As before, prime the campaign Dialer Chat and telephony Dialer Chat with the first Make Call [MC] and Line Connected [LC] messages given below.
MC\CNTestCampaign\TN2
LC\TDdefault\CNTestCampaign\TN2\SI2\TI1234
Click Send on the campaign Dialer Chat to send the first Make Call [MC] message.
When the Call Initiate [CI] Message appears in the telephony Dialer Chat, Click Send to send the Line Connected [LC] message.
Now load the next Make Call [MC] message into the campaign Dialer Chat message text field and click Send.
MC\CNTestCampaign\TN3
Note this time there is no resultant Call Initiate [CI] message, the second Make Call [MC] is cached until the current agent, or another agent becomes ready.
The Interfaces should now look like Fig. 19.
Now we will wrap the call as before by sending a Start Wrap [SW] message and then end the call with a Transaction Complete [TC] message.
Note the Agent Outcome (AO) and Data (DT) parameter values.
SW\TDdefault\CNTestCampaign\AN1
TC\TDdefault\CNTestCampaign\AN1\ AO 105\ DT Sale Completed
The Data (DT) parameter value can be plain text or an XML document. For details see DT XML Parameter Format .
This time the Number Back [NB] message sent to the Campaign Interface contains the DT parameter.
NB\TDdefault\CNTestCampaign\SI2\YS{...}\TN2\ DT Sale Completed\AO105\RE10\AG1\X141046.420644\X241046.420644\X341046.420946\X441046.421771
Since Softdial CallGem™ has another number in its cache it immediately sends another Call Initiate [CI] message to the Telephony Interface.
Enter the following Line Connected [LC] message in the telephony Dialer Chat and click Send.
LC\TDdefault\CNTestCampaign\TN3\SI3\TI1234
As before, Softdial CallGem™ sends a Call Transfer [CT] message to the Telephony Interface and an Agent Connect [AC] message to the Agent Interface. The agent is now talking.
Before we wrap and end this call, this time we are going to send an Agent Unavailable [AU] request from the Agent Interface to Softdial CallGem™. This message tells Softdial CallGem™ that the agent would like to be removed from the predictive pool for example at the end of a shift or to go on a break. The Agent Unavailable [AU] message has a Priority (PR) parameter which determines how the agent will be removed from the pool.
There are three ways an agent may be removed from the predictive pool but only one of these is safe, i.e. will not result in abandoned calls (See Changing Agent Status for more details).
PR value | Softdial CallGem will release the agent... | Risk of an abandoned call |
0 | ...when it is safe to do so | None |
1 | ...at the end of the current call | Medium |
2 | ...immediately, even if on a call | High |
As a rule, agents should only be removed from the predictive pool using a Priority (PR) value of 0, except in emergency.
Send the following Agent Unavailable [AU] request from the agent Dialer Chat.
AU\TDdefault\CNTestCampaign\AN1\PR0
The Interfaces should now look like Fig. 20.
Wrap the call as before by sending a Start Wrap [SW] message and then end the call with a Transaction Complete [TC] message keeping the same Agent Outcome (AO) and Data (DT) parameter values as for the last call.
SW\TDdefault\CNTestCampaign\AN1
TC\TDdefault\CNTestCampaign\AN1\AO105\DTSale Completed
This time, in addition to the normal messages, Softdial CallGem™ sends an Agent Free [AF] message to the Agent Interface to inform it that the agent has been removed from the predictive pool.
In this example, with only one agent and no numbers left in cache, the agent is freed from the predictive pool immediately after the current call. In a normal production situation, where there are many agents and Softdial CallGem™ is vigorously overdialing to keep those agents busy, it is likely that an agent may be required to take at least one and possibly two more calls before being released from the agent pool. This is necessary to avoid the possibility of an abandoned call being generated if, as a result of agents going unavailable, there are more predictive calls being connected than there are agents available to handle them.
In the campaign Dialer Chat, enter the following Close Campaign [CC] command and click Send to close the TestCampaign campaign.
CC\TDdefault\CNTestCampaign
On receipt of this message Softdial CallGem™ responds to the Campaign Interface with a Now Closed [NC] message. It also sends a Switch Logout [SO] message to the Telephony Interface and a Now Logged Out [NO] message to the Agent Interface to confirm that the agent is logged out.
In this exercise, there are no numbers left in Softdial CallGem™s cache when the campaign is closed however in practice it is common for a campaign to be stopped before all the numbers in the list have been dialed. In this case some numbers are left in the Softdial CallGem™'s cache and as they will not be dialed, a Number Back [NB] message will not normally be generated to update the campaign database.
This is provided for in Softdial CallGem™ by appending a Number Back (NB) parameter to the Open Campaign [OC] command. When this parameter is present, Softdial CallGem™ will return internally generated Number Back [NB] messages to the Campaign Interface for any numbers left in its cache when a campaign is closed. This ensures that the campaign database can be kept in sync when a campaign is stopped and started again.
Fig. 21 shows the final state of the four interfaces at the end of the exercise.
The message log file (with some parameter truncation) for the above session is shown below. Full details of the messages and parameters shown can be found in the Softdial API Reference. A full message log may be downloaded here .