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

# Telegram

> POST /v1/platform-users/telegram/link, GET /v1/platform-users/telegram and POST /telegram/unlink: link a platform user's Telegram account, check it, or remove it.

A platform user can link their Telegram account through the CabalSpy ID Telegram bot. The linked account shows in the [user object](https://docs.cabalspy.xyz/cabalspy-id/platform-users-get.md#response) as `telegram`.

## Link

`POST /v1/platform-users/telegram/link`

Returns a `deep_link` to the bot with a one-time code. Show it to the user as a button or QR code. When they open it and start the bot, the account is linked. Check with the status endpoint below.

**external\_id** `string` *required*

Your id of the user. Alternatively pass csid\_id.

```bash cURL theme={null}
curl -X POST "https://api-id.cabalspy.xyz/v1/platform-users/telegram/link" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "user_8412"}'
```

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

r = requests.post("https://api-id.cabalspy.xyz/v1/platform-users/telegram/link",
                  json={"external_id": "user_8412"},
                  headers={"Authorization": "Bearer YOUR_KEY"})
print(r.json()["data"]["deep_link"])
```

```javascript JavaScript theme={null}
const res = await fetch("https://api-id.cabalspy.xyz/v1/platform-users/telegram/link", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ external_id: "user_8412" }),
});
const { data } = await res.json();
console.log(data.deep_link, data.expires_at);
```

**external\_id** `string`

Your id of the user.

**code** `string`

The one-time code inside the deep link.

**deep\_link** `string`

`https://t.me/...?start=<code>`, the link to open.

**expires\_at** `string`

When the code expires.

## Status

`GET /v1/platform-users/telegram?external_id=<id>`

```bash theme={null}
curl "https://api-id.cabalspy.xyz/v1/platform-users/telegram?external_id=user_8412" \
  -H "Authorization: Bearer YOUR_KEY"
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "external_id": "user_8412",
    "linked": true,
    "username": "maze_calls",
    "linked_at": "2026-10-26T08:06:40Z"
  },
  "meta": { "request_id": "req_5162c7cf7f87", "cached": false, "cache_age_seconds": 0, "version": "v1", "timestamp": "2026-10-26T08:07:00Z" }
}
```

`username` and `linked_at` are null while nothing is linked.

## Unlink

`POST /v1/platform-users/telegram/unlink`

Removes the linked Telegram account. Returns `external_id` and `"linked": false`.

**external\_id** `string` *required*

Your id of the user. Alternatively pass csid\_id.

```bash theme={null}
curl -X POST "https://api-id.cabalspy.xyz/v1/platform-users/telegram/unlink" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "user_8412"}'
```

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | external\_id missing. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid or not enabled for CabalSpy ID. |
| 404 | platform\_user\_not\_found | No user with this id in your instance. |
| 409 | account\_claimed | Link or unlink: the person claimed the account and manages it themselves. |
| 503 | service\_unavailable | Link: Telegram linking is temporarily unavailable. |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |

See [Errors](https://docs.cabalspy.xyz/cabalspy-id/errors.md) for the full list.


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