# Overview (/docs/telegram-api/overview)



CRMchat exposes Telegram's TL methods as REST endpoints. This gives you direct access to the
Telegram API through a Telegram account already connected to your workspace.

**Base URL:** `https://api.crmchat.ai/v1`

<Callout type="warn" title="Account safety">
  Incorrect or abusive usage of the Telegram API can result in your account being temporarily or
  permanently banned by Telegram. Avoid bulk operations, rapid-fire requests, and unsolicited
  messaging. CRMchat is not responsible for account restrictions caused by API misuse.
</Callout>

## Quick start [#quick-start]

### 1. Create an API key [#1-create-an-api-key]

[Create an API key](https://app.crmchat.ai/mini-app/settings/api-keys), copy it, and store it
securely. See [Authentication](/docs/authentication) for key scopes and security practices.

### 2. Find an active Telegram account [#2-find-an-active-telegram-account]

1. List your organizations with `GET /v1/organizations` and copy the organization `id`.
2. List its workspaces with `GET /v1/workspaces?organizationId={organizationId}` and copy the workspace `id`.
3. List its Telegram accounts with `GET /v1/workspaces/{workspaceId}/telegram-accounts`, then choose an account with `status: "active"` and copy its `id`.

### 3. Make your first Telegram call [#3-make-your-first-telegram-call]

Use the selected workspace and account IDs to retrieve the connected Telegram user's profile.
This read-only call confirms that authentication, workspace access, and the Telegram connection
all work:

```bash
curl --request POST \
  --url https://api.crmchat.ai/v1/workspaces/{workspaceId}/telegram-accounts/{accountId}/call/users.getFullUser \
  --header "Authorization: Bearer sk_your_api_key" \
  --header "Content-Type: application/json" \
  --data '{"params":{"id":{"_":"inputUserSelf"}}}'
```

Parameters always go inside `params`. Successful responses wrap the Telegram result in `result`:

```json
{
  "result": {
    "_": "users.userFull",
    "...": "method-specific fields"
  }
}
```

You're ready. **Telegram Methods** lists the required parameters and response type for every
available method.

## Telegram values in JSON [#telegram-values-in-json]

| TL Type     | JSON Format                             |
| ----------- | --------------------------------------- |
| `long`      | String (numeric, 64-bit safe)           |
| `bytes`     | Base64 string                           |
| `int128`    | Hex string (32 chars)                   |
| `int256`    | Hex string (64 chars)                   |
| `Bool`      | Boolean                                 |
| `Vector<T>` | Array                                   |
| Constructor | `{ "_": "constructorName", ...fields }` |

### Peers and access hashes [#peers-and-access-hashes]

Methods that target a user, chat, or channel usually take an `InputPeer`, `InputUser`, or
`InputChannel` constructor rather than a bare ID. Users and channels also require the
`accessHash` returned by Telegram.

Use `contacts.resolveUsername`, `contacts.search`, or `messages.getDialogs` to obtain IDs and
access hashes. Keep each access hash with its matching ID.

### Random IDs [#random-ids]

Methods that create messages, such as `messages.sendMessage`, require a `randomId`. Send it as a
unique 64-bit integer string. Reuse it only when retrying the same operation; Telegram uses it to
deduplicate requests.

### Joined responses [#joined-responses]

Methods such as `messages.getDialogs` and `contacts.search` return related objects in separate
arrays. Join `dialogs`, `messages`, `users`, and `chats` by their IDs. The matching user or channel
object is also where you obtain its `accessHash`.

## Common workflows [#common-workflows]

* **Message a username:** `contacts.resolveUsername` → `messages.sendMessage`
* **Message an existing conversation:** `messages.getDialogs` → join the peer with `users` or
  `chats` → `messages.sendMessage`
* **Read conversation history:** resolve an input peer → `messages.getHistory`
* **Join or leave a channel:** resolve the channel → pass an `InputChannel` to
  `channels.joinChannel` or `channels.leaveChannel`

## Receive updates with Telegram webhooks [#receive-updates-with-telegram-webhooks]

Raw method calls are request-response operations. To react to incoming messages, edits, deletions,
reactions, typing activity, and other Telegram events without polling, use Telegram webhooks.

CRMchat delivers selected raw updates from connected accounts to your HTTPS endpoint. You can
filter by update type and account, and every request includes an HMAC signature for verification.
See [Telegram Webhooks](/docs/telegram-webhooks) for setup, supported events, and delivery details.

## Errors and limits [#errors-and-limits]

CRMchat's [API rate limit](/docs/authentication#rate-limiting) still applies. Telegram enforces
additional, method-specific limits. When Telegram returns `FLOOD_WAIT_X`, wait the stated number
of seconds before retrying:

```json
{
  "code": "BAD_REQUEST",
  "message": "FLOOD_WAIT_42",
  "data": {
    "code": "TELEGRAM_RPC_ERROR",
    "tlErrorCode": 420,
    "tlErrorMessage": "FLOOD_WAIT_42"
  }
}
```

Only methods listed in **Telegram Methods** are available. CRMchat excludes authentication and
session internals, dangerous account operations, and methods that require unsupported binary
uploads.

## Machine-readable schemas [#machine-readable-schemas]

OpenAPI schemas are available for code generators, API clients, and AI agents:

* **Method list:** `/v1/tl-spec/manifest.json`
* **Full schema:** `/v1/tl-spec/all.json`
* **Namespace:** `/v1/tl-spec/{namespace}.json`
* **Single method:** `/v1/tl-spec/{namespace}/{method}.json`

Start with the manifest and fetch per-method schemas as needed instead of loading the full schema.