Twilio Component

Twilio Component

Function: twilioField()

Allows participation in voice calls, chats, or SMS messages using 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 Component on an interface in your application.

Access Twilio's API documentation for more details.

Services Used by Appian

Appian integrates with the following Twilio services when using the Twilio Component:

All services can be managed from the Twilio console.

Voice and Networking Overview

For voice calls, the Twilio 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.

There are several requirements for Appian to properly communicate to Twilio, as listed below.

  • 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 Twilio 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.

Parameters

Name Keyword Type Description
Label label Text Optional text to display as the field label.
Label Position labelPosition Text Optional text to determine where the label appears. Valid values include
  • "ABOVE" (default) Displays the label above the component.
  • "ADJACENT" Displays the label to the left of the component.
  • "COLLAPSED" Hides the label. The label will still be read by screen readers; see accessibility considerations for more information.
  • "JUSTIFIED" Aligns the label alongside the component starting at the edge of the page.
Instructions instructions Text Optional text displayed below the field's label.
Help Tooltip helpTooltip Text Displays a help icon with the specified text as a tooltip. The tooltip displays a maximum of 500 characters. The help icon does not show when the label position is "COLLAPSED".
Required required Boolean Determines if a value is required to submit the form. Default is false.
Disabled disabled Boolean Determines if the user is prevented from changing the value and determines if the field should be grayed out. Default is false.
Validations validations Text Array Validation errors to be displayed below the field when the value is not null.
Height height Text Determines the layout height. Valid values: "SHORT", "MEDIUM", "TALL", "AUTO" (default).
Visibility showWhen Boolean Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default is true
Twilio Connected System twilioConnectedSystem Connected System The connected system used to communicate with Twilio. This should be created as a Twilio Connected System.
Twilio Worker SID twilioWorkerSid Text The Twilio Worker SID (e.g., "WK...") for the Twilio worker.
Twilio Workflow SID twilioWorkflowSid Text The Twilio Workflow SID (e.g., "WW...") to use for call/chat/SMS transfers and outbound calls. If no value is specified, the transfer and outbound calling capabilities will be disabled.
Supported Channels supportedChannels Text Array Determines which communication channels are supported. Valid values: "VOICE", "SMS", "CHAT"
Record Call recordCall Boolean Determines whether phone calls will be recorded by Twilio. Default is false.
Allow Direct Transfer allowDirectTransfer Boolean Determines if direct transfers and conferences to specified agents are allowed. If set to true, agents who are available will appear when searching for transfer targets and conferencing will be enabled. If set to false, only blind transfers and consults to queues will be allowed. Default: false.
Display Country Code displayCountryCode Boolean Determines whether the phone number that is passed from Twilio will be formatted to display the country code of the caller. Default: false.
Auto Answer autoAnswer Boolean Determines if the user is automatically connected to an incoming phone call. Default: true.
On Task Reserve onTaskReserve Save Array One or more variables that are updated when a task is reserved. This save array will only be executed when autoAnswer is set to false. The value to be saved will be a dictionary representing the loaded task. Use a!save() to save a modified or alternative value to a variable.
On Task Dismiss onTaskDismiss Save Array One or more variables that are updated when a task is cancelled, rejected, or timed out. This save array will only be executed when autoAnswer is set to false, and will execute after On Task Reserve. The value to be saved will be a dictionary representing the dismissed task. Use a!save() to save a modified or alternative value to a variable.
On Task Load onTaskLoad Save Array One or more variables that are updated when a Twilio TaskRouter task is loaded. The value to be saved will be a dictionary representing the loaded task, including fields for:
  • taskSid The unique identifier of the task.
  • assignmentStatus The current status of the task, which will be "assigned" for this event.
  • taskType The task type, one of "voice", "sms", or "chat".
  • attributes A dictionary containing additional details about the task.
Use a!save() to save a modified or alternative value to a variable.
On Transfer onTransfer Save Array One or more variables that are updated when a blind transfer is initiated. The value to be saved will be:
  • taskSid The unique identifier of the task.
Use a!save() to save a modified or alternative value to a variable.
On Conference onConference Save Array One or more variables that are updated when a the user starts a conference. The value to be saved will be a dictionary representing the newly created conference task, including fields for:
  • taskSid The unique identifier of the newly created task.
  • assignmentStatus The current status of the task.
  • taskType The task type, which will be "voice" for this event.
  • attributes A dictionary containing additional details about the task, including fields for:
      • transferType The type of transfer, which will be "conference" for this event.
      transferredBy The worker SID of the worker who is initiating the conference.
      originTaskQueue The Twilio TaskQueue in which the origin (parent) task was routed through.
