The information on this page pertains to the legacy version of Botkit, 0.7 and below and may be out of date! Documentation for the new v4+ version of Botkit can be found here.

Botkit and Twilio Programmable SMS

Getting Started

1) Install Botkit more info here

2) Register a developer account with Twilio. Once you've got it, head to the Get Started with SMS page in your Twilio Console.

After completing the tutorial above you should have all three values to get your bot running: A Twilio Account SID, a Twilio Auth Token, and a Twilio Number.

Twilio Account SID and Auth Token

These values are available on your Twilio Account Settings page on the Twilio Console. Copy both the SID and token values (located under API Credentials)

Twilio Number

You should have purchased a Twilio Number. You will send/receive messages using this phone number. Example: +19098765432

3) Configure your Twilio Number. Head to the Phone Numbers in your Twilio Console and select the phone number you will use for your SMS bot.

Under the Messaging section, select "Webhooks/TwiML" as your Configure with preference. Two more fields will pop up: A message comes in, and Primary handler fails.

The first one is the type of handler you will use to respond to Twilio webhooks. Select "Webhook" and input the URI of your endpoint (e.g. and select HTTP POST as your handling method.

Twilio will send POST request to this address every time a user sends an SMS to your Twilio Number.

By default Botkit will serve content from https://YOURSERVER/sms/receive. If you are not running your bot on a public, SSL-enabled internet address, you can use a tool like or to expose your local development enviroment to the outside world for the purposes of testing your SMS bot.

The second preference ("Primary handler fails") is your backup plan. The URI Twilio should POST to in case your primary handler is unavailable. You can leave this field in blank for now but keep in mind this is useful for error handling (e.g. to notify users that your bot is unavailable).

4) Run the example Twilio SMS bot included in Botkit's repository (twilio_sms_bot.js). Copy and paste the example bot's code into a new JavaScript file (e.g. twilio_sms_bot.js) in your current working directory and run the following command on your terminal:


Note: Remember to run localtunnel or ngrok to expose your local development environment to the outside world. For example, in localtunnel run lt --port 5000 --subdomain mysmsbot (See note on step 4)

6) Your bot should be online! Grab your phone and text hi to your Twilio Number and you will get a Hello. message back!

Create a controller

To connect Botkit to Twilio SMS, use the constructor method, Botkit.twiliosmsbot(). This will create a Botkit controller with all core features as well as some additional methods.


Argument Description
config an object containing configuration options

Returns a new Botkit controller.

The config argument is an object with these properties:

Name Type Description
studio_token String An API token from Botkit Studio
debug Boolean Enable debug logging
account_sid found in your Twilio Console Dashboard
auth_token found in your Twilio Console Dashboard
twilio_number your app's phone number, found in your Phone Numbers Dashboard The phone number format must be: +15551235555

For example:

var Botkit = require('botkit');
var controller = Botkit.twiliosmsbot({
  account_sid: process.env.TWILIO_ACCOUNT_SID,
  auth_token: process.env.TWILIO_AUTH_TOKEN,
  twilio_number: process.env.TWILIO_NUMBER


Note: This document assumes that you are familiarized with Botkit and Twilio's Programmable SMS API

To connect your bot to Twilio you must point a Messaging webhook to http://your_host/sms/receive, after doing so, every Twilio message will be sent to that address.

Then you need to write your bot. First, create a TwilioSMSBot instance and pass an object with your configuration properties:

const Botkit = require('botkit')
const controller = Botkit.twiliosmsbot({
  account_sid: process.env.TWILIO_ACCOUNT_SID,
  auth_token: process.env.TWILIO_AUTH_TOKEN,
  twilio_number: process.env.TWILIO_NUMBER

spawn() your bot instance:

let bot = controller.spawn({})

Then you need to set up your Web server and create the webhook endpoints so your app can receive Twilio's messages:

controller.setupWebserver(process.env.PORT, function (err, webserver) {
  controller.createWebhookEndpoints(controller.webserver, bot, function () {
    console.log('TwilioSMSBot is online!')

And finally, you can setup listeners for specific messages, like you would in any other botkit bot:

controller.hears(['hi', 'hello'], 'message_received', (bot, message) => {
  bot.startConversation(message, (err, convo) => {
    convo.say('Hi, I am Oliver, an SMS bot! :D')
    convo.ask('What is your name?', (res, convo) => {
      convo.say(`Nice to meet you, ${res.text}!`)

controller.hears('.*', 'message_received', (bot, message) => {
  bot.reply(message, 'huh?')

See full example in the examples directory of this repo.

Sending media attachments (MMS)

To send media attachments, pass a mediaUrl property to any of Botkit's outgoing messages functions (reply, say, ask, etc.) with an optional text property for text that goes along with your attachment.

  Sending an attachment
bot.reply(message, {
  text: 'Optional text to go with attachment',
  mediaUrl: ''

Note: your Twilio number as well as the recipient's phone must support MMS for media attachments to work

For more details on outgoing media attachments and a full list of accepted MIME types, go to Twilio's docs on media attachment.

Is something missing or out of date?

This file is managed on Github. click here to view the source, and send us a pull request with your improvements!

Back to top