Menu

Expand
Rate this page:

Thanks for rating this page!

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

Twilio Conversations Quickstart

Public Beta

Twilio's Conversations API is currently available as a Public Beta product. Some features are not yet implemented and others may be changed before the product is declared as Generally Available.

Public Beta products are not covered by a Twilio SLA.

With Twilio’s Conversations API, you can build virtual spaces ("conversations") for customers to communicate across multiple channels.

Instead of building separate solutions for Chat versus SMS engagement, you now have one API to create customer engagement across all of them.

This Quickstart will cover:

  • Signing up for Twilio and provisioning your first SMS-enabled phone number
  • Creating your first Conversation with the Conversations API
  • Connecting an SMS participant to a Conversation
  • Configuring a Chat application
  • Adding a Chat participant to a Conversation

You will need:

  • Your Twilio credentials (Twilio Account SID and Twilio Auth Token) found in the Console
  • An installed version of the twilio-cli (We'll go over how to install and set this up.)
  • A CodeSandbox account

Twilio Conversations is built on top of several Twilio products. It may also be useful to pull up a document or sticky note to keep track of the various values that you'll need throughout this Quickstart.

Let's get started!

If you’ve already signed up for Twilio and have an SMS-enabled phone number, you can skip ahead to creating your first Conversation.

Before you create your first Conversation, you'll need to sign up for a Twilio account or sign into your existing account and purchase an SMS-capable phone number.

You can sign up for a free Twilio trial account here.

  • When you sign up, you'll be asked to verify your personal phone number. This helps Twilio verify your identity and also allows you to send test messages to your phone from your Twilio account while in trial mode.
  • Once you verify your number, you'll be asked to create a project. For the sake of this tutorial, you can click on the "Learn and Explore" template. Give your project a name, or just click "skip remaining steps" to continue with the default.
  • Once you get through the project creation flow, you'll arrive at your project dashboard in the Twilio Console. This is where you'll be able to access your Account SID, authentication token, find a Twilio phone number, and more.

If you don't currently own a Twilio phone number with SMS functionality, you'll need to purchase one. After navigating to the Buy a Number page, check the "SMS" box and click "Search."

Buy a SMS-Capable Twilio Phone Number

You’ll then see a list of available phone numbers and their capabilities. Find a number that suits your fancy and click "Buy" to add it to your account.

Select an SMS-enabled phone number

Now that you have a Twilio account and a programmable phone number, you can start writing some code.

Number in hand, let's do this!

Create your first Conversation

It's time to make our first Conversation:

        
        
        
        
        Create a Conversation with a FriendlyName using the REST API

        Create your first Conversation

        Create a Conversation with a FriendlyName using the REST API

        Copy down the Conversation SID (It starts with “CHXXX...”). Now, let's use it to fetch that Conversation we just created.

              
              
              
              
              Retrieve your new Conversation to find the Chat Service SID

              Fetch your new Conversation

              Retrieve your new Conversation to find the Chat Service SID

              Copy down the Chat Service SID (It starts with "ISXXX..."), and make sure you've copied the Conversation SID (It starts with “CHXXX...”) as well. We’ll be using these values in the next few steps when we add participants to the Conversation you just created.

              Ready to add some participants

              Add an SMS participant to a Conversation

              You’ve created a Conversation, which you can think of as a virtual space for users to join from the channel of their choice.

              Next, you’ll add your first participant: someone connecting to the Conversation with an SMS-enabled phone number. (Hint: Use the number that you purchased up above.)

              For the following code sample, replace the placeholder values for:

              • CHXXX...: use the Conversation SID you just copied
              • <Your Personal Mobile Number>: your own mobile number, in E.164 format
              • <Your Purchased Twilio Phone Number>: the Twilio number you purchased in step 1, in E.164 format
              • ACXXX...: Your Twilio Account SID
              • your_auth_token: Your Twilio Auth Token
                    
                    
                    
                    
                    Create an SMS-based Conversation Participant with the REST API

                    Add a Conversation Participant (SMS)

                    Create an SMS-based Conversation Participant with the REST API

                    Now you have one SMS Participant in the Conversation that you created!

                    Cool, but who do they talk to?

                    Configure the demo Chat application using CodeSandbox.io

                    Great, you’ve got a Conversation with an SMS Participant. Just one problem: it’s quiet because it’s hard to have a conversation with just one person.

                    It's time to add a second Chat-based Participant to talk with your SMS-based Participant.

                    Sign into CodeSandbox and fork our demo application

                    For this Quickstart, we’ll be using a basic Chat application to join our Conversation. We need to take a quick detour to set up the sample Chat application.

                    For your convenience, we’ve created a demo application that provides a basic Javascript-based chat interface in which you can send and receive messages in your new Conversation.

                    Sign in to Codesandbox.io and fork the demo app into your own Sandbox. CodeSandbox is a cloud-based an online editor that we can use to host, update, and edit our sample chat application.

                    Conversations Demo App on CodeSandbox.io with arrow pointing to "Fork" button

                    Now that you have forked the demo application, you have your own sandbox and online editor to adapt the code. Your changes will be instantly reflected in the deployed application.

                    Install the twilio-cli tools

                    In order for your Chat Application to work, we need to authenticate a Chat user by retrieving a short-lived token attached to your API Key. We'll use the twilio-cli to generate a chat token that you can use in your application.

                    First, install the twilio-cli if you haven't done so already:

                    One of the easiest ways to install the CLI on Mac OS X is to use Homebrew. If you don't already have it installed, visit the Homebrew site for installation instructions and then return here.

                    Once Homebrew is installed, simply run the following command to install the CLI:

                    brew tap twilio/brew && brew install twilio
                    

                    Updating

                    If you already installed the CLI with brew and want to upgrade to the latest version, run:

                    brew upgrade twilio
                    

                    Warning for Node.js developers

                    If you have installed Node.js version 10.12 or higher on your Mac, you can avoid potential Node.js version conflicts by installing the CLI using npm:

                    npm install twilio-cli -g
                    

                    Before we can install, we need to make sure you have Node.js installed (version 10.12 or above). To see if you have node installed, try running this command:

                    node -v
                    

                    If your system reports v10.12.0 or above, you can skip the next step.

                    Installing Node.js on Windows

                    Using the Windows Installer (.msi) is the recommended way to install Node.js on Windows. You can download the installer from the Node.js download page.

                    Installing Twilio CLI

                    The CLI is installed with npm (Node Package Manager), which comes with Node.js. To install the CLI run the following command:

                    npm install twilio-cli -g
                    

                    Note the -g option is what installs the command globally so you can run it from anywhere in your system.

                    Updating

                    If you already installed the CLI with npm and want to upgrade to the latest version, run:

                    npm install twilio-cli@latest -g
                    

                    Before we can install, we need to make sure you have Node.js installed (version 10.12 or above). Even if you already installed Node yourself, the CLI works best when you install it using nvm. Here's how to get nvm installed on most Linux systems:

                    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash
                    

                    Please visit the nvm installation instructions for additional options and troubleshooting steps. Once you have nvm installed, run the following to install and use the most recent LTS release of Node.js:

                    nvm install --lts
                    nvm use <insert version reported from above>
                    

                    Installing other Twilio CLI prerequisites for Linux

                    Depending on your distribution, you will need to run one of the following commands:

                    • Debian/Ubuntu: sudo apt-get install libsecret-1-dev
                    • Red Hat-based: sudo yum install libsecret-devel
                    • Arch Linux: sudo pacman -S libsecret

                    Installing Twilio CLI

                    The CLI is installed with npm (Node Package Manager), which comes with Node.js. To install the CLI run the following command:

                    npm install twilio-cli -g
                    

                    Note the -g option is what installs the command globally so you can run it from anywhere in your system.

                    Updating

                    If you already installed the CLI with npm and want to upgrade to the latest version, run:

                    npm install twilio-cli@latest -g
                    

                    To access your Twilio account, you must provide your Twilio credentials to twilio-cli. This can be done by running this command:

                    twilio login
                    

                    You will be prompted for

                    • a "Shorthand identifier for your Twilio profile": This can be anything, e.g, project-danger
                    • your Account SID and Auth Token, both of which you can find on the dashboard of your Twilio console.

                    This will create an API Key for you that will be stored securely for future use.

                    Install the twilio token plugin and generate your token

                    Next, run the following command to add the twilio token plugin that handles token generation:

                    twilio plugins:install @twilio-labs/plugin-token
                    

                    You can create a token with this command, replacing the arguments with your own values:

                    twilio token:chat --identity testPineapple --chat-service-sid ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
                    

                    For the value you pass to identity, use the username that your Chat user will use to log into the demo Chat application. Use any identity that you like. May we suggest "testPineapple"?

                    For your chat-service-sid, use the unique Chat service SID starting with "ISXXX..." that you copied after creating your Conversation.

                    Copy the chat token that is returned from your cURL request and paste it into the ChatApp.js placeholder field in the getToken function.

                    conversations-paste-token-800.png

                    Reload your Chat application, which now includes a chat token for your chosen identity (i.e., the one you just created when you cURLed the function). Log in with that identity.

                    conversations-login-reload-800.png

                    Once you see "You are connected." You know that you have logged into the Chat application:

                    conversations-demo-no-conversations-800.png

                    Phew! Your Chat Application is all set up and ready to go. We're on to the last part: adding this Chat participant to your Conversation.

                    Let's do this!

                    Add a Chat participant to a Conversation

                    Let’s add a chat participant to our Conversation so it isn’t so lonely in there. The following code sample adds a Conversation Participant by Chat to the Conversation. You will need to replace the following information:

                    • Conversation SID: the same CHXXX SID that you used previously
                    • Identity: the identity that you just created in the demo Chat application (For this example, we'll use "testPineapple")
                          
                          
                          
                          
                          Create a Chat-based Conversation Participant with the REST API

                          Add a Conversation Participant (Chat)

                          Create a Chat-based Conversation Participant with the REST API

                          After you run this code, you should see a link with your Conversation's "friendly name" pop up in the Chat Application. That means you’re connected and can start chatting!

                          conversations-demo-convo-added-800.png

                          I have many things to say to myself.

                          Talk amongst "yourself"

                          New Conversation? Check! Working Chat application? Check! Two participants? Check!

                          It’s time to start talking. On your mobile phone, send a text message to the Twilio number you used to set up your Conversation. Your Chat application should receive the same message almost immediately!

                          conversations-demo-full-conversation-800.png

                          If you reply in the Chat application browser, you'll receive the message as a text on your phone. Notice how all of this routing between the two channels is done automatically on your behalf. Three REST requests in, and you have a working use-case, congratulations!

                          What’s Next?

                          From here, you can add more participants to your Conversation via Chat or SMS. New participants start receiving new messages automatically, and deleting those same participants removes them from the Conversation.

                          Subject to regional SMS limitations, you can have any number of SMS participants (“user address”) for each Twilio number (“proxy address”), or you can have a separate proxy address for each of your users.

                          Want to know more about the Twilio Conversations API?

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