Your Own Website - Rasa Documentation

If you already have an existing website and want to add a Rasa assistant to it, you can use the Rasa Chat Widget a widget which you can incorporate into your existing webpage by adding a HTML snippet. Alternatively, you can also build your own chat widget.

REST Channels

The RestInput and CallbackInput channels can be used for custom integrations. They provide a URL where you can post messages and either receive response messages directly, or asynchronously via a webhook.

RestInput

The REST channel will provide you with a REST endpoint where you can post user messages and receive the assistant’s messages in response. Add the REST channel to your credentials.yml:

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

Restart your Rasa server to make the REST channel available to receive messages. You can then send messages to http://<host>:<port>/webhooks/rest/webhook, replacing the host and port with the appropriate values from your running Rasa server.

Request and Response Format

After making the rest input channel available, you can POST messages to http://<host>:<port>/webhooks/rest/webhook, with the following format:

{
  "sender": "test_user", // sender ID of the user sending the message
  "message": "Hi there!"
}

The response from Rasa will be a JSON body of bot responses, for example:

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

Message Metadata

The REST channel supports sending additional metadata along with messages. This metadata can be accessed through the session_started_metadata slot and can contain any custom fields you want to pass to your assistant. To include metadata in your request, add a metadata field to your JSON payload:

{
  "sender": "test_user",
  "message": "Hi there!",
  "metadata": {
    "user_id": "12345",
    "source": "website",
    "page_url": "https://example.com/contact",
    "user_agent": "Mozilla/5.0...",
    "custom_field": "any_value"
  }
}

This metadata will be available in the session_started_metadata slot at the beginning of the conversation and can be accessed by your actions or flows. A custom action_session_start can be used to store this information to slots for later use in the conversation.

Cancel Background A2A Tasks

If your assistant uses external sub agents over A2A and an operation is running in the background, you can cancel it manually for a specific sender by calling: POST http://<host>:<port>/cancel_background_tasks/<sender_id> Example:

curl -X POST http://localhost:5005/cancel_background_tasks/test_user

This endpoint is useful for frontends or external systems that need to explicitly stop in-flight A2A polling or streaming for a conversation.

CallbackInput

New in Rasa Pro 3.17The Callback channel now supports message streaming. Learn more in the Streaming section.

The Callback channel behaves very much like the REST channel, 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. To use the callback channel, add the credentials to your credentials.yml:

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

Restart your Rasa server to make the new channel endpoint available to receive messages. You can then send messages to http://<host>:<port>/webhooks/callback/webhook, replacing the host and port with the appropriate values from your running Rasa server.

Request and Response Format

After making the callback input available, you can POST messages to http://<host>:<port>/webhooks/callback/webhook with the following format:

{
  "sender": "test_user", // sender ID of the user sending the message
  "message": "Hi there!"
}

If successful, the response will be success. Once Rasa is ready to send a message to the user, it will call the url specified in your credentials.yml with a separate POST request for each bot response:

{ "recipient_id": "test_user", "text": "Hey Rasa!" }

Multi-part responses (for example, a text message followed by an image) arrive as two separate POST requests to the callback URL.

Streaming

The callback channel supports streaming generative responses. To enable it, add stream=true as a query parameter when posting to the webhook:

POST http://<host>:<port>/webhooks/callback/webhook?stream=true

When streaming is active, Rasa calls the callback URL with a sequence of discrete events before delivering the final complete message. All events in the same streaming turn share a stream_id: stream_start — sent once at the beginning of a streamed response:

{
  "type": "stream_start",
  "stream_id": "<uuid>",
  "recipient_id": "test_user"
}

stream_delta — sent for each incremental text chunk, with a zero-based index:

{
  "type": "stream_delta",
  "stream_id": "<uuid>",
  "recipient_id": "test_user",
  "text": "Hello",
  "index": 0
}

stream_end — sent once when all chunks have been delivered:

{
  "type": "stream_end",
  "stream_id": "<uuid>",
  "recipient_id": "test_user"
}

After stream_end, Rasa posts the assembled complete message. This message includes the same stream_id so the client can correlate it with the preceding chunks, a streamed: true flag, and a stream_delta_count with the total number of chunks that were sent:

