Setting up Twilio

About Twilio

Twilio is a cloud-based communications platform that provides support for voice calls, chat, and SMS messages. You can access Twilio's features in Appian by using the Twilio availability and interaction controls components on an interface in your application.

For voice calls, the Twilio availability component uses a web browser to enable real-time calls through WebRTC. It relies on the browser's ability to access the computer's microphone and speaker. When an agent receives a call for the first time, their browser will prompt the agent for permission to use the computer's microphone. The agent must allow access to use the component.

Requirements

There are several requirements for Appian to properly communicate to Twilio, including:

  • The Appian environment must be network resolvable from Twilio, since callback URLs from Twilio need to be able to hit Appian Web APIs.
    • Cloud environments are already configured this way.
      • For on premise environments, Twilio callback URLs to Appian must be resolvable either directly or through proxy.
  • The agent's computer that accepts the call must be network resolvable to the Twilio availability and interaction controls components to connect the call to the agent.
    • Run Twilio's network test to ensure connectivity from a client machine (all voice related tests must pass).
    • Twilio uses the standard 443 server side SSL port.
  • The firewall should allow outgoing UDP to the public internet from browsers that will be using the Twilio component, and allow return traffic in response.
    • If you are operating on a restricted network that requires whitelisting of media IPs, you can find a list of IP ranges by region here.

For additional details on networking, refer to Twilio's network connectivity requirements for ports, bandwidth, and firewall configuration.

Twilio services used by appian

Appian integrates with the following Twilio services when using the Twilio availability and interaction controls components:

All services can be managed from the Twilio console.

Transfers setup

This section describes what is needed to properly set up transfers.

Queue transfers

The capability to transfer a voice call to a queue requires both the Twilio workflow as well as the Twilio availability and interaction controls components to be set up properly. The Twilio availability and interaction controls components search for a specific attribute expression in the Matching Task section of the workflow to a list of queue transfer targets to the agent, as well as execute the transfer successfully.

A Twilio workflow routes a task by its attributes to a particular queue. To ensure correct routing, the Twilio interaction controls component will only display a list of queue transfer targets in which the transfer routing has been properly configured. To configure this routing, the Matching Task section of the workflow filter expression should look for the attribute targetTaskQueueSid with a value of the pertinent TaskQueue. The exact syntax of the expression is provided below.

1
targetTaskQueueSid == '(ID of taskqueue)'

Once this expression has been set in the workflow, the TaskQueue will appear as a transfer target in the Twilio interaction controls component. The rest of this section will focus on how the transfer is executed.

To transfer a voice task, the interaction controls component creates a new task as a clone of the original (with the same attributes). We then add additional attributes, parentTaskSid and targetTaskQueueSid, to reference the parent task and ensure that the cloned task is routed to the appropriate TaskQueue. The targetTaskQueueSid attribute will be set to the SID of the Twilio TaskQueue that was selected in the component. The parentTaskSid will be the taskSid of the task that originally spawned the transfer.

Twilio will route a newly created task to the first TaskQueue that matches the task and has an available worker. Therefore, the cloned attributes of the parent task must be considered as well when routing this transfer task. See the example below of a matching task expression that is used for the ICC App.

1
(type == 'Normal Support' AND targetTaskQueueSid == NULL) OR  targetTaskQueueSid == 'WQxxxxxxxxxxxxxxxxxxxxxxxx'

Direct transfers

Direct transfers to agents can be enabled by setting the Allow Direct Transfer parameter to true. This allows the user to search by agent name. The list of agents who appear as valid transfer targets are agents who are available for voice, chat, or SMS, and not currently on an active interaction.

The ICC Application sets up the workflow and TaskQueue to properly allow for direct transfers. For this capability to function properly, note the following for the All Agents TaskQueue:

  • Must remain the first workflow step
  • Queue expression must match all workers (set as default to 1==1)

Events

The following diagrams describe the events associated with voice calls and chat/SMS sessions. Note that for voice calls, not all events will occur for each interaction. The events logged under Agent Receives a Phone Call can only occur if Auto Answer is set to false. Furthermore, different events will occur depending on whether the agent performs certain transfers during the call.

Voice calls

Twilio_Field_Voice_Event_Lifecycle_Final.png

Chat/SMS sessions

Twilio_Field_Chat_Event_Lifecycle.png

Open in Github

On This Page

FEEDBACK