Warning: This document is for an old version of Rasa Core. The latest version is 0.14.5.

Chat & Voice platforms

Here’s how to connect your conversational AI to the outside world.

See here for details on how to build a custom input channel.

Input channels are defined in the rasa_core.channels module. Currently, there is code for connecting to facebook, slack, telegram, mattermost and twilio. If the connection you want is missing, this is a great place to start contributing!

If you’re testing on your local machine (e.g. not a server), you will need to use ngrok. This gives your machine a domain name and so that facebook, slack, etc. know where to send messages.

Managing Credentials

To connect to most channels, you will need to add some credentials (e.g. an API token). Rasa Core will read these properties from a credentials file in yaml format, here is an example containing most channels:

twillio:
  account_sid: "ACbc2dxxxxxxxxxxxx19d54bdcd6e41186"
  auth_token: "e231c197493a7122d475b4xxxxxxxxxx"
  twilio_number: "+440123456789"

slack:
  slack_token: "xoxb-286425452756-safjasdf7sl38KLls"
  slack_channel: "@my_channel"
  
telegram:
  access_token: "490161424:AAGlRxinBRtKGb21_rlOEMtDFZMXBl6EC0o"
  verify: "your_bot"
  webhook_url: "your_url.com/webhook"

mattermost:
  url: "https://chat.example.com/api/v4"
  team: "community"
  user: "user@user.com"
  pw: "password"

facebook:
  verify: "rasa-bot"
  secret: "3e34709d01ea89032asdebfe5a74518"
  page-access-token: "EAAbHPa7H9rEBAAuFk4Q3gPKbDedQnx4djJJ1JmQ7CAqO4iJKrQcNT0wtD"

Note

You only need to include the channels you want to connect to in your credentials.yml.

Facebook Setup

You first need to retrieve some credentials to connect to the Facebook Messenger. Once you have them you can either attach the input channel running the provided rasa_core.run script, or you can attach it in your own code.

Getting Credentials

How to get the FB credentials: You need to set up a Facebook app and a page.

  1. To create the app go to: https://developers.facebook.com/ and click on “Add a new app”.
  2. go onto the dashboard for the app and under Products, click Add Product and add Messenger. Under the settings for Messenger, scroll down to Token Generation and click on the link to create a new page for your app.
  3. Use the collected verify, secret and access token to connect your bot to facebook.

For more detailed steps, visit the messenger docs.

Using the run script

If you want to connect to facebook using the run script, e.g. using:

python -m rasa_core.run -d models/dialogue -u models/nlu/current \
    --port 5002 --credentials credentials.yml

you need to supply a credentials.yml with the following content:

facebook:
  verify: "rasa-bot"
  secret: "3e34709d01ea89032asdebfe5a74518"
  page-access-token: "EAAbHPa7H9rEBAAuFk4Q3gPKbDedQnx4djJJ1JmQ7CAqO4iJKrQcNT0wtD"

The endpoint for receiving facebook messenger messages is http://localhost:5005/webhooks/facebook/webhook, replacing the host and port with the appropriate values. This is the URL you should add in the configuration of the webhook.

Directly using python

A FacebookInput instance provides a flask blueprint for creating a webserver. This lets you separate the exact endpoints and implementation from your webserver creation logic.

Code to create a Messenger-compatible webserver looks like this:

    from rasa_core.channels.facebook import FacebookInput
    from rasa_core.agent import Agent
    from rasa_core.interpreter import RegexInterpreter

    # load your trained agent
    agent = Agent.load(MODEL_PATH, interpreter=RegexInterpreter())

    input_channel = FacebookInput(
            fb_verify="YOUR_FB_VERIFY",
            # you need tell facebook this token, to confirm your URL
            fb_secret="YOUR_FB_SECRET",  # your app secret
            fb_access_token="YOUR_FB_PAGE_ACCESS_TOKEN"
            # token for the page you subscribed to
    )

    # set serve_forever=False if you want to keep the server running
    s = agent.handle_channels([input_channel], 5004, serve_forever=False)

Slack Setup

