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

Quick start

1. Create an API key

Create an API key, copy it, and store it securely. See Authentication for key scopes and security practices.

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

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:

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:

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

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

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

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

• 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

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 for setup, supported events, and delivery details.

Errors and limits

CRMchat's API rate limit still applies. Telegram enforces additional, method-specific limits. When Telegram returns FLOOD_WAIT_X, wait the stated number of seconds before retrying:

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

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.