How Integrate Twilio with Botpress Step-by-Step

Hello everyone!!

For a few days I’ve been researching how to integrate Botpress with Twilio to use with Whatsapp, but I haven’t found any effective guidance in the official Botpress documentation (which isn’t good) either here on the forum or even on google or youtube.

But as I solved my problem, regarding Botpress setup with Twilio and Whatsapp, I decided to write a step-by-step tutorial on how to make it work.

Integration Tutorial

This tutorial aims to demonstrate how the botpress framework is integrated with Whatsapp through the Twilio platform.

Note: For ease I will describe the step-by-step for Windows environment, since it is the environment, I am currently using .


To use Twilio as integration of your botpress with Whatsapp it is necessary that your bot has external access via SSL /TLS [ https ]

  • If your bot is being built in a local environment(localhost) you will need to use a tunnel application such as NGROK so that you can access your localhost externally.
    • Follow the steps below:
      • Download NGROK in ngrok - download
      • Unzip the file and rotate the executable
      • In the /ngrok/bin folder run the ngrok file.exe
      • The command prompt [cmd] will open
      • In it run the following command: ngrok http 3000, where ngrok is the executable command of the application, http indicates that it will be accessed via web and 3000 is the default port of botpress

If you are developing your bot in cloud environment, such as Heroku for example, just use the external url of your bot which should look something like this: https://<yourbotname>


Now let’s go to the Twilio!!

  1. Create an account on Twilio (I will not describe here how to create an account in Twilio because it is very simple and intuitive to create an account).

  2. When you create the account, in your account dashboard, copy and reserve the keys: accountSID and authToken.

Register your phone number in your account, as Twilio will need to.

Once that’s done, now it’s time to set up your Twilio access credentials in Botpress.

In Botpress you perform the following steps:

  1. Open the \data\bots<your_bot>\bot.config.json file
  2. Include, before the last “}”, the json code block as below:
    "messaging": {
	          "channels": {
	                     "twilio": {
		                  "enabled": false, "change here to true"
		                  "accountSID": "Enter your key accountSID here",
		                  "authToken": "Enter your key authToken here"

It should look like this:

  1. Go to \data\global\ folder and open the file botpress.config.json

  2. With the file open, change the parameter externalUrl as follows:

    "externalUrl": "",
    "session": {
       "enabled": true, “If false change to true”
       "maxAge": "1h"

It should look like this:

  1. Now, in the \data\global\config folder, open the channel-twilio.json file and configure it as follows:
      "$schema": "bp://types/modules/channel-twilio/config.schema.json",
      "enabled": true,
      "accountSID": " Enter your key accountSID here",
      "authToken": " Enter your key authToken here"

It should look like this:

  1. Now copy the channel-twilio.json file from the \data\global\config folder and paste it into the \data\bots\ folder <your_bot>\config

  1. Done that it’s time to restart your Botpress. Then restart your Botpress and see in the initiation log the URL of the Twilio webhook. You must present as:

  1. Now copy the Twilio webhook url, go to your Twilio account, and paste it into the webhook section, as shown in the image below:

  1. Now, still in twilio’s account, go to menu Messanging → Try it out → Send a Whatsapp message

  2. You will need to activate Twilio Whatsapp, so open whatsapp as follows:

  1. This “join lot-idea” code activates Twilio to interact with your botpress.

  2. If you want to disable the Twilio service just send a message with the text “stop”.

  3. And that’s it! Your botpress is prepared to send and receive message by whatsapp. See the interaction of messages, as well as the log:

I put the pdf tutorial on the drive for anyone who wants to download it. Follow the link:

I hope this contribution helps those in need.



Nice write up. I agree the docs can use real world use case examples like this. As it is now, it feels like bot press is a powerful platform, but due to limited docs, lots of trial and error to figure thinks out….I myself got real into it then stepped back.

Hopefully the team takes inspiration from user submitted content like this and adds to the tutorial section of the docs. Thanks for sharing.


Thanks @chris!

I really felt it was necessary to write this tutorial because I had a lot of difficulty setting up following the official guide.



Impressive content great work! Can I move the category of your post to howTo ?


Hi @Daehli

Sure! it will be an honour.

I was in doubt when posting whether I would put it in the how to category or in the community.

Feel free to change the category.


@danilorslima Hi Sir,

I have integrated my bot with whatsapp but when I’ll upload file its not going to save on aws s3 bucket. I need your help.