botium-connector-whatsapp v0.0.3

Botium Connector for Whatsapp Webhooks

This is a Botium connector for testing your Whatsapp Business API Webhooks.

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 ?

Botium emulates the Whatsapp Business API

• It sends inbound messages to your webhook
• It listens for outbound messages from your webhook

Redis is used to connect the webhook to Botium scripts: all messages received over the webhook are published to Redis, and Botium on the other end subscribes to those Redis channels before running a conversation.

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

• Botium CLI
• Botium Bindings
• Botium Box

Requirements

• Node.js and NPM
• a Whatsapp Business API Webhook
• a Redis instance (Cloud hosted free tier for example from redislabs will do as a starter)
• a project directory on your workstation to hold test cases and Botium configuration

Install Botium and Whatsapp Connector

When using Botium CLI:

> npm install -g botium-cli
> npm install -g botium-connector-whatsapp
> cd <your working dir>
> botium-cli init
> botium-cli run

When using Botium Bindings:

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

When using Botium Box:

Already integrated into Botium Box, no setup required

Connecting your Whatsapp Webhook to Botium

Open the file botium.json in your working directory and add the webhook url and Redis connection settings.

{
  "botium": {
    "Capabilities": {
      "PROJECTNAME": "<whatever>",
      "CONTAINERMODE": "whatsapp",
      "WHATSAPP_WEBHOOKURL": "...",
      "SIMPLEREST_INBOUND_REDISURL": "redis://127.0.0.1:6379"
    }
  }
}

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

Important: The inbound-proxy command has to be started with Botium CLI. Otherwise, Botium scripts will fail to receive any input or output messages from your chatbot!

Running the Samples

Install botium-core as peerDependency

> npm install --no-save botium-core

Afterwards in the folder samples/whatsapp-echo-bot is an example for a simple Whatsapp Webhook chatbot - it is connected to a I Am Botium chatbot endpoint doing some simple smalltalk. Start the webhook:

> cd samples/whatsapp-echo-bot && npm install && npm start

Finally, navigate into the samples/simple and run npm install, start the inbound proxy server and run the test itself with the following commands:

 > cd samples/simple
 > npm install
 > npm run inbound
 > npm test

Supported Capabilities

Set the capability CONTAINERMODE to whatsapp to activate this connector.

WHATSAPP_WEBHOOKURL

The URL of your Whatsapp Business API webhook.

WHATSAPP_RECIPIENTID

The Whatsapp Id of the user.

Optional. By default, a unique id is generated.

Open Issues and Restrictions

• Currently only plain text messages are supported
• Currently only individual receivers supported