node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



Easily build conversations for Twilio, Facebook Messenger, and more.


Via NPM:

npm install convo-builder

You can also check out convo-builder directly from Git:

git clone

After cloning the Git repository, you have to install the node dependencies. Navigate to the root of your cloned repository and use npm to install all necessary dependencies.

npm install


var convo = require('convo-builder');
  port: 8145,
  twilio: {
    phoneNumber: '<YOUR_TWILIO_PHONE_NUMBER>'
var greeting = 'Hi! Here\'s a survey your coach wanted me to send you.';
var messages = [
  'Did you eat cake at least once this week?',
  'What one food would you most like to eat next week?',
  'On a scale from 1 to 5, how happy were you with this week\'s meal plan?'
var conclusion = 'Thanks for answering my questions! Enjoy the rest of your day.';
var options = {
  provider: 'twilio',
  providerOptions: {
convo.say(greeting, options, function (err) {
  convo.converse(messages, options, function (err, response, message) {
    if (!err) {
    console.log('The user\'s response to the message "' + message + '" was: ' + response);
    } else {
      console.log('An error occurred:');
  }, function () {
    convo.say(conclusion, options, function (err) {
      console.log('The conversation has finished.');



Takes an object that is used to configure convo-builder and the providers.

Available options:

  port: <Port number to listen for messages on>
  twilio: {
    ACCOUNT_SID: '<Twilio account SID>',
    AUTH_TOKEN: '<Twilio auth token>',
    phoneNumber: '<Twilio phone number>'
  messenger: {
    VERIFY_TOKEN: '<Verify token for Facebook messenger>',
    PAGE_ACCESS_TOKEN: '<Page access token for Facebook messenger>'
convo.say(message, options, callback)

Send the user a message using the provided options, takes an optional callback that runs after the message has been sent.

convo.converse(messages[], options, callback)

Sends the user an array of messages once at a time using the provided options, calls the provided callback with the user's response to each message in turn. Takes an optional callback that runs after all of the messages are sent.

Options for convo.say() and convo.converse()

  provider: '<Either messenger or twilio>',
  providerOptions: {
    phoneNumber: '<User phone number>' // For twilio 
    recipientId: '<User facebook id>' // For Facebook messenger