Custom Media attached to Conversations

Conversations may have Custom Media attached to them that allows the customers to view information related to the conversation after it has ended. Custom Media can point to resources related to the conversation or its segments, such as Chat Transcripts and Call Recordings.

To attach Custom Media to a Conversation, you update the TaskRouter Task and pass specific attributes depending on the type of Custom Media you want to attach. To update the TaskRouter Task, you make an API call to the URL:

https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks/WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Replace WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX with your Twilio Workspace SID, and WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX with the TaskRouter Task's SID. The example below uses curl to call the TaskRouter API URL and passes all of the necessary attributes to attach a media link to a Conversation.

ATTRIBUTES=$(cat << EOF
{
    "conversations": {
      "media": [
        {
          "type": "Referenced",
          "url": "https://externalsystem.com/record-id2",
          "title": "External Ticket"
        }
      ]
    }
}
EOF
)
curl -X POST https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks/WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
--data-urlencode "Attributes=$ATTRIBUTES" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

If you are looking to use library-specific methods to update the TaskRouter Task, check out Update a Task resource.

Add Media Links

Each segment can have multiple media links related to it. You can provide links on the task level and/or on the reservation level.

• Task-level media links. The media links are attached to all segments related to the task.
• Reservation-level media links. The media are attached to all segments related to the reservation. Reservation-level media links override task-level media links. If a reservation has related media links no media links from the task level are attached.

Example TaskRouter attributes structure for task-level media links:

{
  "conversations": {
    "media": [
      // media links list goes here   
    ]
  }
}

Example TaskRouter attributes structure for reservation-level media links:

{
  "reservation_attributes": {
    "<reservation_sid_1>": {
      "media": [
         // media links list goes here
      ]
    }
  }
}

Raw Media Link

Raw media links are passed as-is to Historical Reporting. This means that when you drill down, the link is opened in a new browser tab or you can respond to clicks on that link and create custom drill down behavior in Flex.

{
  "conversations": {
    "media": [
      {
        "type": "Raw",
        "url": "https://company.com/record-id",
        "title": "CRM Conversation Record"
      }
    ]
  }
}

Embedded Media Link

Embedded media links can display a custom webpage on the Conversation Screen in an iFrame. This type of media link is useful for referencing tickets, CRM records and similar content related to the conversation. The web application that you embed has to support unique URLs for records that you are interested in so you can point to the content directly related to a conversation.

{
  "conversations": {
    "media": [
      {
        "type": "Embedded",
        "url": "https://company.com/tickets/ticket-id",
        "title": "Support Ticket"
      }
    ]
  }
}

Note Some web applications do not enable embedding for their content, or require configuration on their side to enable embedding. In case a web application does not enable embedding, use the referenced media link type instead.

Referenced Media Link

Referenced media links are useful for linking to external web pages related to a conversation. Referenced media links are shown as links in Conversation Screen.

{
  "conversations": {
    "media": [
      {
        "type": "Referenced",
        "url": "https://externalsystem.com/record-id",
        "title": "External Ticket"
      }
    ]
  }
}

Voice Recording Media Link

Voice Recording Media Links reference voice call recordings that users can playback and listen to in case they need to drill down to a conversation.

{
  "conversations": {
    "media": [
      {
        "type": "VoiceRecording",
        "url": "https://exampleurl.com",
        "start_time": 1574350320000,
        "channels": [
          "customer",
          "others"
        ],
        "title": "Dual channel recording"
      }
    ]
  }
}

Note When call recording is enabled in Flex, you do not typically have to provide a link to a voice recording.

Chat Transcript Media Link

Chat Transcript media link references a chat transcript made by Twilio Programmable Chat.

{
  "conversations": {
    "media": [
      {
        "type": "ChatTranscript",
        "sid": "CHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    ]
  }
}

Multiple Media Links

Media link lists can have multiple items in them. When users drill down to a conversation with multiple media attached to them, they can switch between them.

In the following case there is a specific behavior for media links:

• When Raw media link is on the first position in the list then when customers drill down to a conversation Conversation Screen does not open. The Raw media link is open in a new browser window/tab. The other media links are not accessible from Flex user interface.

The following example shows multiple media links in a conversation. The Conversation Screen will offer users to switch between the chat transcript and the embedded content.

{
  "conversations": {
    "media": [
      {
        "type": "Embedded",
        "url": "https://company.com/ticket-id",
        "title": "Support Ticket"
      },
      {
        "type": "ChatTranscript",
        "sid": "CHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      },
      {
        "type": "VoiceRecording",
        "url": "https://exampleurl.com"
      }
    ]
  }
}

Respond to Drilldowns in Historical Reporting

When users click on a conversation in Flex Insights Flex shows either a call, chat transcript or a list of custom media provided via TaskRouter attributes. Users can change this behavior. The primary use of custom response to drill downs is to respond to Raw media links.

import { Actions } from "@twilio/flex-ui"

Actions.replaceAction("HistoricalReporting:view", async (url, original) => {

    // implement your own handling of URL or call original(url) to use the original handler
})

Developers can decide whether they want to handle each drill down themselves or pass it to Flex to handle the drill down. This can be based on the URL that a user clicked or based on any other conditions.