Menu

Expand
Rate this page:

Send Outbound Messages via SMS, WhatsApp and Other Channels

Flex allows your agents to initiate conversations with your customers via any Twilio Messaging Channel, including SMS, WhatsApp, and Facebook Messenger.

Currently, outbound messages require additional development work. This page outlines some of the work you'll need to do for the backend but outbound messages will also require a Flex UI Plugin to expose the functionality in the Flex interface.

Managing Task Creation

There are two ways to handle task creation for outbound messages: when the agent messages the customer (immediately) or when the customer responds to the outbound message (delayed).

Outbound messages require a Flex Flow ChannelType of sms, whatsapp, facebook, or custom.

Strategy 1: Create Task When Agent Messages Customer

The following steps will create a task when you send an outbound message to your customer.

1. Define a Flex Flow

First, define an outbound Flex Flow with an Integration type of task. You only need to do this once. Please ensure you are also defining your Flex Flow to use a Messaging capable Task Channel such as sms or chat. If you already have a Flex Flow that's using Studio, then the enabled parameter must be set to false.

        
        
        

        2. Create a Flex Chat Channel

        Next, create a Chat Channel using the Flex API to initiate messaging with the customer. In this example, the API call also adds Task Attributes, which will allow the channel to route the task to a specific agent (using the targetWorker Workflow expression).

        Make sure to save the SID of the Chat Channel - you'll need it later!

              
              
              

              Once the Flex Channel API is executed succesfully, two things happen:

              • A new chat channel is created
              • A new task is created and assigned to the worker specified in targetWorker

              Then, if you open the Flex UI for targetWorker, you should see the following new reservation:

              Outbound Chat reservation in Flex

              3. Set up a Twilio Proxy Session

              Now that you have a channel, you'll want to associate it with a Proxy Session. Sessions offer a useful layer of state and metadata that Flex uses to ensure that your customers' messages stay properly threaded as they are processed by bots, TaskRouter and agents.

              You'll need to make two requests:

              The first creates the Proxy Session, and includes the person you're trying to reach.

              The second request adds the chat channel to the session, and maps it to the Contact Center number.

              Consider enabling the Channel Janitor to help manage any stale chat sessions.

                    
                    
                    

                    In the sample code, you need to replace:

                    {{CUSTOMER_NUMBER}} The phone number of the customer you are trying to reach
                    {{SID_FROM_CHANNELS_API}} The SID for the Chat Channel created in Step 2. Here, it is being used as a name for the Proxy Session, which helps you (and Flex) find it.

                    You'll also need to add the agent to the Proxy Session, using their Chat Channel SID as their identifier and the Contact Center number as their Proxy identifier, since messages from the agent should look like they're coming from the Contact Center.

                    Finally, if you want the agent to see the Customer's number when they respond to the chat, make the Agent's friendly name the customer's number.

                          
                          
                          

                          In the sample code, you need to replace:

                          CONTACT_CENTER_NUMBER This is the contact center phone number, channel number, or agent number from which the message will be sent. This is likely the same number you used as contactIidentity when you created the Flex Flow.
                          CHAT_CHANNEL_SID The SID of the chat channel you created using the Channel API in Step 2. This tells Proxy that the agent will be sending messages over this channel.

                          3. Update the Chat Channel Attributes

                          Update the Chat Channel attributes to include the Proxy Session SID you created in Step 3 if it's not already there. The chat channel attributes should be a JSON string:

                          {proxySession: "KCXXXXXXXXXXXXXXXXXXXXXXXX"}

                          Make sure that you retrieve the existing attributes object, add the proxySession key, and then update the parameter as a string.

                                
                                
                                

                                4. Start chatting

                                Now, go back to Flex and accept the reservation. Your agent can directly message into the Chat interface, and messages are routed to the customer on their Twilio Channel.

                                Strategy 2: Create Task When Customer Responds

                                The following steps outline an alternate architecture for sending a message to the customer. When the customer responds, the inbound message handler will create a Task and forward it to an agent.

                                1. Configure inbound messages

                                Make sure you set up an inbound message handler, and that it's configured to create a Task. This will handle the customer's response to the outbound message. Please ensure you are also defining your Flex Flow to use a Messaging capable Task Channel such as sms or chat.

                                If you already handle inbound messages and want to use that logic, you can use the code sample below to retrieve all Flex Flows on the account - simply choose the SID of the one associated with your current message handler for your desired channel (e.g., the SMS message handler).

                                      
                                      
                                      

                                      2. Create a Channel

                                      Create a chat channel using the Flex Channel Resource. You'll need the Flex Flow for outbound messages. You'll need a new channel for each interaction.

                                      You may see multiple SIDs associated with a Flow - some might be for Twilio Studio. You need to use a Flex Flow SID, which will begin with the letters FO.

                                            
                                            
                                            

                                            3. Create a Proxy Session

                                            Now you'll need to create a Proxy Session in order to associate the Chat Channel and the Customer's Phone number together. Sessions offer a useful layer of state and metadata that Flex uses to ensure that your customers' messages stay properly threaded as they are processed by bots, TaskRouter and agents. It will help tell Flex that, when the customer responds, they should be talking to this Agent over this Channel. Pass the channel you created in Step 2 as the Unique Name of the Session.

                                            In the sample code, you need to replace:

                                            {{CHAT_CHANNEL_SID}} The chat channel that the agent will be using to respond to the customer, which you created in Step 2.
                                            {{CONTACT_CENTER_NUMBER}} The contact center/agent ID (the number the SMS will be sent from). This is the same number you used as contactIdentity when you created the Flex Flow. This could be a WhatsApp Number, or any other identifier for another messaging channel.
                                                  
                                                  
                                                  

                                                  Use another request to add the customer, using their number as the identifier. Proxy can use its own logic to select the Proxy identifier.

                                                        
                                                        
                                                        

                                                        4. Update the Chat Channel Attributes

                                                        Update the Chat Channel attributes to include the Proxy Session SID you created in Step 3 if it's not already there. The chat channel attributes should be a JSON string:

                                                        {proxySession: "KCXXXXXXXXXXXXXXXXXXXXXXXX"}

                                                        Make sure that you retrieve the existing attributes object, add the proxySession key, and then update the parameter as a string.

                                                              
                                                              
                                                              

                                                              5. Send the message

                                                              Now you can manually send your outbound message with a Proxy Messaging Interaction. This will invoke the Flex Message Handler - for example, if you're using Studio, then it will trigger the Studio Flow as an outbound message to your customer.

                                                              MESSAGE_CONTENT This is the message content that you can send in the message. Note that this content may not appear (e.g., if you're using a Studio Flow that doesn't use the Trigger Widget's body property.
                                                              AGENT_PROXY_PARTICIPANT_SID The SID for the Agent's Participant Resource. This will tell Proxy to send a message from the Agent to the Customer using the identifiers stored in Proxy.
                                                                    
                                                                    
                                                                    

                                                                    Your customer should now receive a message. When they respond, a Task will be created, and you can route it to an agent who can accept and handle the response.

                                                                    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 Community Forums or browsing the Twilio tag on Stack Overflow.

                                                                          
                                                                          
                                                                          

                                                                          Thank you for your feedback!

                                                                          We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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

                                                                          Thanks for your feedback!

                                                                          Refer us and get $10 in 3 simple steps!

                                                                          Step 1

                                                                          Get link

                                                                          Get a free personal referral link here

                                                                          Step 2

                                                                          Give $10

                                                                          Your user signs up and upgrade using link

                                                                          Step 3

                                                                          Get $10

                                                                          1,250 free SMSes
                                                                          OR 1,000 free voice mins
                                                                          OR 12,000 chats
                                                                          OR more