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

# Send X monitor alerts to a Telegram chat with a bot

> Get a t.me link that connects a Telegram chat to your monitor events. Press Start in @XquikBot and each event arrives as a message. It costs no credits.

<Panel>
  <Tabs defaultTabIndex={0} sync={false}>
    <Tab title="201" id="response-webhooks-telegram-201">
      ```json theme={null}
      {
        "url": "https://t.me/XquikBot?start=Q2hhdExpbmtDb2RlRXhhbXBsZTAx",
        "expiresAt": "2025-01-15T12:15:00.000Z"
      }
      ```
    </Tab>

    <Tab title="400" id="response-webhooks-telegram-400">
      ```json theme={null}
      {
        "error": "invalid_input",
        "message": "Invalid input. Check the request body."
      }
      ```
    </Tab>

    <Tab title="401" id="response-webhooks-telegram-401">
      ```json theme={null}
      {
        "error": "unauthenticated",
        "message": "Authentication required. Provide a valid API key or bearer token."
      }
      ```
    </Tab>

    <Tab title="429" id="response-webhooks-telegram-429">
      ```json theme={null}
      {
        "error": "rate_limit_exceeded",
        "message": "Too many requests. Try again later.",
        "retryAfter": 60
      }
      ```
    </Tab>

    <Tab title="503" id="response-webhooks-telegram-503">
      ```json theme={null}
      {
        "error": "telegram_unavailable",
        "message": "Telegram alerts are off right now. Try again later."
      }
      ```
    </Tab>
  </Tabs>
</Panel>

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

<Callout icon="circle-check" color="#16a34a">
  **Free.** Connecting a chat and its messages cost no credits.
</Callout>

Get your monitor events in Telegram with no server of your own. The call
returns a link to @XquikBot. Open it and press Start. The chat is connected.

## How it works

1. Call this endpoint. It returns a `url` like `https://t.me/XquikBot?start=...`.
2. Open the link on a phone or computer with Telegram, then press **Start**.
3. @XquikBot answers "Connected." Each new event of your monitors arrives as a
   message: the account and event type in bold, the post's text or the profile
   change, and a link to the post.

* A link works once, within 15 minutes. Make a new one if it expires.
* The chat appears in [List webhooks](/api-reference/webhooks/list) with the URL
  `telegram:<chat ID>`. [Deliveries](/api-reference/webhooks/deliveries),
  retries, [Resume](/api-reference/webhooks/resume) and
  [Test webhook](/api-reference/webhooks/test) work as for any webhook.
* In the chat, send `/stop` to pause alerts and `/status` to check them. A new
  link turns them on again.
* When Telegram asks Xquik to slow down, the retry waits as long as it asks.
* @XquikBot works in private chats. It answers in English, Turkish or Spanish,
  by your Telegram language.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://xquik.com/api/v1/webhooks/telegram" \
    -H "x-api-key: xq_YOUR_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{"eventTypes": ["tweet.new", "tweet.reply"]}' \
    | jq -r '.url'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://xquik.com/api/v1/webhooks/telegram", {
    method: "POST",
    headers: {
      "x-api-key": "xq_YOUR_KEY_HERE",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ eventTypes: ["tweet.new", "tweet.reply"] }),
  });
  const link = await response.json();
  console.log(`Open ${link.url} before ${link.expiresAt}`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://xquik.com/api/v1/webhooks/telegram",
      headers={"x-api-key": "xq_YOUR_KEY_HERE"},
      json={"eventTypes": ["tweet.new", "tweet.reply"]},
  )
  link = response.json()
  print(f"Open {link['url']} before {link['expiresAt']}")
  ```
</CodeGroup>

## Body

<ParamField body="eventTypes" type="string[]">
  The event types the chat gets, like `tweet.new` or `profile.bio.changed`. Omit
  the body or this field to get every event type.
</ParamField>

## Headers

<ParamField header="x-api-key" type="string" required>
  Your API key.
</ParamField>

## Response

### 201 Created

```json theme={null}
{
  "url": "https://t.me/XquikBot?start=Q2hhdExpbmtDb2RlRXhhbXBsZTAx",
  "expiresAt": "2025-01-15T12:15:00.000Z"
}
```

<ResponseField name="url" type="string">
  Opens @XquikBot with the link's code. Open it and press Start.
</ResponseField>

<ResponseField name="expiresAt" type="string">
  When the link stops working, 15 minutes after it was made.
</ResponseField>

### 400 Invalid input

```json theme={null}
{
  "error": "invalid_input",
  "message": "Pick at least 1 valid event type, like tweet.new."
}
```

An event type is unknown. Use the types the monitor endpoints list.

### 401 Unauthenticated

```json theme={null}
{ "error": "unauthenticated" }
```

Missing or invalid API key. Check the `x-api-key` header value.

### 503 Telegram unavailable

```json theme={null}
{
  "error": "telegram_unavailable",
  "message": "Telegram alerts are off right now. Try again later."
}
```

Telegram delivery is off for now. Try again later.

<Note>
  **Related.** [Webhooks overview](/webhooks/overview) · [List webhooks](/api-reference/webhooks/list) · [Webhook deliveries](/api-reference/webhooks/deliveries)
</Note>


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