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
    • 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, please 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
Supported Channels supportedChannels Text Array Determines which communication channels are supported. Valid values: "VOICE", "SMS", "CHAT"
Twilio Connected System twilioWorkerConnectedSystem Connected System The connected system used to communicate with Twilio and to generate the Twilio TaskRouter token. This should be an HTTP connected system with Basic authentication, using the Twilio Account SID (e.g., "AC...") as the Username and the corresponding Twilio Auth Token as the Password.
Twilio TwiML App SID twilioTwiMLAppSid Text The Twilio TwiML App SID (e.g., "AP...") for the Twilio application.
Twilio Workspace SID twilioWorkspaceSid Text The Twilio Workspace SID (e.g., "WS...") for the Twilio workspace.
Twilio Worker SID twilioWorkerSid Text The Twilio Worker SID (e.g., "WK...") for the Twilio worker.
Twilio Chat Connected System twilioChatConnectedSystem Connected System The connected system used to generate the Twilio chat token. This should be an HTTP connected system with Basic authentication, using the Twilio Chat API Key SID (e.g., "SK...") as the Username and the corresponding Twilio Chat API Key Secret as the Password.
Twilio Chat Service SID twilioChatServiceSid Text The Twilio Chat Service SID (e.g., "IS...") for the Twilio chat service.
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 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 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 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.
Record Call recordCall Boolean Determines whether phone calls will be recorded by Twilio. Default is false.
Twilio Transfer Workflow SID twilioTransferWorkflowSid Text The Twilio Workflow SID (e.g., "WW...") to use for call transfers. If no value is specified, the transfer function will be disabled.
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.
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.
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 is false.
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:
    1. 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:
    1. 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 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.
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.

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 in 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 display 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. Please 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 will appear as valid transfer targets are agents who are available for voice, and not currently on an active call.

The ICC Application sets up the workflow and TaskQueue to properly allow for direct transfers. For this capability to function properly, please 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. Please 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
FEEDBACK