You first need to retrieve some credentials, once you have them you can either attach the input channel running the provided rasa_core.run script, or you can attach it in your own code.

Getting Credentials

How to get the Slack credentials: You need to set up a Slack app.

  1. To create the app go to: https://api.slack.com/apps and click on “Create New App”.
  2. Activate the following features: interactive components, event subscriptions, bot users, permissions (for basic functionality you should subscribe to the message.channel, message.groups, message.im and message.mpim events)
  3. The slack_channel is the target your bot posts to. This can be a channel, an app or an individual person
  4. Use the entry for Bot User OAuth Access Token in the “OAuth & Permissions” tab as your slack_token

For more detailed steps, visit the slack api docs.

Using run script

If you want to connect to the slack input channel using the run script, e.g. using:

python -m rasa_core.run -d models/dialogue -u models/nlu/current \
    --port 5002 --credentials credentials.yml

you need to supply a credentials.yml with the following content:

slack:
  slack_token: "xoxb-286425452756-safjasdf7sl38KLls"
  slack_channel: "@my_channel"

The endpoint for receiving facebook messenger messages is http://localhost:5005/webhooks/slack/webhook, replacing the host and port with the appropriate values. This is the URL you should add in the OAuth & Permissions section.

Note

If you do not set the slack_channel keyword argument, messages will by delivered back to the user who sent them.

Directly using python

A SlackInput instance provides a flask blueprint for creating a webserver. This lets you separate the exact endpoints and implementation from your webserver creation logic.

Code to create a Messenger-compatible webserver looks like this:

    from rasa_core.channels.slack import SlackInput
    from rasa_core.agent import Agent
    from rasa_core.interpreter import RegexInterpreter

    # load your trained agent
    agent = Agent.load(MODEL_PATH, interpreter=RegexInterpreter())

    input_channel = SlackInput(
            slack_token="YOUR_SLACK_TOKEN",
            # this is the `bot_user_o_auth_access_token`
            slack_channel="YOUR_SLACK_CHANNEL"
            # the name of your channel to which the bot posts (optional)
    )

    # set serve_forever=False if you want to keep the server running
    s = agent.handle_channels([input_channel], 5004, serve_forever=False)

Mattermost Setup

You first need to retrieve some credentials, once you have them you can either attach the input channel running the provided rasa_core.run script, or you can attach it in your own code.

Getting Credentials

How to setup the outgoing webhook:

  1. To create the mattermost outgoing webhook login to your mattermost team site and go to Main Menu > Integrations > Outgoing Webhooks
  2. Click Add outgoing webhook
  3. Fill out the details including the channel you want the bot in. You will need to ensure the trigger words section is setup with @yourbotname so that way it doesn’t trigger on everything that is said.
  4. Make sure trigger when section is set to value first word matches a trigger word exactly
  5. For the callback url this needs to be your ngrok url where you have your webhook running in core or your public address, e.g. http://test.example.com/webhooks/mattermost/webhook

For more detailed steps, visit the mattermost docs at.

Using run script

If you want to connect to the mattermost input channel using the run script, e.g. using:

python -m rasa_core.run -d models/dialogue -u models/nlu/current \
    --port 5002 --credentials credentials.yml

you need to supply a credentials.yml with the following content:

mattermost:
  url: "https://chat.example.com/api/v4"
  team: "community"
  user: "user@user.com"
  pw: "password"

Directly using python

A MattermostInput instance provides a flask blueprint for creating a webserver. This lets you separate the exact endpoints and implementation from your webserver creation logic.

Code to create a Mattermost-compatible webserver looks like this:

    from rasa_core.channels.mattermost import MattermostInput
    from rasa_core.agent import Agent
    from rasa_core.interpreter import RegexInterpreter

    # load your trained agent
    agent = Agent.load(MODEL_PATH, interpreter=RegexInterpreter())

    input_channel = MattermostInput(
            # this is the url of the api for your mattermost instance
            url="http://chat.example.com/api/v4",
            # the name of your team for mattermost
            team="community",
            # the username of your bot user that will post
            user="user@email.com",
            # messages
            pw="password"
            # the password of your bot user that will post messages
    )

    # set serve_forever=False if you want to keep the server running
    s = agent.handle_channels([input_channel], 5004, serve_forever=False)

