Twilio Component

Twilio Component

Function: twilioField()

Allows participation in voice calls, chats, or SMS messages using Twilio.

See Also: Setting Up Twilio To Work with Appian

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

Twilio is a third-party service with independent costs and billing. For information on Twilio costs, consult their pricing information.

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

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

Transfer Expression

Call transfers must be properly set up in the Twilio workflow as well as in the Twilio field. The Twilio component searches for a specific attribute expression in the ‘Matching Task’ section of the workflow to display a list of transfer targets to the agent, as well as execute the transfer successfully. This section 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'

Events

The following diagrams describe the events associated with voice calls and chat/SMS sessions.

Voice Calls

/Twilio Field Voice Event Lifecycle

Chat/SMS Sessions

/Twilio Field Chat Event Lifecycle

FEEDBACK