Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Integrate a Custom Chat Client with Flex


(information)

Info

Flex Conversations requires Flex UI 2.0. If you are on Flex UI 1.x, please refer to Messaging in Flex pages.

You may have already built a custom chat experience with Twilio Conversations or you are looking to build from scratch. You can integrate these chat experiences with Flex and hand off incoming Conversation messages to your agents.

(information)

Info

We have an open source demo chat application(link takes you to an external page) available to get you started. Refer to the README file for more information about the features offered in that example application and how it works.


Example Chat Integration with Conversations

example-chat-integration-with-conversations page anchor

The following diagram illustrates one potential way of integrating your Chat application with Flex:

example diagram on how to integrate chat application with flex.
  1. Your application needs to initialize the Twilio Conversations SDK with an Access Token and a Conversation SID . These should be obtained from your backend. This is outside the scope of this guide and you can get more information from the Twilio Conversations client applications' quickstart.
  2. Your backend will typically use the Twilio Helper Library but for the purposes of this guide, we will utilize curl for our Conversations API requests:

    1. Create a Conversation using the Twilio Conversations API.


      _10
      curl -X POST https://conversations.twilio.com/v1/Conversations \
      _10
      --data-urlencode "MessagingServiceSid=MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
      _10
      --data-urlencode "FriendlyName=My First Custom Chat Conversation" \
      _10
      -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN


      _10
      SID Chat Service SID Friendly Name Date Created
      _10
      CH1cbf85a0e7c844fca4cb4d2fad880196 IScf002bd40e59480bb62024d8fa161dbb My First Custom Chat Conversation Feb 17 2022 17:01:06 GMT-0800

    2. Add a participant to the conversation. Use the SID of the conversation that you created in the previous step. Make sure the identity uniquely identifies your end user and avoid using personally identifiable information (PII) like names.


      _10
      twilio api:conversations:v1:conversations:participants:create \
      _10
      --conversation-sid=CH1cbf85a0e7c844fca4cb4d2fad880196 \
      _10
      --identity=customer


      _10
      SID Messaging Binding
      _10
      MBb3469eabc7d040dbadc89a7876eb263f null

    3. Add a scoped webhook with "studio" as the target using the Conversations Webhook endpoint. With a scoped webhook set to Studio and the configuration filter set to "onMessageAdded", any message that is added to the conversation will invoke the "Incoming Conversation" trigger on the specified Studio flow.


      _10
      twilio api:conversations:v1:conversations:webhooks:create --target=studio --configuration.flow-sid=FWd945421fea3b172bb9c5889a22d2f410 --configuration.filters='onMessageAdded' --conversation-sid=CH1cbf85a0e7c844fca4cb4d2fad880196


      _10
      SID Target
      _10
      WH3bd00957227d499991c9a4ce5cd303e9 studio

  3. Now the Conversations SDK is initialized. Your participant can send a message.
  4. Your app makes use of the Conversations SDK to send the message. For the purposes of this guide, we will use the Twilio CLI to send a message on behalf of your participant. It's important to specify the x-twilio-webhook-enabled property to ensure any scoped or service webhooks are invoked.


    _10
    twilio api:conversations:v1:conversations:messages:create --author=customer --body=hello --conversation-sid=CH1cbf85a0e7c844fca4cb4d2fad880196 --x-twilio-webhook-enabled=true

  5. When the first message is sent, it will trigger the Studio Flow you set in step 2.3.
  6. The Conversations Service will find your conversation and send an "onMessageAdded" event to your Studio Flow.
  7. In your flow, you need to use the Send To Flex widget to route your participant, "customer" in this case, to an agent on Flex. Under the hood, the Send To Flex widget invokes the Interactions API to create a task and have it routed. Here's an example Interactions API POST request that Send To Flex makes (you don't need to do this since Studio does it on your behalf when you set Studio as the target for "onMessageAdded"):


    _30
    CHANNEL=$(cat << EOF
    _30
    {
    _30
    "type": "web",
    _30
    "initiated_by": "Customer",
    _30
    "properties": {
    _30
    "media_channel_sid": "CHXXX"
    _30
    }
    _30
    }
    _30
    EOF
    _30
    )
    _30
    _30
    ROUTING=$(cat << EOF
    _30
    {
    _30
    "type": "TaskRouter",
    _30
    "properties": {
    _30
    "workspace_sid": "WSXXX",
    _30
    "workflow_sid": "WWXXX",
    _30
    "attributes": {
    _30
    "channelType": "web",
    _30
    "from": "customer"
    _30
    }
    _30
    }
    _30
    }
    _30
    EOF
    _30
    )
    _30
    _30
    curl -X POST "https://flex-api.twilio.com/v1/Interactions" \
    _30
    --data-urlencode "Channel=$CHANNEL" \
    _30
    --data-urlencode "Routing=$ROUTING" \
    _30
    -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

  8. The Flex agent will get a task reservation and when they accept it, they will get added to the same conversation.

Rate this page: