Function: twilioField()
Allows participation in voice calls, chats, or SMS messages using 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.
Appian integrates with the following Twilio services when using the Twilio Component:
All services can be managed from the Twilio console.
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.
For additional details on networking, refer to Twilio's network connectivity requirements for ports, bandwidth, and firewall configuration.
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
|
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:
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:
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:
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.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:
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.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:
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. |
This section describes what is needed to properly set up 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 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:
1==1
)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.
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
On This Page