Interaction Dialer

The Dialer service provides the ability to perform various Dialer-related operations:

  • Log in to and out of Dialer Campaigns
  • Mark agents as ready for calls
  • Request breaks from taking Dialer Interactions
  • Disposition Dialer Interactions

The Dialer API does not yet have support for Dialer scripts or staging.


For further information about Interaction Dialer concepts, see the Dialer Administration Concepts guide in the Documentation Library.

Jump to a section that describes each area of the Dialer API:

Basic Dialer Flow

This is a quick rundown of the most basic steps that are taken in the most basic ICWS Dialer flow.

  1. Establish an ICWS session.
  2. Log in to Dialer (POST /icws/{sessionId}/dialer/log-in).
  3. Tell Dialer you're ready for calls (POST /icws/{sessionId}/dialer/ready-for-calls).
  4. Set status to Available (not a Dialer API, but a necessary step).
  5. Receive a Dialer call via the data pop message (
    1. The call may be a Dialer preview call ( ==
      1. Preview calls must be dialed to connect to the party (POST /icws/{sessionId}/dialer/place-preview-call).
    2. Or all other Dialer dialing modes ( ==
  6. Request a logoff from Dialer (POST /icws/{sessionId}/dialer/log-off).
  7. Finish and disposition the current call, and potentially take an additional call if Dialer has already placed one (POST /icws/{sessionId}/dialer/disposition).
  8. Receive the logoff granted message (

If any one of these steps fails, do not let the application proceed. Return an appropriate error message to the agent.

Logging in to Dialer

The agent first logs in to Dialer (POST /icws/{sessionId}/dialer/log-in) and receives a message in response ( If the agent does not have the Logon Campaign right (configured in IA, provided via message.agentHasLogonCampaignRight == false), the agent is automatically logged in to all campaigns that are running that they are eligible for. If the agent does have the right (message.agentHasLogonCampaignRight == true), the available campaigns message contains a list of available campaigns (message.campaignsAdded), but the agent is not automatically logged in to any of them and will not receive any Dialer calls until logged in to at least one campaign. The agent selects each campaign (via individual requests to POST /icws/{sessionId}/dialer/log-in) to log in to.

Dialer Breaks

At any point while logged in to Dialer, the agent may request a break (POST /icws/{sessionId}/dialer/request-break). Dialer will not grant the break until the agent is eligible to go on a break (i.e. dispositioned the active Dialer call and not on another Dialer call). The agent receives the break granted message ( indicating that they are now on a break (message.breakStatus == 2). The agent returns to taking Dialer calls by ending the break (POST /icws/{sessionId}/dialer/end-break) or may log out of campaigns or Dialer (POST /icws/{sessionId}/dialer/log-off).

The Dialer system will automatically put an agent into an "on break" mode if they manually change their status to a non-ACD status, followed by "off break" when they return to an ACD-available status. When an agent ends a break, the custom application's UI does not need to wait for a response from the server before visually taking the agent out of an "on break" mode, since Dialer will always grant that request immediately.

Dialer Dispositions

To complete any Dialer call, the call must be dispositioned (POST /icws/{sessionId}/dialer/disposition). The values that can be used to disposition (body.label) come from the dataPop message for the Dialer call ( To reschedule a call, the scheduled time should be set to the desired date and time (body.scheduledTime), in UTC and needs to be sent as the number of seconds that have elapsed since Epoch time. To target a scheduled call for a specific agent, set the scheduled agent (body.scheduledAgent) to the CIC username of the desired user. After dispositioning, the agent must set their status to Available to receive another Dialer call.

Dialer Logoff

The agent can log out of campaigns individually (specify the campaign ID when calling POST /icws/{sessionId}/dialer/log-off) or can log out of Dialer completely, including all logged in campaigns (specify an empty array for the campaign IDs). Dialer will grant the logoff with a message ( that indicates the campaigns that the agent has been logged out of (message.campaigns). If one of the campaigns in the array is an empty string, it indicates that the agent has been logged out of Dialer completely, including all campaigns. The agent may log off of all campaigns, but remain logged in to Dialer.

Dialer Logoff Eligibility

If the agent is on a campaign call, Dialer will not grant a logoff for that campaign or for Dialer until that call has been dispositioned. If the agent is on a campaign call from a different campaign than the logoff request specifies, Dialer will typically grant the logoff request for that campaign immediately. Because of the logoff isn't granted until after the agent dispositions their current call, campaign and Dialer logoff requests should be made prior to dispositioning the call.

Blended Agents

A blended agent is an agent that is configured for inbound ACD as well as Dialer. There are no special considerations for blended agents. CIC/Dialer will determine the best interaction to assign to the user and ICWS will generate appropriate messaging depending on the interaction type.