The arguments for the handle_channels are the input channels and the port. The endpoint for receiving mattermost channel messages is /webhooks/mattermost/webhook. This is the url you should add in the mattermost outgoing webhook.

Telegram Setup

You first need to retrieve some credentials, once you have them you can either attach the input channel running the provided rasa_core.run script, or you can attach it in your own code.

Getting Credentials

How to get the Telegram credentials: You need to set up a Telegram bot.

  1. To create the bot, go to: https://web.telegram.org/#/im?p=@BotFather, enter /newbot and follow the instructions.
  2. At the end you should get your access_token and the username you set will be your verify.
  3. If you want to use your bot in a group setting, it’s advisable to turn on group privacy mode by entering /setprivacy. Then the bot will only listen when the message is started with /bot

For more information on the Telegram HTTP API, go to https://core.telegram.org/bots/api

Using run script

If you want to connect to telegram using the run script, e.g. using:

python -m rasa_core.run -d models/dialogue -u models/nlu/current
    --port 5002 --credentials credentials.yml

you need to supply a credentials.yml with the following content:

telegram:
  access_token: "490161424:AAGlRxinBRtKGb21_rlOEMtDFZMXBl6EC0o"
  verify: "your_bot"
  webhook_url: "your_url.com/webhooks/telegram/webhook"

Directly using python

A TelegramInput instance provides a flask blueprint for creating a webserver. This lets you separate the exact endpoints and implementation from your webserver creation logic.

Code to create a Messenger-compatible webserver looks like this:

    # telegram channel will try to set a webhook, so we need to mock the api

    httpretty.register_uri(
            httpretty.POST,
            'https://api.telegram.org/bot123:YOUR_ACCESS_TOKEN/setWebhook',
            body='{"ok": true, "result": {}}')

    httpretty.enable()

    from rasa_core.channels.telegram import TelegramInput
    from rasa_core.agent import Agent
    from rasa_core.interpreter import RegexInterpreter

    # load your trained agent
    agent = Agent.load(MODEL_PATH, interpreter=RegexInterpreter())

    input_channel = TelegramInput(
            # you get this when setting up a bot
            access_token="123:YOUR_ACCESS_TOKEN",
            # this is your bots username
            verify="YOUR_TELEGRAM_BOT",
            # the url your bot should listen for messages
            webhook_url="YOUR_WEBHOOK_URL"
    )

    # set serve_forever=False if you want to keep the server running
    s = agent.handle_channels([input_channel], 5004, serve_forever=False)

The arguments for the handle_channels are the input channels and the port. The endpoint for receiving telegram channel messages is /webhooks/telegram/webhook. This is the URL you should use as the webhook_url. To get the bot to listen for messages at that URL, go to myurl.com/webhooks/telegram/set_webhook first to set the webhook.

Twilio Setup

You first need to retrieve some credentials, once you have them you can either attach the input channel running the provided rasa_core.run script, or you can attach it in your own code.

Getting Credentials

How to get the Twilio credentials: You need to set up a Twilio account.

  1. Once you have created a Twilio account, you need to create a new project. The basic important product to select here is Programmable SMS.
  2. Once you have created the project, navigate to the Dashboard of Programmable SMS and click on Get Started and follow the steps to connect a phone number to the project.
  3. Now you can use the Account SID, Auth Token and the phone number you purchased in your credentials yml.

For more information on the Twilio REST API, go to https://www.twilio.com/docs/iam/api

Using run script

If you want to connect to the twilio input channel using the run script, e.g. using:

python -m rasa_core.run -d models/dialogue -u models/nlu/current
    --port 5002 --credentials credentials.yml

you need to supply a credentials.yml with the following content:

twillio:
  account_sid: "ACbc2dxxxxxxxxxxxx19d54bdcd6e41186"
  auth_token: "e231c197493a7122d475b4xxxxxxxxxx"
  twilio_number: "+440123456789"

Directly using python

A TwilioInput instance provides a flask blueprint for creating a webserver. This lets you separate the exact endpoints and implementation from your webserver creation logic.

