Get started with Twilio’s programmable chat API

A guide to embedding chat directly into your web applications with Twilio and JavaScript

Have you ever needed to talk to a customer service representative but don’t have the time to wait on hold? Or maybe you need to get in touch with a company that is only open during business hours and you can’t leave your desk to run the errand?

Chat makes it easy for customers to communicate with businesses from home or work, without the frustration of long hold times. And businesses have the opportunity to provide a pleasant, personalized experience that keeps their customers happy, without putting a huge burden on resources. Best of both worlds.

With the power of flexible APIs, businesses and developers can now add chat capabilities to their applications.

Twilio’s Programmable Chat API enables you to build in-app chat between multiple parties across websites and mobile applications. It also supports message synchronization so that users can instantly access chat history and engage in conversations across different devices. You can even add advanced features like a typing indicator, message read status, topic search or mobile push notifications.

This tutorial focuses on building a web-based chat application in Node.js using the Twilio Programmable Chat JavaScript SDK. Twilio also provides Chat SDKs for Android and iOS, along with a server-side REST API — you can learn more about these in the section following the tutorial.

Get an API key

Before you start your first chat conversation, you need to sign up for a Twilio account and generate an API Key and API Key Secret in the Twilio Chat Console. Note that the API Key Secret is only shown once, so make sure that you save it in a safe and secure location. We will need it the upcoming steps.

Now that you have a Twilio account and an API Key, open up your text editor or IDE of choice - it’s time to write some code.

Get the JavaScript SDK Quickstart application

Next, we will install the JavaScript SDK Quickstart application by cloning this GitHub repository. This quickstart application is built with Node.js, but you can also check out the same project in C# .Net, Java, PHP, Python, and Ruby.

To grab our Node.js project, find a nice directory on your machine and clone the repository by running:

git clone

If you don’t have Node and NPM installed, on your machine now is a good time to install it.

Setting up the application

Now that we have our QuickStart application, we want to ensure its configured correctly. We need to create a configuration file to add all our configuration values. Type in the following command to create your configuration file.

cp .env.example .env

We need to add the following configuration parameters:

  • TWILIO_ACCOUNT_SID: Your primary Twilio account identifier—find this in the console here.
  • TWILIO_API_KEY: We created this at the beginning. You can also find this in the console here.
  • TWILIO_API_SECRET: Pull it up from the safe location you stored it earlier.

Edit .env with the three configuration parameters.

Before we can fire up the application, we also need to create a Twilio Chat service. This service uniquely identifies our chat application from others you might add to your Twilio account in the future.

Create a new Chat service in your Console and then use its Sid value to set the TWILIO_CHAT_SERVICE_SID variable in your .env file.

Last, we need to install our dependencies from NPM:

npm install

Running the application

Now we should be all set! Run the application:

npm start

Your application should now be running at http://localhost:3000. Head over to http://localhost:3000/chat to check out the Twilio Chat demo.

You’re now in your own chat room! Open another tab and join the same room—you’ll get a different random username you can use to chat with yourself.

Chat with a friend

If you haven’t already, install ngrok and ensure the ngrok command is on your system path. The following command would use ngrok to expose port 3000 to the public Internet. This would allow you to share the chat room public URL link with a friend to find a more interesting conversation partner:

ngrok http 3000

Where to next?

Twilio Chat also has SDKs for iOS and Android platforms. Check out the iOS and Android quickstarts to learn more.

Now that you know the basics of how to build a Twilio Chat application, you might want to check out these Twilio resources for more advanced applications and use cases:

Happy coding!

This article is published as part of the IDG Contributor Network. Want to Join?