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

# Add chat to an endpoint and your website

> Turn on Chat for an endpoint, put Raily Chat on your website, and call the chat API from your app.

Chat answers questions in plain language from the sources an endpoint already serves. Every answer cites the results it used, with links back to them. It runs on the same search as the endpoint, so a change to the endpoint's sources or search settings shows up in chat too.

You can use Chat in two ways:

* **Raily Chat on your website.** Add a short script to your site and visitors get a chat button that opens a branded chat panel.
* **The chat API.** Your app sends a conversation to the endpoint with an API key and gets back an answer with its sources.

Agents in Claude or ChatGPT are not affected. They keep seeing search only.

> [!NOTE]
>
> Chat is available on request. [Contact us](https://www.raily.ai/contact) to turn it on for your Account. Turning Chat on for an endpoint is available on paid plans.

## Turn on Chat for an endpoint

**1. Open the endpoint**

In the Rail, open the endpoint you want to chat with. Chat needs an endpoint with a search source.

**2. Turn on Chat**

In the card with **Search results with UI**, turn on **Chat**.

You can also turn it on when you create an endpoint: the **New endpoint** form has the same **Chat** switch.

**3. Save**

Click **Save Changes**.

**4. Try it**

Click **Preview** next to the **Chat** switch. A preview of Raily Chat opens, answering from this endpoint. Click **Hide preview** to close it.

The endpoint now answers the chat API. To show chat on your website, add the website next.

If your plan doesn't include Chat, the switch is turned off and the form shows **Upgrade your plan** to turn Chat on. Turning Chat off always works, on any plan.

## Put Raily Chat on your website

Raily Chat only loads on the websites you list. A site that isn't on the list can't show it, even with your script.

**1. Turn on and save Chat**

Follow the steps above. The **Websites** list appears under the **Chat** switch. You can add websites once Chat is saved.

**2. Add your website**

In **Website address**, type the address of your site, such as `https://your-site.com`, and click **Add website**.

Add each address your visitors use. `https://example.com` and `https://www.example.com` are different websites, so add both if both serve your pages. You can add up to 20 websites.

**3. Copy the snippet**

Under **Paste it into your website's HTML**, click the copy button next to the script. It looks like this:

```html theme={null}
<script src="https://app.raily.ai/public-chat/loader.js" data-integration-id="..." defer></script>
```

**4. Add the snippet to your site**

Paste it once, before the closing `</body>` tag on every page where you want chat. You don't need to change it when you add or remove websites later.

When it works, the **Chat** row shows a **Live on 1 website** badge (or the number of websites), and a chat button appears on your site.

On a trial plan you can see the website list but can't change it.

## Customize the chat

Open **Customize the chat** under the website list to match Raily Chat to your brand. Click **Preview** next to the **Chat** switch to see your changes before you save. The preview follows the language you're editing.

The settings have three tabs.

### Button

* **Style**: **Round**, **Button with label** (an icon with optional text), or **Your own SVG** (a complete SVG of your own).
* **Icon**, **Show label** and **Label** for the button, plus **Button background** and **Icon colour**.
* **Side** (**Left** or **Right**), **Location** (**Bottom** or **Center**), **Distance from side** and **Distance from bottom**.
* Size and shape: **Height**, **Width**, **Rotation** and **Corner radius**, depending on the style.
* **Chat opens**: **Above button**, **Beside button**, or **From bottom**. On smaller screens the chat moves to fit. **From bottom** hides the button until the visitor closes the chat.

### Chat

* **Chat logo**: click **Add logo** to use an image link (it must be a direct `https://` image that doesn't need a sign-in) or an icon from the library.
* **Chat text**, per language: **Chat title**, **Chat subtitle**, **Welcome heading**, **Welcome text** and **Message placeholder**. Pick the language to edit from the menu next to **Chat text**.
* **Suggested questions**: up to 4 per language. Visitors click one to ask it. Use **Show icons** and **Show arrows** to change how they look.
* **Disclaimer**: **Show disclaimer**, an optional icon, and the **Disclaimer text** shown under the chat.
* **Appearance**: the **Accent**, **Background**, **Text** and **Prompt background** colours, and **Chat corner radius**.
* **Source tags**: up to 8 short labels on the welcome screen that tell visitors what they can ask about. Tags are one text for every language, so write them in a way that works for all your visitors.

### Languages

* **Languages**: add the languages Raily Chat should speak. 13 languages are available, including English, Hebrew, German, French, Spanish and Arabic.
* **Choose language by**:
  * **Page language**: the language your page declares.
  * **Visitor language**: the visitor's browser language.
  * **Per website**: a fixed language for each website in your list.

### Icons

Wherever you pick an icon, the **Choose icon** panel has two tabs. **Raily** has the built-in icons. **Custom** holds SVG icons your Organization uploaded: click **Upload SVG** to add one (SVG only, up to 50 KB). Uploaded icons are shared by every endpoint in the Organization.

### Save your changes

Click **Save** at the bottom of the settings. Your website picks up the new look; you don't need to change the snippet. **Discard** goes back to your last saved settings. **Restore defaults** replaces every setting, including uploaded SVGs, text, prompts, colours, languages and source tags, with Raily's defaults. Nothing changes on your website until you click **Save**.

## What visitors see

A visitor clicks the chat button and asks a question. Raily Chat answers from your endpoint's sources and shows the sources it used as cards that open in a new tab. Visitors can ask follow-up questions, including about a source from an earlier answer.

The footer reads **Powered by Raily**, with a link to raily.ai.

Raily protects the chat from bots. Before the first message, the visitor briefly sees **Checking your browser…** while Raily checks the browser. Chat needs cookies, so a visitor who blocks cookies for your site is asked to allow them and reload.

Each visitor can ask up to 30 questions a day. When a visitor reaches the limit, the chat tells them when they can ask again. The count resets at midnight UTC. [Contact us](https://www.raily.ai/contact) if your site needs a different limit.

## Remove websites or turn chat off

* **Remove one website**: click the trash icon on its row. Raily Chat stops loading there.
* **Remove every website**: click **Remove all** above the list. Raily Chat comes off your website right away. This always works, even if Chat is no longer available for your Account. If you add a website again later, the snippet you already pasted keeps working.
* **Pause chat**: turn off **Chat** and click **Save Changes**. The website chat pauses and your website list and settings are kept. Turn Chat back on to resume.

When Chat is off, the endpoint also stops answering the chat API.

## Use the chat API

Your app can chat with an endpoint over HTTP with an API key. Only API keys work here: a token from a user's sign-in is refused.

### Before you start

* Chat is on and saved for the endpoint (see [Turn on Chat](#turn-on-chat-for-an-endpoint)).
* You have the endpoint URL and an API key for the endpoint. See [Get your endpoint URL and key](https://docs.raily.ai/connect/sdk.md#get-your-endpoint-url-and-key).

### Send a question

The chat address is your endpoint URL with `/v1/chat` in place of `/mcp`. For example, `https://endpoints.app.raily.ai/t/your-workspace/123/mcp` becomes `https://endpoints.app.raily.ai/t/your-workspace/123/v1/chat`.

```bash curl theme={null}
curl https://endpoints.app.raily.ai/t/your-workspace/123/v1/chat \
  -H "Authorization: Bearer $RAILY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "What changed in the 2026 rules?"}]}'
```

```typescript TypeScript theme={null}
const response = await fetch(
  "https://endpoints.app.raily.ai/t/your-workspace/123/v1/chat",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.RAILY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      messages: [{ role: "user", content: "What changed in the 2026 rules?" }],
    }),
  },
);
const { answer, citations, sources, request_id } = await response.json();
```

### The request

Send the whole conversation in `messages` on every call. Raily keeps no conversation on its side.

| Field | Type | Description |
| - | - | - |
| `messages` | array | The conversation so far, oldest first. 1 to 50 messages. The last one must be a non-empty `user` message: that's the question. |
| `messages[].role` | `"user"` or `"assistant"` | Who wrote the message. |
| `messages[].content` | string | The message text, up to 32,000 characters. |
| `messages[].sources` | array, optional | On an `assistant` message only: the sources that answer cited, up to 8. Send them back so a follow-up like "tell me more about the second one" can still reach them. |
| `messages[].sources[].collection` | string | The source's `source_collection` from the earlier response. |
| `messages[].sources[].id` | string | The source's `id` from the earlier response. |
| `messages[].sources[].n` | integer, optional | The number your reader saw on that source, if your app shows numbers. |

A follow-up turn looks like this:

```json theme={null}
{
  "messages": [
    { "role": "user", "content": "What changed in the 2026 rules?" },
    {
      "role": "assistant",
      "content": "Two things changed [1][3]...",
      "sources": [
        { "collection": "articles", "id": "8812", "n": 1 },
        { "collection": "articles", "id": "9034", "n": 3 }
      ]
    },
    { "role": "user", "content": "Who wrote the second one?" }
  ]
}
```

### The response

```json theme={null}
{
  "answer": "Two things changed [1][3]...",
  "citations": [1, 3],
  "sources": [ { "id": "8812", "source_collection": "articles", "fields": [...], "text": "..." } ],
  "request_id": "..."
}
```

| Field | Description |
| - | - |
| `answer` | The answer, with numbered markers such as `[1]` where it cites a source. |
| `citations` | The marker numbers, in the same order as `sources`. |
| `sources` | The cited results, in the same shape the search API returns. `sources[i]` is the result the answer cites as `[citations[i]]`. |
| `request_id` | An ID for this turn. Include it when you contact support. |

The numbers in `citations` can skip (for example `[1, 3]` with two sources), so find a marker's source by its position in `citations`, not by counting.

When the endpoint has nothing relevant, `answer` holds your endpoint's no-results message and `sources` is empty.

### Errors

An error response has an `error` code, and usually a `request_id`:

| Status | `error` | What it means |
| - | - | - |
| 400 | `invalid_request` | The body isn't valid, or the last message isn't a non-empty user message. |
| 401 | `unauthorized` | No API key, or the key isn't valid for this endpoint. |
| 403 | `api_key_required` | The request used a sign-in token. Use an API key. |
| 409 | `chat_disabled` | Chat is off for this endpoint, or isn't available for your Account. |
| 413 | `body_too_large` | The conversation is over 2 MB. Send fewer messages. |
| 422 | `unsupported_query` | The endpoint can't answer this kind of question. |
| 502 | `upstream_error` | Something failed while answering. Try again. |
| 503 | `endpoint_unavailable` | The endpoint can't serve chat right now. |
| 504 | `deadline_exceeded` | No answer within 55 seconds. Try again, or ask a narrower question. |

Each call has 55 seconds to answer. Set your client's timeout a little above that, for example 65 seconds.

## Next steps

> [card] [Create an AI endpoint](https://docs.raily.ai/concepts/ai-endpoints.md)
>
> Let agents search this source

> [card] [Search from your app](https://docs.raily.ai/connect/sdk.md)
>
> Call an endpoint with an API key


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.