Use a!save() to save a modified or alternative value to a variable.
On Consult Start onConsultStart Save Array One or more variables that are updated when a the user starts a consult. The value to be saved will be a dictionary representing the newly created consult task, including fields for:
  • taskSid The unique identifier of the newly created task.
  • assignmentStatus The current status of the task.
  • taskType The task type, which will be "voice" for this event.
  • attributes A dictionary containing additional details about the task, including fields for:
      • transferType The type of transfer, which will be "consult" for this event.
      transferredBy The worker SID of the worker who is initiating the conference.
      originTaskQueue The Twilio TaskQueue in which the origin (parent) task was routed through.
Use a!save() to save a modified or alternative value to a variable.
On Consult Transfer onConsultTransfer Save Array One or more variables that are updated when the consult transfer is complete. The value to be saved will be a dictionary representing the completed task. Use a!save() to save a modified or alternative value to a variable.
On Consult Return onConsultReturn Save Array One or more variables that are updated when the user clicks "Back to Caller" during consult. The value to be saved will be a dictionary representing the original task. Use a!save() to save a modified or alternative value to a variable.
On Communication Complete onCommunicationComplete Save Array One or more variables that are updated when the call or chat ends. The value to be saved will be the current task SID. Use a!save() to save a modified or alternative value to a variable.
On Task Complete onTaskComplete Save Array One or more variables that are updated when the Twilio task is completed. The value to be saved will be the current task SID. Use a!save() to save a modified or alternative value to a variable.
Outbound Call outboundCall Boolean Determines if the user has the ability to place an outbound call. Default is false.
Outbound Caller ID outboundCallerID Text The caller ID that is associated with the outgoing call. The value provided must be an E.164 formatted number that is either owned or verified by the Twilio account. If this field is left blank, the caller ID will default to the first owned number in Twilio.
Outbound Suggestion outboundSuggestion Text A suggested phone number that will appear in the outbound dial pad. The number can be edited by the user before the call is placed.
Default Country Code defaultCountryCode Integer If provided, prefixes a country code in front of the entered phone number for all outbound calls. If not provided, users will need to manually enter ina country code for each call that is placed.
Chat Start Audio chatStartAudio Boolean Determines whether there will be an audio notification at the start of a chat or SMS conversation. The audio will be dismissed when the user clicks in the text response box. Default is false.
Chat Suggestion chatSuggestion Text A suggested chat message which will appear in the chat message window. The message can be edited by the user before being sent.
On New Chat Message onNewChatMessage Save Array One or more variables that are updated when a new chat message is sent or received. The value to be saved will be a dictionary representing the new message, including fields for:
  • channelSid The unique identifier of the current chat channel.
  • isFromAgent True if the message was sent by the agent using the Twilio component. False if the message was sent by a remote participant.
  • message The body of the message
Use a!save() to save a modified or alternative value to a variable.
On Member Leave onMemberLeave Save Array One or more variables that are updated when a member leaves the chat. The value to be saved will be a dictionary representing the identity of the worker that left, member SID, channel SID, and member count of the channel. Use a!save() to save a modified or alternative value to a variable.
Is Debug isDebug Boolean Determines whether debug mode is enabled for browser console logging. This parameter should only be set to true in non-production environments. Default: false.
Twilio Client Region twilioClientRegion Text Specifies which Twilio Data Center to use when an agent receives or initiates a call. If left blank, the component will use Twilio's global low latency (GLL) region selection.

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 field to be properly set up. The Twilio component searches 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. This subsection explains how the Twilio component handles queue transfers and walks through how to properly set up the Twilio workflow to handle transfers.

A Twilio workflow routes a task by its attributes to a particular queue. The ensure correct routing, the Twilio 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 component. The rest of this section will focus on how the transfer is executed.

To transfer a voice task, the 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.

Keep in mind that 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. When this is set, the Twilio component will allow the user to search by agent name. The component looks for the workerDisplayName parameter in the Twilio worker attributes to return a list of matching agents. This field is created by default and set to the Appian user's name when using the Add Appian Users as Twilio Workers action to create Twilio workers. 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

Reserved Attributes

The Twilio component uses several attributes on each Twilio task for the various functions it needs to perform. There is no configuration required, but it may be of value for designers to be aware of these reserved attributes. These attributes should not be overwritten at any point.

1
2
3
4

parentTaskSid
targetTaskQueueSid
isAgentMuted
isCustomerOnHold
Open in Github

On This Page

FEEDBACK