> ## Documentation Index > Fetch the complete documentation index at: https://docs.dmly.io/llms.txt > Use this file to discover all available pages before exploring further. # Connect a Telegram bot. > Telegram has no consent screen, so there is no hosted session: your app collects the customer's BotFather bot token and sends it here from your backend. DMLY validates it with Telegram, creates the channel, points the bot's webhook at DMLY and returns the channel, with `meta.webhook_registered`. Returns 201 for a new bot and 200 when the same bot is already connected to this sub-account (a new token for it refreshes the channel in place). Returns 422 with an error on `bot_token` when Telegram rejects the token or the bot is connected to another DMLY workspace, 422 on `channel` when the plan has no room, and 403 when Channel Connect is not enabled for your agency or the sub-account is suspended. The token is never returned. ## OpenAPI ````yaml /api-reference/agency-openapi.json post /workspaces/{workspace}/channels/telegram openapi: 3.1.0 info: title: DMLY Agency API version: 1.0.0 description: >- The DMLY Agency API lets a whitelabel reseller manage its sub-accounts programmatically — provision customer workspaces, assign plans and add-ons, and subscribe to sub-account lifecycle events. It is a separate surface from the public workspace [REST API](/api-reference/introduction): a different base URL, a different key, and a different set of webhooks. ## Base URL ``` https://dash.dmly.io/api/agency/v1 ``` ## Authentication Every request carries an **agency API key**, which authenticates the acting agency and scopes every request to that agency's own sub-accounts — an agency can only ever see and act on its own workspaces. ``` x-api-key: dmly_ag_xxxxxxxx… ``` `Authorization: Bearer dmly_ag_xxxxxxxx…` is also accepted. Mint and revoke keys from the agency console under **API Keys**. The plaintext key is shown **once** on creation; only its hash is stored. An agency key is different from a workspace API key (`dmly_…`) and is not interchangeable with it. ## Conventions - Sub-accounts, plans, add-ons and webhook endpoints are identified by their public `uuid`, returned as `uuid`. - Lists are paginated with `?per_page` (alias `?limit`) — default 25, hard cap 100. ## Availability The whole surface can be disabled fleet-wide during an incident without revoking individual keys; while it is off, every endpoint returns `503`. contact: name: DMLY url: https://dmly.io servers: - url: https://dash.dmly.io/api/agency/v1 description: DMLY security: - agencyApiKeyAuth: [] - agencyBearerAuth: [] tags: - name: Agency Plans description: Endpoints for Agency Plans. - name: Agency Subscriptions and add-ons description: Endpoints for Agency Subscriptions and add-ons. - name: Agency Webhook endpoints description: Endpoints for Agency Webhook endpoints. - name: Agency Workspaces description: Endpoints for Agency Workspaces. - name: Agency Channel Connect description: >- Let your customers connect WhatsApp, Messenger, Instagram, TikTok and Telegram from your own app (private beta). - name: Agency events description: Sub-account lifecycle events DMLY posts to your endpoint. paths: /workspaces/{workspace}/channels/telegram: post: tags: - Agency Channel Connect summary: Connect a Telegram bot. description: >- Telegram has no consent screen, so there is no hosted session: your app collects the customer's BotFather bot token and sends it here from your backend. DMLY validates it with Telegram, creates the channel, points the bot's webhook at DMLY and returns the channel, with `meta.webhook_registered`. Returns 201 for a new bot and 200 when the same bot is already connected to this sub-account (a new token for it refreshes the channel in place). Returns 422 with an error on `bot_token` when Telegram rejects the token or the bot is connected to another DMLY workspace, 422 on `channel` when the plan has no room, and 403 when Channel Connect is not enabled for your agency or the sub-account is suspended. The token is never returned. operationId: channels.telegram.post parameters: - name: workspace in: path required: true description: Workspace id. schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: - bot_token properties: bot_token: type: string description: The token @BotFather issued for the bot. name: type: string maxLength: 120 description: Optional channel name. Defaults to the bot's username. example: bot_token: 123456789:AAbbCCddEEffGGhhIIjjKKllMMnnOOpp name: Sparkle Cleaning responses: '200': description: 'The same bot, already connected: its channel, refreshed.' '201': description: Connected. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Channel' meta: type: object properties: webhook_registered: type: boolean example: data: id: 55555555-5555-5555-5555-555555555555 name: Telegram · @sparkle_bot platform: telegram handle: '@sparkle_bot' status: connected connected: true created_at: '2026-10-06T12:04:11+00:00' meta: webhook_registered: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/Unavailable' components: schemas: Channel: type: object properties: id: type: string format: uuid name: type: string platform: type: string handle: type: string nullable: true status: type: string connected: type: boolean created_at: type: string format: date-time Error: type: object properties: message: type: string ValidationError: type: object properties: message: type: string errors: type: object description: Field name → array of messages. additionalProperties: type: array items: type: string responses: Unauthorized: description: The agency API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: This agency has been suspended, so its keys no longer work. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: >- No such resource for this agency — the uuid is unknown or belongs to another agency. content: application/json: schema: $ref: '#/components/schemas/Error' ValidationError: description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/ValidationError' RateLimited: description: >- Rate limit exceeded: 120 requests per minute per agency key. Requests without a valid key share a per-IP budget of 60 per minute instead. headers: Retry-After: description: Seconds until the limit resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' Unavailable: description: The reseller API is currently disabled fleet-wide. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: agencyApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your agency API key (`dmly_ag_…`). It authenticates the acting agency and scopes every request to that agency's own sub-accounts and plans. agencyBearerAuth: type: http scheme: bearer description: 'The same agency API key, sent as `Authorization: Bearer dmly_ag_…`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.