Code to create a Twilio-compatible webserver looks like this:

    from rasa_core.channels.twilio import TwilioInput
    from rasa_core.agent import Agent
    from rasa_core.interpreter import RegexInterpreter

    # load your trained agent
    agent = Agent.load(MODEL_PATH, interpreter=RegexInterpreter())

    input_channel = TwilioInput(
            # you get this from your twilio account
            account_sid="YOUR_ACCOUNT_SID",
            # also from your twilio account
            auth_token="YOUR_AUTH_TOKEN",
            # a number associated with your twilio account
            twilio_number="YOUR_TWILIO_NUMBER"
    )

    # set serve_forever=False if you want to keep the server running
    s = agent.handle_channels([input_channel], 5004, serve_forever=False)

The arguments for the handle_channels are the input channels and the port. The endpoint for receiving twilio channel messages is /webhooks/twilio/webhook.

RocketChat Setup

Getting Credentials

How to set up Rocket.Chat:

  1. Create a user that will be used to post messages and set its credentials at credentials file.
  2. Create a Rocket.Chat outgoing webhook by logging as admin to Rocket.Chat and going to Administration > Integrations > New Integration.
  3. Select Outgoing Webhook.
  4. Set Event Trigger section to value Message Sent.
  5. Fill out the details including the channel you want the bot listen to. Optionally, it is possible to set the Trigger Words section with @yourbotname so that way it doesn’t trigger on everything that is said.
  6. Set your URLs section to the Rasa URL where you have your webhook running, in Core or your public address with /webhooks/rocketchat/webhook, e.g.: http://test.example.com/webhooks/rocketchat/webhook.

For more information on the Rocket.Chat Webhooks, go to https://rocket.chat/docs/administrator-guides/integrations/

Using run script

If you want to connect to the rocketchat input channel using the run script, e.g. using:

python -m rasa_core.run -d models/dialogue -u models/nlu/current
    --port 5002 --credentials credentials.yml

you need to supply a credentials.yml with the following content:

rocketchat:
  user: "yourbotname"
  password: "YOUR_PASSWORD"
  server_url: "https://demo.rocket.chat"

Directly using python

A RocketChatInput instance provides a flask blueprint for creating a webserver. This lets you separate the exact endpoints and implementation from your webserver creation logic.

Code to create a RocketChat-compatible webserver looks like this:

    from rasa_core.channels.rocketchat import RocketChatInput
    from rasa_core.agent import Agent
    from rasa_core.interpreter import RegexInterpreter

    # load your trained agent
    agent = Agent.load(MODEL_PATH, interpreter=RegexInterpreter())

    input_channel = RocketChatInput(
            # your bots rocket chat user name
            user="yourbotname",
            # the password for your rocket chat bots account
            password="YOUR_PASSWORD",
            # url where your rocket chat instance is running
            server_url="https://demo.rocket.chat"
    )

    # set serve_forever=False if you want to keep the server running
    s = agent.handle_channels([input_channel], 5004, serve_forever=False)

The arguments for the handle_channels are the input channels and the port. The endpoint for receiving mattermost channel messages is /webhooks/rocketchat/webhook. This is the url you should add in the RocketChat outgoing webhook.

Microsoft Bot Framework Setup

Using run script

If you want to connect to the botframework input channel using the run script, e.g. using:

python -m rasa_core.run -d models/dialogue -u models/nlu/current \
    --port 5002 --credentials credentials.yml

you need to supply a credentials.yml with the following content:

botframework:
  app_id: "MICROSOFT_APP_ID"
  app_password: "MICROSOFT_APP_PASSWORD"

Directly using python

A BotFrameworkInput instance provides a flask blueprint for creating a webserver. This lets you seperate the exact endpoints and implementation from your webserver creation logic.

