# telegram

 9 routes, from the API’s own OpenAPI document.

URL: https://docs.qaldy.com/reference/api/telegram/

9 routes. Every path starts at `https://cloud-api.qaldy.com`. Sign-in, tokens, errors and limits are on the [overview](https://docs.qaldy.com/reference/api/).

## Routes

| Method | Path | What it does |
|---|---|---|
| [[GET]] | [`/​v1/​workspaces/​{ws}/​telegram`](#get-v1-workspaces-ws-telegram) | Telegram for this workspace: the bot, your link, and for admins who is linked |
| [[POST]] | [`/​v1/​workspaces/​{ws}/​telegram`](#post-v1-workspaces-ws-telegram) | Turn Telegram on for a Telegram connection: sets the bot’s webhook (admins) |
| [[PATCH]] | [`/​v1/​workspaces/​{ws}/​telegram`](#patch-v1-workspaces-ws-telegram) | Choose the alerts chat and whether the weekly digest goes there (admins) |
| [[DELETE]] | [`/​v1/​workspaces/​{ws}/​telegram`](#delete-v1-workspaces-ws-telegram) | Turn Telegram off: removes the bot’s webhook; links are kept (admins) |
| [[POST]] | [`/​v1/​workspaces/​{ws}/​telegram/​check`](#post-v1-workspaces-ws-telegram-check) | Ask Telegram how delivery to the webhook is going (admins) |
| [[DELETE]] | [`/​v1/​workspaces/​{ws}/​telegram/​link`](#delete-v1-workspaces-ws-telegram-link) | Unlink your own Telegram account |
| [[POST]] | [`/​v1/​workspaces/​{ws}/​telegram/​link-code`](#post-v1-workspaces-ws-telegram-link-code) | A one-time code (10 minutes) to send to the bot to link your Telegram account |
| [[DELETE]] | [`/​v1/​workspaces/​{ws}/​telegram/​people/​{userId}`](#delete-v1-workspaces-ws-telegram-people-userid) | Unlink someone’s Telegram account from this workspace (admins) |
| [[POST]] | [`/​v1/​workspaces/​{ws}/​telegram/​test`](#post-v1-workspaces-ws-telegram-test) | Send a test message to your own linked chat |

## Reference

### [[GET]] `/v1/workspaces/{ws}/telegram`

Telegram for this workspace: the bot, your link, and for admins who is linked.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** member; console only

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspaceId` | string | yes | at least 1 characters |
| `ready` | boolean | yes |  |
| `notReady` | "keys_missing" · "pepper_missing" · "public_url_not_https" · null or null | yes |  |
| `bot` | object or null | yes |  |
| `bot.connectorId` | string | yes | 1 to 128 characters |
| `bot.connectorName` | string | yes | up to 128 characters |
| `bot.username` | string or null | yes | up to 64 characters |
| `bot.enabled` | boolean | yes |  |
| `bot.webhook` | "pending" · "set" · "failed" · "removed" | yes |  |
| `bot.webhookError` | string or null | yes | up to 64 characters |
| `bot.alertsChat` | object or null | yes |  |
| `bot.digestToChat` | boolean | yes |  |
| `bot.updatedAt` | string (date-time) | yes |  |
| `connections` | object[] | yes | up to 20 items |
| `connections[].id` | string | yes | 1 to 128 characters |
| `connections[].displayName` | string | yes | 1 to 128 characters |
| `connections[].status` | "connected" · "expired" · "error" · "disconnected" | yes |  |
| `canManage` | boolean | yes |  |
| `me` | object | yes |  |
| `me.linked` | boolean | yes |  |
| `me.telegramUsername` | string or null | yes | up to 64 characters |
| `me.linkedAt` | string (date-time) or null | yes |  |
| `me.codeExpiresAt` | string (date-time) or null | yes |  |
| `people` | object[] | yes | up to 500 items |
| `people[].userId` | string | yes | 1 to 128 characters |
| `people[].name` | string | yes | up to 200 characters |
| `people[].telegramUsername` | string or null | yes | up to 64 characters |
| `people[].linkedAt` | string (date-time) | yes |  |
| `people[].lastSeenAt` | string (date-time) or null | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[POST]] `/v1/workspaces/{ws}/telegram`

Turn Telegram on for a Telegram connection: sets the bot’s webhook (admins).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin; console only

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `connectorId` | string | yes | 1 to 128 characters |
| `replaceExisting` | boolean |  |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspaceId` | string | yes | at least 1 characters |
| `ready` | boolean | yes |  |
| `notReady` | "keys_missing" · "pepper_missing" · "public_url_not_https" · null or null | yes |  |
| `bot` | object or null | yes |  |
| `bot.connectorId` | string | yes | 1 to 128 characters |
| `bot.connectorName` | string | yes | up to 128 characters |
| `bot.username` | string or null | yes | up to 64 characters |
| `bot.enabled` | boolean | yes |  |
| `bot.webhook` | "pending" · "set" · "failed" · "removed" | yes |  |
| `bot.webhookError` | string or null | yes | up to 64 characters |
| `bot.alertsChat` | object or null | yes |  |
| `bot.digestToChat` | boolean | yes |  |
| `bot.updatedAt` | string (date-time) | yes |  |
| `connections` | object[] | yes | up to 20 items |
| `connections[].id` | string | yes | 1 to 128 characters |
| `connections[].displayName` | string | yes | 1 to 128 characters |
| `connections[].status` | "connected" · "expired" · "error" · "disconnected" | yes |  |
| `canManage` | boolean | yes |  |
| `me` | object | yes |  |
| `me.linked` | boolean | yes |  |
| `me.telegramUsername` | string or null | yes | up to 64 characters |
| `me.linkedAt` | string (date-time) or null | yes |  |
| `me.codeExpiresAt` | string (date-time) or null | yes |  |
| `people` | object[] | yes | up to 500 items |
| `people[].userId` | string | yes | 1 to 128 characters |
| `people[].name` | string | yes | up to 200 characters |
| `people[].telegramUsername` | string or null | yes | up to 64 characters |
| `people[].linkedAt` | string (date-time) | yes |  |
| `people[].lastSeenAt` | string (date-time) or null | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[PATCH]] `/v1/workspaces/{ws}/telegram`

Choose the alerts chat and whether the weekly digest goes there (admins).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin; console only

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `alertsChat` | string or null |  |  |
| `digestToChat` | boolean |  |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspaceId` | string | yes | at least 1 characters |
| `ready` | boolean | yes |  |
| `notReady` | "keys_missing" · "pepper_missing" · "public_url_not_https" · null or null | yes |  |
| `bot` | object or null | yes |  |
| `bot.connectorId` | string | yes | 1 to 128 characters |
| `bot.connectorName` | string | yes | up to 128 characters |
| `bot.username` | string or null | yes | up to 64 characters |
| `bot.enabled` | boolean | yes |  |
| `bot.webhook` | "pending" · "set" · "failed" · "removed" | yes |  |
| `bot.webhookError` | string or null | yes | up to 64 characters |
| `bot.alertsChat` | object or null | yes |  |
| `bot.digestToChat` | boolean | yes |  |
| `bot.updatedAt` | string (date-time) | yes |  |
| `connections` | object[] | yes | up to 20 items |
| `connections[].id` | string | yes | 1 to 128 characters |
| `connections[].displayName` | string | yes | 1 to 128 characters |
| `connections[].status` | "connected" · "expired" · "error" · "disconnected" | yes |  |
| `canManage` | boolean | yes |  |
| `me` | object | yes |  |
| `me.linked` | boolean | yes |  |
| `me.telegramUsername` | string or null | yes | up to 64 characters |
| `me.linkedAt` | string (date-time) or null | yes |  |
| `me.codeExpiresAt` | string (date-time) or null | yes |  |
| `people` | object[] | yes | up to 500 items |
| `people[].userId` | string | yes | 1 to 128 characters |
| `people[].name` | string | yes | up to 200 characters |
| `people[].telegramUsername` | string or null | yes | up to 64 characters |
| `people[].linkedAt` | string (date-time) | yes |  |
| `people[].lastSeenAt` | string (date-time) or null | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[DELETE]] `/v1/workspaces/{ws}/telegram`

Turn Telegram off: removes the bot’s webhook; links are kept (admins).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin; console only

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspaceId` | string | yes | at least 1 characters |
| `ready` | boolean | yes |  |
| `notReady` | "keys_missing" · "pepper_missing" · "public_url_not_https" · null or null | yes |  |
| `bot` | object or null | yes |  |
| `bot.connectorId` | string | yes | 1 to 128 characters |
| `bot.connectorName` | string | yes | up to 128 characters |
| `bot.username` | string or null | yes | up to 64 characters |
| `bot.enabled` | boolean | yes |  |
| `bot.webhook` | "pending" · "set" · "failed" · "removed" | yes |  |
| `bot.webhookError` | string or null | yes | up to 64 characters |
| `bot.alertsChat` | object or null | yes |  |
| `bot.digestToChat` | boolean | yes |  |
| `bot.updatedAt` | string (date-time) | yes |  |
| `connections` | object[] | yes | up to 20 items |
| `connections[].id` | string | yes | 1 to 128 characters |
| `connections[].displayName` | string | yes | 1 to 128 characters |
| `connections[].status` | "connected" · "expired" · "error" · "disconnected" | yes |  |
| `canManage` | boolean | yes |  |
| `me` | object | yes |  |
| `me.linked` | boolean | yes |  |
| `me.telegramUsername` | string or null | yes | up to 64 characters |
| `me.linkedAt` | string (date-time) or null | yes |  |
| `me.codeExpiresAt` | string (date-time) or null | yes |  |
| `people` | object[] | yes | up to 500 items |
| `people[].userId` | string | yes | 1 to 128 characters |
| `people[].name` | string | yes | up to 200 characters |
| `people[].telegramUsername` | string or null | yes | up to 64 characters |
| `people[].linkedAt` | string (date-time) | yes |  |
| `people[].lastSeenAt` | string (date-time) or null | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[POST]] `/v1/workspaces/{ws}/telegram/check`

Ask Telegram how delivery to the webhook is going (admins).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin; console only

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `urlSet` | boolean | yes |  |
| `pending` | integer | yes | at least 0 |
| `lastError` | string or null | yes | up to 400 characters |
| `lastErrorAt` | string (date-time) or null | yes |  |
| `reason` | string or null | yes | up to 64 characters |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[DELETE]] `/v1/workspaces/{ws}/telegram/link`

Unlink your own Telegram account.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** member; console only

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspaceId` | string | yes | at least 1 characters |
| `ready` | boolean | yes |  |
| `notReady` | "keys_missing" · "pepper_missing" · "public_url_not_https" · null or null | yes |  |
| `bot` | object or null | yes |  |
| `bot.connectorId` | string | yes | 1 to 128 characters |
| `bot.connectorName` | string | yes | up to 128 characters |
| `bot.username` | string or null | yes | up to 64 characters |
| `bot.enabled` | boolean | yes |  |
| `bot.webhook` | "pending" · "set" · "failed" · "removed" | yes |  |
| `bot.webhookError` | string or null | yes | up to 64 characters |
| `bot.alertsChat` | object or null | yes |  |
| `bot.digestToChat` | boolean | yes |  |
| `bot.updatedAt` | string (date-time) | yes |  |
| `connections` | object[] | yes | up to 20 items |
| `connections[].id` | string | yes | 1 to 128 characters |
| `connections[].displayName` | string | yes | 1 to 128 characters |
| `connections[].status` | "connected" · "expired" · "error" · "disconnected" | yes |  |
| `canManage` | boolean | yes |  |
| `me` | object | yes |  |
| `me.linked` | boolean | yes |  |
| `me.telegramUsername` | string or null | yes | up to 64 characters |
| `me.linkedAt` | string (date-time) or null | yes |  |
| `me.codeExpiresAt` | string (date-time) or null | yes |  |
| `people` | object[] | yes | up to 500 items |
| `people[].userId` | string | yes | 1 to 128 characters |
| `people[].name` | string | yes | up to 200 characters |
| `people[].telegramUsername` | string or null | yes | up to 64 characters |
| `people[].linkedAt` | string (date-time) | yes |  |
| `people[].lastSeenAt` | string (date-time) or null | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[POST]] `/v1/workspaces/{ws}/telegram/link-code`

A one-time code (10 minutes) to send to the bot to link your Telegram account.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** member; console only

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `locale` | "en" · "ru" · "kk" |  |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `code` | string | yes |  |
| `expiresAt` | string (date-time) | yes |  |
| `deepLink` | string or null | yes | up to 200 characters |
| `botUsername` | string or null | yes | up to 64 characters |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[DELETE]] `/v1/workspaces/{ws}/telegram/people/{userId}`

Unlink someone’s Telegram account from this workspace (admins).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin; console only

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |
| `userId` | path | string | yes |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspaceId` | string | yes | at least 1 characters |
| `ready` | boolean | yes |  |
| `notReady` | "keys_missing" · "pepper_missing" · "public_url_not_https" · null or null | yes |  |
| `bot` | object or null | yes |  |
| `bot.connectorId` | string | yes | 1 to 128 characters |
| `bot.connectorName` | string | yes | up to 128 characters |
| `bot.username` | string or null | yes | up to 64 characters |
| `bot.enabled` | boolean | yes |  |
| `bot.webhook` | "pending" · "set" · "failed" · "removed" | yes |  |
| `bot.webhookError` | string or null | yes | up to 64 characters |
| `bot.alertsChat` | object or null | yes |  |
| `bot.digestToChat` | boolean | yes |  |
| `bot.updatedAt` | string (date-time) | yes |  |
| `connections` | object[] | yes | up to 20 items |
| `connections[].id` | string | yes | 1 to 128 characters |
| `connections[].displayName` | string | yes | 1 to 128 characters |
| `connections[].status` | "connected" · "expired" · "error" · "disconnected" | yes |  |
| `canManage` | boolean | yes |  |
| `me` | object | yes |  |
| `me.linked` | boolean | yes |  |
| `me.telegramUsername` | string or null | yes | up to 64 characters |
| `me.linkedAt` | string (date-time) or null | yes |  |
| `me.codeExpiresAt` | string (date-time) or null | yes |  |
| `people` | object[] | yes | up to 500 items |
| `people[].userId` | string | yes | 1 to 128 characters |
| `people[].name` | string | yes | up to 200 characters |
| `people[].telegramUsername` | string or null | yes | up to 64 characters |
| `people[].linkedAt` | string (date-time) | yes |  |
| `people[].lastSeenAt` | string (date-time) or null | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[POST]] `/v1/workspaces/{ws}/telegram/test`

Send a test message to your own linked chat.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** member; console only

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `sent` | boolean | yes |  |
| `reason` | string or null | yes | up to 64 characters |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).