Menu

Interactions API

Base URL

https://flex-api.twilio.com/v1

Authentication

The Flex API uses the same HTTP Basic Authentication as other Twilio APIs. Use your Twilio account SID as your username and your Auth Token as your password.

Resources

Example Request and Response

The following is an example of an agent-initiated interaction.

Request

Loading Code Sample...
        
        

        Agent-initiated outbound SMS

        Response

        {
           "url": "https://https://flex-api.twilio.com//v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
           "routing": {
               "reservation": null,
               "properties": {
                   "date_updated": 1637013849,
                   "task_queue_entered_date": 1637013849,
                   "workflow_name": "Assign to Anyone",
                   "age_in_queue": 0,
                   "task_channel_unique_name": "sms",
                   "assignment_status": "pending",
                   "queue_name": "Everyone",
                   "assignmentCounter": 0,
                   "priority": 0,
                   "sid": "WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                   "workflow_sid": "WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                   "routing_target": "WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                   "reason": null,
                   "attributes": "{\"customerAddress\":\"+1311-555-2368\",\"flexChannelInviteSid\":\"KGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\"conversationSid\":\"CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\"channelType\":\"sms\",\"conversations\":{\"initiated_by\":\"Agent\",\"communication_channel\":\"Sms\",\"media\":[{\"conversation_sid\":\"CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"}],\"direction\":\"Outbound\"},\"customerName\":\"silly name\",\"flexInteractionChannelSid\":\"UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\"initiatedBy\":\"agent\",\"direction\":\"outbound\"}",
                   "task_channel_sid": "TCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                   "age": 0,
                   "workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                   "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                   "timeout": 86400,
                   "date_created": 1637013849,
                   "addons": "{}",
                   "queue_sid": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
               }
           },
           "channel": {
               "type": "sms",
               "sid": "UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
           },
           "sid": "KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
           "links": {
               "channels": "https://https://flex-api.twilio.com/v1/Interactions/KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels"
           }
        }

        Task Attributes

        The following table lists a set of “well known” attributes that are consumed by the Flex UI and/or Flex Insights.

        Attribute

        Description

        Example

        customerName

        For Insights, it is used to populate conversations.customers.name.


        In the Flex UI, it is rendered as the main customer’s name for an email task.

        Al Fresco

        customerAddress

        For Insights, it is used to populate conversations.customers.email or conversations.customers.phone.


        In the Flex UI, it is rendered as the main customer’s email address for an email task.

        +192522212345 or

        alfresco@aol.com

        from

        This is the Flex UI's preferred attribute for identifying the customer on non-email tasks. For email tasks, it uses customerName.

        Al Fresco, +19251235555

        subject

        In the Flex UI, it is rendered as the initial subject of an email thread task.

        Issue with shoes

        flexInteractionChannelSid

        Used in the Flex UI to identify whether a task is interaction-based or not and therefore whether there is a need for Flex UI orchestration or not.

        UOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

        flexInteractionSid

        The interaction SID

        KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

        flexChannelInviteSid

        The invite SID

        KGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

        followed_by

        Used for external warm transfers

        outcome

        Used for external warm transfers

        customers

        This object is automatically added if customerAddress and customerName are provided.


        This object contains the name, phone, and email of a single customer.

        name [required]: The display name of the customer. If name is not available, it must be set to null

        phone [required]: The phone number or WhatsApp number of the customer. If number is not available, it should be set to null

        email [required]: The email address of the customer. If no email address is available, it should be set to null

        "customers": {

        "name": "Al Fresco",

        "Phone": "+19252148887",

        "email": null

        }

        The following attributes are added when the channel is created (asynchronously):

        Attribute

        Description

        Example

        conversations.external_contact


        (This is the Conversation projected address)

        For Insights, this is the contact address the customer used to reach you or the contact address from which you have reached them. This may be an inbound support phone number, your support email, or a phone number that appears on the customer's phone when you call them.


        The contact information (email, phone) that the customer uses or sees when communicating with the contact center can be used for traffic segmentation.

        help@example.com

        Task Attributes mapped from Channel Attributes

        Some interaction request channel attributes are also used to create other task attributes. The following table lists those task attributes that are created from the given channel attributes:

        Interaction Channel Attribute

        Task Attribute(s)

        Values


        type

        conversations.media.type (Insights)

        For all conversation media types

        ChatTranscript

        conversations.communication_channel (Insights)

        Email, SMS, Whatsapp, Web, Chat

        channelType (FlexUI)

        The Flex UI uses this to identify tasks that have the same “uniqueTaskChannelName” as chat, but have to be treated differently, e.g. whatsapp, sms.

        email, sms, whatsapp, web, chat, messenger, gbm

        initiated_by

        direction (Flex UI)

        When initiated_by is set to “agent”, this value is outbound, otherwise it’s inbound.

        customer | api | agent


        properties.media_channel_sid

        conversations.conversation_id (Insights)

        KDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

        conversations.media.sid (Insights)

        conversationSid (Flex UI)

        The following table captures the reason for requiring these attributes:

        Flex Insights attributes

        How/why is it used

        conversations.media.type

        Example of the entire media object with attached chat transcript

        conversations.initiated_by

        Flex Insights: Used to identify how the conversation was initiated. This helps to identify funnels leading towards a conversation.

        conversations.external_contact

        Flex Insights: The contact address the customer used to reach you or the contact address from which you have reached them. This may be an inbound support phone number, your support email, or a phone number that appears on the customer's phone when you call them.


        Useful for segmenting traffic by contact information (email, phone)

        conversations.conversation_id

        conversations.media.sid

        The ID of the conversation used for Historical insights. The Media SID is used to get access to the transcripts.

        Errors

        Some common errors you may encounter include Error 20003 and Error 11200. See the Twilio Error and Warning Dictionary for a list of potential errors.

        Rate this page:

        Need some help?

        We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        thanks-feedback-gif