Code to create a Microsoft Bot Framework-compatible webserver looks like this:

    from rasa_core.channels.botframework import BotFrameworkInput
    from rasa_core.agent import Agent
    from rasa_core.interpreter import RegexInterpreter

    # load your trained agent
    agent = Agent.load(MODEL_PATH, interpreter=RegexInterpreter())

    input_channel = BotFrameworkInput(
            # you get this from your Bot Framework account
            app_id="MICROSOFT_APP_ID",
            # also from your Bot Framework account
            app_password="MICROSOFT_APP_PASSWORD"
    )

    # set serve_forever=False if you want to keep the server running
    s = agent.handle_channels([input_channel], 5004, serve_forever=False)

The arguments for the handle_channels are the input channels and the port. The endpoint for receiving botframework channel messages is /webhooks/botframework/webhook. This is the url you should add in your microsoft bot service configuration.

SocketIO Setup

You can either attach the input channel running the provided rasa_core.run script, or you can attach the channel in your own code.

Using run script

If you want to connect the socketio input channel using the run script, e.g. using:

python -m rasa_core.run -d models/dialogue -u models/nlu/current
    --port 5002 --credentials credentials.yml

you need to supply a credentials.yml with the following content:

socketio:
  user_message_evt: user_uttered
  bot_message_evt: bot_uttered

These two configuration values define the event names used by Rasa Core when sending or receiving messages over socket.io.

Directly using python

Code to create a Socket.IO-compatible webserver looks like this:

    from rasa_core.channels.socketio import SocketIOInput
    from rasa_core.agent import Agent
    from rasa_core.interpreter import RegexInterpreter

    # load your trained agent
    agent = Agent.load(MODEL_PATH, interpreter=RegexInterpreter())

    input_channel = SocketIOInput(
            # event name for messages sent from the user
            user_message_evt="user_uttered",
            # event name for messages sent from the bot
            bot_message_evt="bot_uttered",
            # socket.io namespace to use for the messages
            namespace=None
    )

    # set serve_forever=False if you want to keep the server running
    s = agent.handle_channels([input_channel], 5004, serve_forever=False)

The arguments for the handle_channels are the input channels and the port. Once started, you should be able to connect to http://localhost:5005 with your socket.io client.

Using Ngrok For Local Testing

You can use https://ngrok.com/ to create a local webhook from your machine that is Publicly available on the internet so you can use it with applications like Slack, Facebook, etc.

The command to run a ngrok instance for port 5002 for example would be:

ngrok httpd 5002

Ngrok is only needed if you don’t have a public IP and are testing locally

ngrok will create a https address for your computer, for example https://xxxxxx.ngrok.io . For a facebook bot, your webhook address would then be https://xxxxxx.ngrok.io/webhooks/facebook/webhook, for telegram https://xxxxxx.ngrok.io/webhooks/telegram/webhook, etc.

REST Channels

If you want to put a widget on your website so that people can talk to your bot, check out these two projects:

For these use cases it is easiest to use either the RestInput or the CallbackInput channels. They will provide you with a URL to post the messages to.

RestInput

The rest channel, will provide you with a REST endpoint to post messages to and in response to that request will send back the bots messages. Here is an example on how to connect the rest input channel using the run script:

python -m rasa_core.run -d models/dialogue -u models/nlu/current \
    --port 5002 --credentials credentials.yml

you need to supply a credentials.yml with the following content:

rest:
  # you don't need to provide anything here - this channel doesn't
  # require any credentials

After connecting the rest input channel, you can post messages to POST /webhooks/rest/webhook with the following format:

{
  "sender": "Rasa",
  "text": "Hi there!"
}

The response to this request will include the bot responses, e.g.

[
  {"text": "Hey Rasa!"}, {"image": "http://example.com/image.jpg"}
]

CallbackInput

The callback channel behaves very much like the rest input, but instead of directly returning the bot messages to the HTTP request that sends the message, it will call a URL you can specify to send bot messages.

Here is an example on how to connect the callback input channel using the run script:

python -m rasa_core.run -d models/dialogue -u models/nlu/current \
    --port 5002 --credentials credentials.yml

you need to supply a credentials.yml with the following content:

callback:
  # URL to which Core will send the bot responses
  url: "http://localhost:5034/bot"

After connecting the callback input channel, you can post messages to POST /webhooks/callback/webhook with the following format:

