> ## Documentation Index
> Fetch the complete documentation index at: https://rasa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Your Own Website

> Deploy and Run a Rasa Chat Bot on a Website

If you already have an existing website and want to add a Rasa assistant to it,
you can use the [Rasa Chat Widget](/docs/reference/channels/your-own-website#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:

```yaml theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
[{ "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:

```json theme={null}
{
  "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`](https://rasa.com/docs/rasa-pro/nlu-based-assistants/default-actions#customization) 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:

```bash theme={null}
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

<Info>
  **New in Rasa Pro 3.17**

  The Callback channel now supports message streaming. Learn more in the [Streaming](/docs/reference/channels/your-own-website#streaming) section.
</Info>

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`:

```yaml theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{ "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:

```json theme={null}
{
  "type": "stream_start",
  "stream_id": "<uuid>",
  "recipient_id": "test_user"
}
```

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

```json theme={null}
{
  "type": "stream_delta",
  "stream_id": "<uuid>",
  "recipient_id": "test_user",
  "text": "Hello",
  "index": 0
}
```

**`stream_end`** — sent once when all chunks have been delivered:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{ "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`:

```yaml theme={null}
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:

```yaml theme={null}
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`:

```yaml theme={null}
socketio:
  socketio_path: /my.socket.io
```

<Note>
  **Running `socketio` alongside the `inspector` channel**

  You 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](/docs/pro/testing/trying-assistant#inspecting-conversations-over-external-channels) 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.
</Note>

<Note>
  **session persistence**

  By 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](https://github.com/botfront/rasa-webchat)
  implements this session creation mechanism (version >= 0.5.0).
</Note>

<Note>
  **SocketIO client / server compatibility**

  The version of the SocketIO client connecting to Rasa must be compatible with the versions of
  the [python-socketio](https://github.com/miguelgrinberg/python-socketio) and
  [python-engineio](https://github.com/miguelgrinberg/python-engineio) packages used by
  Rasa. Please refer to the
  [`pyproject.toml`](https://github.com/RasaHQ/rasa/blob/main/pyproject.toml)
  file relative to your version of Rasa and the official `python-socketio` compatibility table.
</Note>

### 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.

```yaml theme={null}
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`:

```json theme={null}
{
  "token": "jwt_encoded_payload"
}
```

### Chat Widget

Once you've set up your SocketIO channel, you can use the [official Rasa Chat Widget](https://github.com/RasaHQ/chat-widget) on any webpage.
Use the example HTML below and paste the URL of your Rasa instance into
the `server-url` attribute:

```html theme={null}
<!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](https://chatwidget.rasa.com/).

Alternatively, if you want to embed the widget in a React app, there is
[a library in the NPM package repository](https://www.npmjs.com/package/@rasahq/chat-widget-react).

<Note>
  **Deprecated Chat Widget**

  For information on the deprecated chat widget, [rasa-chat](https://www.npmjs.com/package/@rasahq/rasa-chat), documentation can be found [here](https://chat-widget-docs.rasa.com).
</Note>


## Related topics

- [Set Up Your Agent on GCP](/docs/learn/deployment/gcp/gcp-playbook-setup-agent.md)
- [Set Up Your Agent on Azure](/docs/learn/deployment/azure/azure-playbook-setup-agent.md)
- [Set Up Your Agent on AWS](/docs/learn/deployment/aws/aws-playbook-setup-agent.md)
- [Connecting to Messaging and Voice Channels](/docs/reference/channels/messaging-and-voice-channels.md)
- [Custom Connectors](/docs/reference/channels/custom-connectors.md)