{
  "recipient_id": "test_user",
  "text": "Hello there",
  "stream_id": "<uuid>",
  "streamed": true,
  "stream_delta_count": 2
}

Any follow-up messages in the same turn that were not streamed (for example, a second response from a flow step) are posted as plain messages without streaming fields:

{ "recipient_id": "test_user", "text": "Is there anything else I can help with?" }

When streaming is disabled (no stream=true query parameter), the chunk events are suppressed and only the complete message is posted to the callback URL.

SocketIO Channel

The SocketIO channel uses websockets and is real-time. To use the SocketIO channel, add the credentials to your credentials.yml:

socketio:
  user_message_evt: user_uttered
  bot_message_evt: bot_uttered
  session_persistence: true/false

The first two configuration values define the event names used by Rasa when sending or receiving messages over socket.io. The socket client can pass an object named metadata to supply metadata to the channel. You can configure an alternative key using the metadata_key setting. For example, if your client wants to pass metadata on a key named customData, the setting would be:

socketio:
  metadata_key: customData

Restart your Rasa server to make the new channel endpoint available to receive messages. You can then send messages to http://<host>:<port>/socket.io, replacing the host and port with the appropriate values from your running Rasa server. The Socket.IO transport path defaults to /socket.io and can be overridden with socketio_path:

socketio:
  socketio_path: /my.socket.io

Running socketio alongside the inspector channelYou can declare both socketio: and inspector: in the same credentials.yml. Each channel needs its own Socket.IO transport path. Rasa keeps the socketio channel on /socket.io and puts the inspector channel on /inspector.io. If you give two Socket.IO channels the same socketio_path, Rasa fails to start with a RasaException that names both channels. Set a distinct socketio_path on all but one of them to resolve it.

session persistenceBy default, the SocketIO channel uses the socket id as sender_id, which causes the session to restart at every page reload. session_persistence can be set to true to avoid that. In that case, the frontend is responsible for generating a session id and sending it to the Rasa server by emitting the event session_request with {session_id: [session_id]} immediately after the connect event.The example Webchat implements this session creation mechanism (version >= 0.5.0).

SocketIO client / server compatibilityThe version of the SocketIO client connecting to Rasa must be compatible with the versions of the python-socketio and python-engineio packages used by Rasa. Please refer to the pyproject.toml file relative to your version of Rasa and the official python-socketio compatibility table.

JWT Authentication

The SocketIO channel can be optionally configured to perform JWT authentication on connect by defining the jwt_key and optional jwt_method in the credentials.yml file.

socketio:
  user_message_evt: user_uttered
  bot_message_evt: bot_uttered
  session_persistence: true
  jwt_key: my_public_key
  jwt_method: HS256

When initially requesting the connection, the client should pass in an encoded payload as a JSON object under the key token:

{
  "token": "jwt_encoded_payload"
}

Once you’ve set up your SocketIO channel, you can use the official Rasa Chat Widget on any webpage. Use the example HTML below and paste the URL of your Rasa instance into the server-url attribute:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>HTML Example</title>
    <script
      type="module"
      src="https://unpkg.com/@rasahq/chat-widget-ui/dist/rasa-chatwidget/rasa-chatwidget.esm.js"
    ></script>
    <link
      rel="stylesheet"
      href="https://unpkg.com/@rasahq/chat-widget-ui/dist/rasa-chatwidget/rasa-chatwidget.css"
    />
  </head>
  <body>
    <rasa-chatbot-widget server-url="https://example.com"></rasa-chatbot-widget>
  </body>
</html>

For more information, including how to fully customize the widget for your website, you can check out the full documentation. Alternatively, if you want to embed the widget in a React app, there is a library in the NPM package repository.

Deprecated Chat WidgetFor information on the deprecated chat widget, rasa-chat, documentation can be found here.

​REST Channels

​RestInput

​Request and Response Format

​Message Metadata

​Cancel Background A2A Tasks

​CallbackInput

​Request and Response Format

​Streaming

​SocketIO Channel

​JWT Authentication

​Chat Widget

REST Channels

RestInput

Request and Response Format

Message Metadata

Cancel Background A2A Tasks

CallbackInput

Request and Response Format

Streaming

SocketIO Channel

JWT Authentication

Chat Widget