{
  "sender": "Rasa",
  "text": "Hi there!"
}

The response will simply be success. Once Core wants to send a message to the user, it will call the URL you specified with a POST and the following JSON body:

[
  {"text": "Hey Rasa!"}, {"image": "http://example.com/image.jpg"}
]

Creating a new Channel

You can also implement your own, custom channel. You can use the rasa_core.channels.channel.RestInput class as a template. The methods you need to implement are blueprint and name. The method needs to create a Flask blueprint that can be attached to a flask server.

This allows you to add REST endpoints to the server, the external messaging service can call to deliver messages.

Your blueprint should have at least the two routes health on / and receive on the http route /webhook.

The name method defines the url prefix. E.g. if your component is named myio the webhook you can use to attach the external service is: http://localhost:5005/webhooks/myio/webhook (replacing the hostname and port with your values).

To send a message, you would run a command like:

curl -XPOST http://localhost:5000/webhooks/myio/webhook \
  -d '{"sender": "user1", "message": "hello"}' \
  -H "Content-type: application/json"

where myio is the name of your component.

In your implementation of the receive endpoint, you need to make sure to call on_new_message(UserMessage(text, output, sender_id)). This will tell Rasa Core to handle this user message. The output is an output channel implementing the OutputChannel class. You can either implement the methods for your particular chat channel (e.g. there are methods to send text and images) or you can use the CollectingOutputChannel to collect the bot responses Core creates while the bot is processing your messages and return them as part of your endpoint response. This is the way the RestInput is implemented. For examples on how to create and use your own output channel, please take a look at the implementations of the other output channels, e.g. the SlackBot in rasa_core.channels.slack.

To use a custom channel, you can use the rasa_core.run script, passing in the classpath of your custom channel using --channel mypackage.MyIO or you can write your own code hooking up the agent with the channel.

Example implementation for an input channel that receives the messages, hands them over to Rasa Core, collects the bot utterances and returns these bot utterances as the json response to the webhook call that posted this message to the channel:

class RestInput(InputChannel):
    """A custom http input channel.

    This implementation is the basis for a custom implementation of a chat
    frontend. You can customize this to send messages to Rasa Core and
    retrieve responses from the agent."""

    @classmethod
    def name(cls):
        return "rest"

    @staticmethod
    def on_message_wrapper(on_new_message, text, queue, sender_id):
        collector = QueueOutputChannel(queue)

        message = UserMessage(text, collector, sender_id,
                              input_channel=RestInput.name())
        on_new_message(message)

        queue.put("DONE")

    def _extract_sender(self, req):
        return req.json.get("sender", None)

    # noinspection PyMethodMayBeStatic
    def _extract_message(self, req):
        return req.json.get("message", None)

    def stream_response(self, on_new_message, text, sender_id):
        from multiprocessing import Queue

        q = Queue()

        t = Thread(target=self.on_message_wrapper,
                   args=(on_new_message, text, q, sender_id))
        t.start()
        while True:
            response = q.get()
            if response == "DONE":
                break
            else:
                yield json.dumps(response) + "\n"

    def blueprint(self, on_new_message):
        custom_webhook = Blueprint(
                'custom_webhook_{}'.format(type(self).__name__),
                inspect.getmodule(self).__name__)

        @custom_webhook.route("/", methods=['GET'])
        def health():
            return jsonify({"status": "ok"})

        @custom_webhook.route("/webhook", methods=['POST'])
        def receive():
            sender_id = self._extract_sender(request)
            text = self._extract_message(request)
            should_use_stream = utils.bool_arg("stream", default=False)

            if should_use_stream:
                return Response(
                        self.stream_response(on_new_message, text, sender_id),
                        content_type='text/event-stream')
            else:
                collector = CollectingOutputChannel()
                on_new_message(UserMessage(text, collector, sender_id,
                                           input_channel=self.name()))
                return jsonify(collector.messages)

        return custom_webhook

Have questions or feedback?

We have a very active support community on Rasa Community Forum that is happy to help you with your questions. If you have any feedback for us or a specific suggestion for improving the docs, feel free to share it by creating an issue on Rasa Core GitHub repository.