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

# Subscribe Telegram Chat

> Deliver tracked events to a Telegram chat

Register a Telegram chat to receive events for everything tracked under your API key. Each API key maps to one chat — subscribing again replaces the existing chat.

Before saving, Scrapest sends a confirmation message to the chat. If the bot can't post there (not a member, kicked, wrong chat ID), the request fails — add the Scrapest bot to the chat first.

## How events are delivered

Each tracked event is delivered to the chat as a **Telegram document** — the full `SourceEvent` JSON is attached as a `payload.json` file, with a human-readable summary as the message caption. This keeps large payloads intact without hitting Telegram's message-length limits.

Delivery is throttled to roughly **1 message per second per chat**. If Telegram rate-limits the bot (HTTP 429), Scrapest backs off and retries automatically, so bursts are smoothed out rather than dropped.

## Request Body

<ParamField body="chatId" type="string" required>
  The Telegram chat ID to deliver events to. Group chat IDs are negative numbers
  (e.g. `-1001234567890`).
</ParamField>

<ParamField body="name" type="string" default="default">
  A label for this subscription, shown in the confirmation message.
</ParamField>

## Response

<ResponseField name="message" type="string">
  `Subscription registered` on first subscribe, `Subscription updated` when
  replacing an existing chat.
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://scrape.st/tg_subscribe \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "chatId": "-1001234567890",
      "name": "alerts"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "message": "Subscription registered"
  }
  ```
</ResponseExample>