Twilio Flex Integration
This feature is in Preview and its behavior is likely to change based on user feedback. The feature also may have lower availability and have more maintenance windows.
You can connect multiple Twilio Flex instances to a single Salted CX account and mix data with other contact center platforms, other data sources and upload additional data using our Ingest API.
Integration between Twilio Flex and Salted CX
Transcripts are available for messaging channels only. Calls are available for playback in the customer journey without transcript.
We combine two data sources from Twilio to reconstruct customer journeys, conversations and turns (messages) in Salted CX:
- Twilio Event Stream
- Programmable Chat (Conversation API)
Configure Event Stream
In the following steps you will ask Twilio to send important events from your contact center to Salted CX:
- In Twilio Console go to Event Stream ⏵ Manage ⏵ Create Sink
- Choose sink Type: Amazon Kinesis Data Stream
- Request from Salted CX team Amazon Resource Name (ARN), External ID and Role ARN
- Fill those information provided by Salted CX
- Click Finish setup
- In Twilio Console go to Event Stream ⏵ Manage ⏵ Create Subscription
- Select the Sink created in step 5
- Use description to ensure people know what the subscription is for, for example “Integration with Salted CX”
- Select all events with the latest schema version from the TaskRouter section EXCEPT RateLimit (all events from reservation, task, task qeuues worker and workflow)
Create API Key
In this step you will generate token that Salted CX can use to extract data:
- In the right top corner click on Admin ⏵ Account Management
- Keys & Credentials ⏵ API keys & Tokens ⏵ Create API Key
Provide Account Information to Salted CX
Pass the following information securely to Salted CX team:
- Account SID
- API key SID and secret
Twilio Flex Data in the Logical Model
We translate data from all platforms into our unified Logical Model that enables you to report on data from multiple platforms in the same way. We use unified concepts with unified naming and the same meaning in every platform.
As each platform has its own vocabulary and concepts we cannot adopt any single platform vocabulary. Platforms have different names for the same concepts (for example queues, case, issue, or task for a single customer-related request). Or different platforms use the same name for different concepts (for example “Contact” means a single conversation with a customer in one platform, but it means a customer email/phone in another platform).
This article covers how Twilio Flex concepts translate into Salted CX concepts and vocabulary.
To understand Twilio Flex data in the Logical Model it is recommended to have a basic understanding of our Customer Journey and Logical Model. You can also check our Glossary to understand the naming and meaning of our concepts.
Salted CX uses TaskRouter tasks to read details about agents activities and reservations. We gather information from the tasks attributes and map them into the Salted CX Logical Model
Customers
Salted CX creates individual customers that correspond to task attributes that are relevant to the customer identification.
| Salted CX | Task Attribute |
|---|---|
| Customer Contact ID | task_attributes.customers.external_id task_attributes.customers.phone task_attributes.customers.email task_attributes.from / to (depends on direction) task SID |
| Customer State | task_attributes.customers.state |
| Customer Country | task_attributes.customers.country |
| Customer Category | task_attributes.customers.category |
| Customer Organization | task_attributes.customers.organization |
| Customer Region | task_attributes.customers.region |
| Customer Segment | task_attributes.customers.segment |
Customer ID is taken from the multiple objects based on priority as mentioned in the table above. If no information about the customer is in the task then the customer is created with task SID which keeps the conversation isolated. That’s why it’s recommended always to populate any contact information into the task attributes.
Agents
Salted CX gather the agents’ information from the worker attributes that are part of the events that are generated when an agent changes the activity (ie. Offline > Available).
| Salted CX | Worker Attribute |
|---|---|
| Agent ID | |
| Agent Name | full_name |
| Agent Department | department |
| Agent Location | location |
| Agent Manager | manager |
| Agent Team | team agent_team |
| Agent Roles | roles |
| Agent Organization | organization |
| Agent Cost per Hour | cost_per_hour |
| Agent Cost per Engagement | cost_per_engagement |
Agent State is set to ‘Active’ when the worker is created and ‘Inactive’ if deleted.
Agent Role is set to the the highest permission (admin > supervisor > agent).
Agent Status
Activity is a detailed agent status change (AUX codes) during the day including attribution to time. Each item in the Activity data set represents a sum of time spent in a single agent status (AUX code) in a 15-minute interval.
Offline Activity is not being stored in Salted CX.
Conversations
Each TaskRouter task translates to one conversation.
Agent Engagement
Twilio Flex uses TaskRouter for assigning tasks and reservations to agents. Salted CX translates a reservation into the engagement which means that there can be multiple engagements in one conversation.
Agent engagement starts with the event of reservation accepted and ends with reservation completed.
| Salted CX | Task Attribute |
|---|---|
| Campain | task_attributes.conversations.campaign |
| Case | task_attributes.conversations.case |
| Category | task_attributes.conversations.category |
| Channel | task_attributes.conversations.channel task_channel_unique_name (name of the channel in Taskrouter) |
| Channel Vendor | “Twilio” |
| Company Contact | task_attributes.conversations.company_contact task_attributes.conversations.external_contact task_attributes.from / task_attributes.to (based on direction) |
| Conversation | task_attributes.conversations.conversation_jd task SID |
| Direction | task_attributes.conversations.direction task_attributes.direction ’Inbound’ |
| Engaged Department | worker_attributes.department |
| Engaged Location | worker_attributes.location |
| Engaged Organization | worker_attributes.organization |
| Engaged Manager | worker_attributes.manager |
| Engaged Role | worker_attributes.role |
| Engaged Team | worker_attributes.team worker_attributes.agent_team |
| Engagement Attribute 1 | task_attributes.conversations.attribute_1 task_attributes.conversations.conversation_attribute_1 |
| Engagement Attribute 2 | task_attributes.conversations.attribute_2 task_attributes.conversations.conversation_attribute_2 |
| Engagement Attribute 3 | task_attributes.conversations.attribute_3 task_attributes.conversations.conversation_attribute_3 |
| Engagement Fact 1 | task_attributes.conversations.fact_01 |
| Engagement Fact 2 | task_attributes.conversations.fact_02 |
| Engagement Fact 3 | task_attributes.conversations.fact_03 |
| Engagement Time | Duration between reservationAccepted and reservationWrapup |
| Engagement Type | “Agent” |
| Focus Time | task_attributes.conversations.focus_time |
| Hold Time | task_attributes.conversations.hold_time |
| Invitation Time | Duration between reservationCreated <> reservation Rejected/Revoked/Accepted/Missed/Cancelled |
| Language | task_attributes.conversations.language |
| Outcome | task_attributes.conversations.outcome |
| Outcome Category | task_attributes.conversations.outcome_category |
| Platform | “Flex” |
| Priority | task_attributes.conversations.priority |
| Queue | task_attributes.conversations.queue task_queue_sid / task_queue_name |
| Reason | task_attributes.conversations.reason |
| Start Time | reservation.accepted timestamp |
| End Time | reservation.completed timestamp |
| Wait Time | Duration between the last queue.entered and reservation.accepted events |
| Wrap Up Time | Duration between reservation.wrapup and reservation.completed |
If the channel unique name is voice (default Twilio naming) then we also gather task_attributes.conversations.sgement_link with an URL to the recording so the audio file can be re-played in the customer journey.
If there is not wrapup event configured then the wrap up time is not populated.
Queue Engagement
The queue segment always starts with TaskRouter event queue.TaskQueueEntered.
The queue segments have the same attributes as the Agent Engagements but they have a different outcome type in Salted CX model based on the ending event:
| Ending Event Name | Outcome Type | Usage |
|---|---|---|
| ReservationAccepted | Accepted | For such queue segments we also create agent engagements so all reporting can be done with this engagements where you will have populated waiting time, engagement time, invitation time and wrap up time (if wrap up exists) |
| TaskQueueEntered | Moved | Such queue engagements represent transfers from queue to another queue |
| TaskDeleted | Deleted | Such queue engagements represent deleted task |
| TaskCanceled | Customer Left Canceled | If the ending event is TaskCanceled then it depends on the Taskrouter value for field task_canceled_reason that is populated automatically by Twilio Taskrouter. If it’s ‘hangup’ then we populate ‘Customer Left’ and it represents abandoned conversations. If it’s ‘Task canceled on Workflow timeout’ then the task was ended due to timeout configuration in your Taskrouter Workflow settings. |
Invitation Engagement
The invitation engagements represent situations in which agents receive a reservation (invitation to join a conversation) but they miss it or reject it. Salted CX does not create invitations for instances when agent accepts the reservation. The invitation engagement starts with the event reservation.created.
The invitation engagements are mapped to the same attributes as the Agent Engagements but they have a different outcome type in Salted CX model based on the ending event:
| Ending Event Name | Outcome Type | Usage |
|---|---|---|
| ReservationAccepted | —- | We do not create invitation engagement because we have already all information in agent engagement. |
| ReservationTimeout ReservationCanceled | Missed | Such invitation engagements can be used to see how many reservations were missed by agent due to timeout configured in the Taskrouter workflow |
| ReservationRejected | Rejected | Such invitation engagements can be used to see how many reservations were actively rejected by the agents. |
| ReservationRescinded | Revoked | Such invitation engagements represent reservations that were closed because another agent already accepted the task’s reservation. Such scenario can happen if multiple reservations are created for one task (can be configured in Twilio Taskrouter queue setting) |
Turns
Each individual message in the channel from an agent or from a customer creates a new turn associated with an engagement of the currently engaged agent. The current deployment is configured to download chat transcripts via Twilio Conversation API.