Routing and User Management

This page will outline the general design and architecture for ICC, particularly around the handoffs with Twilio and Google Dialogflow. This also covers the basics of performing agent management actions from Appian.

Routing Overview

There are a series of handoffs between Appian, Twilio, and Google Dialogflow when routing calls and SMS interactions. Please refer to the diagram below for an overview.

/icc high level flow

  1. The routing starts when a call, SMS, or chat arrives in Twilio.

  2. The initial configuration action in the ICC App sets up a TwiML App ("Appian ICC App") in Twilio which is configured to call Appian web APIs. Voice and SMS interactions in Twilio are configured to use the TwiML App, while chat is configured to call an API endpoint directly. The sub-bullets below are the Appian APIs that are called from Twilio for the different channels:
    • Voice: ICC_WS_TWIL_voiceEndpoint
    • SMS: ICC_WS_TWIL_smsEndpoint
    • Chat: ICC_WS_TWIL_chatEndpoint
  3. During this step, a variety of IVR or virtual agent capabilities can be configured. Appian can send responses back to Twilio for IVR and voice, which will be relayed to the customer. Twilio will then send the customer response back to Appian and wait for a response. This process will continue until Appian tells Twilio to enqueue, which will move the process along to step 4. Please refer to the Virtual Agent section for more details on how to configure virtual agent and IVR.
    • Appian can also optionally leverage Google Dialogflow during this step. For voice, the 'ICC_UT_TWIML_Dialogflow_routeVoiceCall' rule is used in this step to transfer a call to Dialogflow for virtual agent. For SMS, Appian sends each text to Dialogflow for intent extraction, with logic in 'ICC_UT_AI_fulfillReply' to send a response back to Twilio.
  4. Once Appian sends an enqueue response to Twilio, a task is created. A JSON string can be sent with the enqueue response to set attributes on the task for routing purposes. Therefore, much of the routing logic can be configured through IVR and virtual agent in Appian if so desired.

  5. After the task is sent through TaskRouter in Twilio and assigned to a worker, the Appian user associated with that worker will receive the interaction on their Agent Dashboard through the Twilio component. This step will only occur if the Appian user associated with that Twilio worker is logged into Appian and has the Agent Dashboard actively rendered. If this is not the case, then the Twilio worker will not be able to accept the task and the behavior will follow any timeout/contingency logic as defined in the Twilio workflow.


The initial setup of the ICC App adds two TaskQueues. By default, all tasks get routed to the "Normal Support" queue. Modifications to this routing can be done in the Twilio workspace and on the attributes set in the Appian API endpoints.

Additional TaskQueues can be added through Appian or Twilio. However, for the 'Update Twilio Queue Membership' action to work, it must be created with a specific queue expression. There is a 'Create Twilio TaskQueue' action in the ICC App to set this for you to make this easy. The queue expression is displayed below:

queues HAS "(TaskQueue friendly name)"

Designers can choose different expressions for TaskQueues if they wish. However, if the expression deviates from what is listed above, the 'Update Twilio Queue Membership' action will no longer work.

Worker Creation and Queue Assignment

The Twilio component has a 'twilioWorkerSid' parameter that must be valid for the component to load. Therefore, we must pass in an Appian user's associated Twilio worker SID when that user is logged into Appian. In order to do this, we use a table (ICC_WORKER) to store this association. This is important when evaluating how to sync Appian users with Twilio workers.

The ICC App is built with the assumption that users are first created in Appian and need to be pushed to Twilio. As so, the 'ICC Create or Update Twilio Worker' process is used in the app for a couple of purposes:

  • Creating a Twilio worker and linking to an Appian user
  • Setting attributes on newly created workers
  • Modifying attributes on existing workers (to add or remove queue association)

This process can be re-purposed to be used as part of a sync process when Appian users are created from external systems. Here are the important parameters that are passed into this process:

  • username
    • the Appian user ID of the agent in which you want a Twilio worker created for
  • workerAttribute
    • attribute(s) that you want to assign to the worker upon initial creation
  • updateAttributesFlag
    • this variable should be set to false for initial worker creation; it is set to true when the process is used to update queue membership

Please note that passing in an Appian user that is already linked to a Twilio worker will overwrite that Twilio worker's attributes.

To make user management easier for a manager, the ICC App uses this process in several actions:

  • Add Appian Users as Twilio Workers
    • Given a list of users/user groups, create workers in Twilio (without any attributes) and link them to that user
    • If the user is already linked to a Twilio worker, optionally ignore this user, or reset their worker attributes
  • Update Twilio Queue Membership
    • Please note that this action will only work if the TaskQueue expression conforms to the syntax listed in the previous section
    • Given a list of users/user groups and Twilio TaskQueues, perform the following logic: - Create worker if user is not already associated with a worker
      • If adding to queue, add the TaskQueue's friendly name to the "queues" attribute of that worker
      • If removing from queue, remove the TaskQueue's friendly name from the "queues" attribute of that worker (if applicable)