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

# Telegram alerts for monitors, X (Twitter) API docs

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

> For the complete documentation index, see [llms.txt](https://docs.xquik.com/llms.txt).

`POST https://xquik.com/api/v1/webhooks/telegram`

**Free.** Connecting a chat and its messages cost no credits.

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 alert then arrives as a message.
   It shows the account and the event in bold.
   It also shows the post's text or the profile change, and a link.

* Alerts that wait together come as 1 digest.

* A busy chat gets 5 quick messages, then 1 every 30 seconds. A quiet chat gets
  each alert at once.

* Only the first message of a minute rings. The rest arrive silently.

* A post that is new and has media is 1 alert. Its title is "New post with media".

* A link works once, within 15 minutes. Make a new one if it expires.

* The chat appears in [List webhooks](https://docs.xquik.com/api-reference/webhooks/list.md) with the URL
  `telegram:<chat ID>`. [Deliveries](https://docs.xquik.com/api-reference/webhooks/deliveries.md),
  retries, [Resume](https://docs.xquik.com/api-reference/webhooks/resume.md) and
  [Test webhook](https://docs.xquik.com/api-reference/webhooks/test.md) 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.

* Telegram can ask Xquik to slow down. When it does, the retry waits as long as it asks.

* @XquikBot works in private chats. It answers in English, Spanish, Turkish,
  Japanese, Korean or Chinese, by your Telegram language. Other languages get
  English.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
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={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
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={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
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']}")
```

## Body

| Body parameter | Type | Required | Description |
| - | - | - | - |
| `eventTypes` | `string[]` | No | The event types the chat gets, like `tweet.new` or `tweet.reply`. Omit the body or this field to get new posts only. |

## Headers

| Header | Type | Required | Description |
| - | - | - | - |
| `x-api-key` | `string` | Yes | Your API key. |

## Response

### 201 Created

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
{
  "url": "https://t.me/XquikBot?start=Q2hhdExpbmtDb2RlRXhhbXBsZTAx",
  "expiresAt": "2025-01-15T12:15:00.000Z"
}
```

| Field | Type | Description |
| - | - | - |
| `url` | `string` | Opens @XquikBot with the link's code. Open it and press Start. |
| `expiresAt` | `string` | When the link stops working, 15 minutes after it was made. |

### 400 Invalid input

`{ "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

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

### 503 Telegram unavailable

Telegram delivery is off for now. Try again later.

> [!NOTE]
>
> **Related.** [Webhooks overview](https://docs.xquik.com/webhooks/overview.md) · [List webhooks](https://docs.xquik.com/api-reference/webhooks/list.md) · [Webhook deliveries](https://docs.xquik.com/api-reference/webhooks/deliveries.md)

## Response examples

* **400** `{ "error": "invalid_input", "message": "Invalid input. Check the request body." }`
* **401** `{ "error": "unauthenticated", "message": "Authentication required. Provide a valid API key or bearer token." }`
* **403** `{ "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." }`
* **429** `{ "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }`
* **503** `{ "error": "telegram_unavailable", "message": "Telegram alerts are off right now. Try again later." }`


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