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. Programmable Chat for Flex will reach end of life on June 1, 2026. If you're new to Flex or currently using Programmable Chat, build with Flex Conversations or migrate.
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.
1const AccessToken = require('twilio').jwt.AccessToken;2const ChatGrant = AccessToken.ChatGrant;34// Used when generating any kind of tokens5// To set up environmental variables, see http://twil.io/secure6const twilioAccountSid = process.env.TWILIO_ACCOUNT_SID;7const twilioApiKey = process.env.TWILIO_API_KEY;8const twilioApiSecret = process.env.TWILIO_API_SECRET;910// Used specifically for creating Chat tokens11const serviceSid = process.env.TWILIO_CHAT_SERVICE_SID;12const identity = 'user@example.com';1314// Create a "grant" which enables a client to use Chat as a given user,15// on a given device16const chatGrant = new ChatGrant({17serviceSid: serviceSid,18});1920// Create an access token which we will sign and return to the client,21// containing the grant we just created22const token = new AccessToken(23twilioAccountSid,24twilioApiKey,25twilioApiSecret,26{identity: identity}27);2829token.addGrant(chatGrant);3031// Serialize the token to a JWT string32console.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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createChannel() {11const channel = await client.flexApi.v1.channel.create({12chatFriendlyName: "Chat with abc123",13chatUserFriendlyName: "Jane",14flexFlowSid: "FOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",15identity: "abc123",16target: "abc123",17});1819console.log(channel.accountSid);20}2122createChannel();
Response
1{2"flex_flow_sid": "FOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"task_sid": "WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",6"user_sid": "USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",7"date_created": "2016-08-01T22:10:40Z",8"date_updated": "2016-08-01T22:10:40Z",9"url": "https://flex-api.twilio.com/v1/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"10}
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.