Integrate a Custom Chat Client with Flex
Info
This guide is for Flex UI 1.x.x and channels that use Programmable Chat and Proxy. If you are using Flex UI 2.x.x or you are starting out, we recommend that you build with Flex Conversations.
You may have already built a custom chat experience with Programmable Chat or from scratch. You can integrate these chat experiences with Flex and hand off incoming Chat messages to your agents.
Info
Custom chat integrations require a Flex Flow ChannelType of custom.
First, initialize the Twilio Chat SDK using an access token that links a user with a unique identity - for example: abc123. The Chat SDK is going to help you pass messages back and forth with Flex.
Warning
Make sure this identity uniquely identifies your end user and avoid using personally identifiable information like names.
_32const AccessToken = require('twilio').jwt.AccessToken;
_32const ChatGrant = AccessToken.ChatGrant;
_32// Used when generating any kind of tokens
_32// To set up environmental variables, see http://twil.io/secure
_32const twilioAccountSid = process.env.TWILIO_ACCOUNT_SID;
_32const twilioApiKey = process.env.TWILIO_API_KEY;
_32const twilioApiSecret = process.env.TWILIO_API_SECRET;
_32// Used specifically for creating Chat tokens
_32const serviceSid = process.env.TWILIO_CHAT_SERVICE_SID;
_32const identity = 'user@example.com';
_32// Create a "grant" which enables a client to use Chat as a given user,
_32const chatGrant = new ChatGrant({
_32 serviceSid: serviceSid,
_32// Create an access token which we will sign and return to the client,
_32// containing the grant we just created
_32const token = new AccessToken(
_32token.addGrant(chatGrant);
_32// Serialize the token to a JWT string
_32console.log(token.toJwt());
Now you need to:
-
Ensure you have a relevant Message Handler. You can add
Studio
to the communication flow, immediately create a task, or do something else entirely depending on how you've configured your
Flex Flow
.
-
Create a Flex Chat Channel (or reuse one if this is a return customer and you're using Long Lived channels)
-
Creating a Channel will also automatically create a Chat User and place it in the Channel.
This configuration could require a minimum of four API requests, but with Flex you can do everything with a single request to Flex Chat Channels API.
_22// Download the helper library from https://www.twilio.com/docs/node/install
_22const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_22// Find your Account SID and Auth Token at twilio.com/console
_22// and set the environment variables. See http://twil.io/secure
_22const accountSid = process.env.TWILIO_ACCOUNT_SID;
_22const authToken = process.env.TWILIO_AUTH_TOKEN;
_22const client = twilio(accountSid, authToken);
_22async function createChannel() {
_22 const channel = await client.flexApi.v1.channel.create({
_22 chatFriendlyName: "Chat with abc123",
_22 chatUserFriendlyName: "Jane",
_22 flexFlowSid: "FOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_22 console.log(channel.accountSid);
_10 "flex_flow_sid": "FOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10 "sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10 "task_sid": "WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10 "user_sid": "USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10 "date_created": "2016-08-01T22:10:40Z",
_10 "date_updated": "2016-08-01T22:10:40Z",
_10 "url": "https://flex-api.twilio.com/v1/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Now you can use the Twilio Chat SDK to manage communications on the Chat Channel you created with Flex:
-
When
a message comes in
, you'll receive a
messageAdded
event and can render it in your custom UI.
-
When
you need to send a message
, the SDK includes a
sendMessage()
method that you can use to publish media over the Twilio Chat Channel.