Botium Connector for Twilio SMS

This is a Botium connector for testing SMS bots.

Did you read the Botium in a Nutshell articles? Be warned, without prior knowledge of Botium you won't be able to properly use this library!

How it works

Connector using Programmable SMS of Twilio to send and receive SMS messages in order to test any SMS bot.

The Connector can be used as any other Botium connector with all Botium Stack components:

• Botium CLI
• Botium Bindings
• Botium Box

To receive messages from Twilio API a public endpoint is required.

• This endpoint has to be configured depending on usage:
  • If used from Botium Box, its provided automatical. Redis is required for communication between Connector and Box.
  • Connector can be started with integrated endpoint (see TWILIO_SMS_INBOUNDPORT and TWILIO_SMS_INBOUNDENDPOINT capabilities)
  • Endpoint is provided by the Botium Twilio Webhook Proxy included in this module. Redis is required for communication between Connector and Box.
• This endpoint has to be public:
  • If used from Botium Box, then no addititional steps are required.
  • If the server is not public, then the easiest way to use Twilio cli (which uses ngrok internally) to make it public.
    • in case of integrated endpoint: twilio phone-numbers:update "<<TWILIO_SMS_FROM>>" --sms-url="http://localhost:<<TWILIO_SMS_INBOUNDPORT>><<TWILIO_SMS_INBOUNDENDPOINT>>/sms"
    • If you use Botium Twilio Webhook Proxy, then it displays the complete command for Twilio cli
  • Or use ngrok: ngrok http <<TWILIO_SMS_INBOUNDPORT>>
• This endpoint has to be registered in Twilio:
  • If you use Twilio cli to make endpoint public, then it registers the endpoint.
  • You can use Twilio cli just for registering twilio phone-numbers:update [PN sid or E.164] --sms-url http://url (see more)
  • Or you can use Twilio console to do it

Twilio API is not free, see pricing here.

Prerequisites

• Node.js and NPM
• (optional) a Redis instance (Cloud hosted free tier for example from redislabs will do as a starter)
• Twilio Account (See trial account limitation of Twilio here)
  • Note accountSid and authToken
• Purchased, or verified Twilio phone number with SMS capabilities enabled
• A project directory on your workstation to hold test cases and Botium configuration

Install Botium and Twilio SMS Connector

When using Botium CLI:

> npm install -g botium-cli
> npm install -g botium-connector-twilio-sms
> botium-cli init
> botium-cli run

When using Botium Bindings:

> npm install -g botium-bindings
> npm install -g botium-connector-twilio-sms
> botium-bindings init mocha
> npm install && npm run mocha

When using Botium Box:

Already integrated into Botium Box, no setup required

Install and Run the Botium Twilio Webhook Proxy

Proxy has two goals:

• Provides endpoint for Twilio to receive incoming messages
• Sends messages to Connector using Redis.

Installation with NPM:

> npm install -g botium-connector-twilio-sms
> botium-twilio-sms-proxy-cli start --help

There are several options required for running the Botium webhook service:

--port: Local port to listen (optional, default 5002)

--redisurl: Redis connection url (optional, default redis://localhost:6379)

Connecting Twilio to Botium

Open the file botium.json in your working directory fill it. See Supported Capabilities.

Connect the Connector to the Proxy using Redis:

{
  "botium": {
    "Capabilities": {
      "PROJECTNAME": "<whatever>",
      "CONTAINERMODE": "twilio-sms",
      "TWILIO_SMS_ACCOUNT_SID": "...",
      "TWILIO_SMS_AUTH_TOKEN": "...",
      "TWILIO_SMS_FROM": "...",
      "TWILIO_SMS_TO": "...",
      "TWILIO_SMS_REDISURL" : "..."
    }
  }
}

Or start a standalone connector with own endpoint:

{
  "botium": {
    "Capabilities": {
      "PROJECTNAME": "<whatever>",
      "CONTAINERMODE": "twilio-sms",
      "TWILIO_SMS_ACCOUNT_SID": "...",
      "TWILIO_SMS_AUTH_TOKEN": "...",
      "TWILIO_SMS_FROM": "...",
      "TWILIO_SMS_TO": "...",
      "TWILIO_SMS_INBOUNDPORT": "..."
    }
  }
}

Botium setup is ready, you can begin to write your BotiumScript files.

Supported Capabilities

Set the capability CONTAINERMODE to twilio-sms to activate this connector.

TWILIO_SMS_ACCOUNT_SID

See accountSid in Prerequisites

TWILIO_SMS_AUTH_TOKEN

See authToken in Prerequisites

TWILIO_SMS_FROM

Purchased, or verified phone number

TWILIO_SMS_TO

Telephone number.

TWILIO_SMS_INBOUNDPORT and TWILIO_SMS_INBOUNDENDPOINT

only required when NOT using the Botium Twilio Webhook Proxy

Local port and endpoint to be used for launching the webhook

The default of TWILIO_SMS_INBOUNDENDPOINT is "\"

TWILIO_SMS_REDISURL and TWILIO_SMS_REDIS_TOPICBASE

only required when using the Botium Twilio Webhook Proxy

Redis Url and base topic name for Redis subscription topic.

The default url for local redis is redis://localhost:6379

TWILIO_SMS_INBOUNDENDPOINT is optional.

Changelog

0.1.0

• Twilio cli is removed from dependencies. (It is a heavy but optional package)
• All version numbers updated.