> ## Documentation Index > Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt > Use this file to discover all available pages before exploring further. # Criar instância Telegram > Conecta uma conta Telegram ao seu workspace — o canal por onde entram e saem mensagens. Escolha o exemplo: - **Bot com token** — robô que responde sozinho (@BotFather). - **Conta de usuário: QR na sua tela** — você exibe o código e faz login na hora. - **Conta de usuário: link para o cliente** — envia um link; a pessoa conclui o login no Telegram dela. Escopo: **telegram:instances:create**. ## OpenAPI ````yaml /telegram-api/api-reference/openapi-telegram.json post /v1/telegram/instances openapi: 3.0.3 info: title: Notifique API — Telegram description: >- Envie mensagens Telegram e gerencie conexões. Autentique com `Authorization: Bearer sk_live_...` ou `x-api-key`. version: 1.0.0 servers: - url: https://api.notifique.dev description: Produção security: - ntfTgBearerAuth: [] - ntfTgApiKeyHeader: [] tags: - name: Mensagens description: Enviar e gerenciar mensagens - name: Instâncias description: Criar e conectar bots ou contas USER - name: Chats description: Listar chats paths: /v1/telegram/instances: post: tags: - Instâncias summary: Criar instância Telegram description: >- Conecta uma conta Telegram ao seu workspace — o canal por onde entram e saem mensagens. Escolha o exemplo: - **Bot com token** — robô que responde sozinho (@BotFather). - **Conta de usuário: QR na sua tela** — você exibe o código e faz login na hora. - **Conta de usuário: link para o cliente** — envia um link; a pessoa conclui o login no Telegram dela. Escopo: **telegram:instances:create**. operationId: ntfTg_postV1TelegramInstances requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NtfTg_CreateTelegramInstanceRequest' examples: botWithToken: summary: Bot com token description: Robô Telegram — cole o token do @BotFather. value: name: Atendimento mode: BOT botToken: 123456:ABC-DEF userQrOnYourScreen: summary: 'Conta de usuário: QR na sua tela' description: >- Você mostra o QR na sua interface; quem faz login precisa estar aí. value: name: Minha conta TG mode: USER acceptUserTerms: true userLinkForCustomer: summary: 'Conta de usuário: link para o cliente' description: Envie o link para outra pessoa concluir o login no Telegram. value: name: Atendimento TG mode: USER acceptUserTerms: true generateShareableLink: true responses: '200': description: >- Conta cadastrada. Bot fica **ACTIVE** com `webhookUrl`. Conta de usuário costuma ficar **PENDING** até concluir o login (QR ou link). content: application/json: schema: $ref: '#/components/schemas/NtfTg_CreateTelegramInstanceResponse' examples: bot: summary: Bot value: success: true data: id: clxx_inst_bot name: Atendimento status: ACTIVE mode: BOT botUsername: '@meubot' webhookUrl: >- https://api.notifique.dev/webhooks/telegram/clxx_inst_bot user: summary: Conta de usuário (aguardando login) value: success: true data: id: clxx_inst_user name: Minha conta status: PENDING mode: USER connection: status: WAITING_QR loginUrl: tg://login?token=... expiresSeconds: 30 base64: data:image/png;base64,... message: >- Use GET .../qr ou POST .../session para concluir o login. code: TELEGRAM_USER_PENDING_SESSION userShareable: summary: Conta de usuário com link compartilhável value: success: true data: id: clxx_inst_user name: Minha conta status: PENDING mode: USER connection: status: WAITING_QR loginUrl: tg://login?token=... expiresSeconds: 30 base64: data:image/png;base64,... shareableLink: hostedUrl: >- https://api.notifique.dev/w/instance-connect/...?token=... embedUrl: >- https://api.notifique.dev/w/embed/instance-connect/...?token=... publicId: ... code: TELEGRAM_USER_PENDING_SESSION '400': description: >- Dados inválidos, token de bot rejeitado ou falta de aceite nos termos no modo USER. content: application/json: schema: $ref: '#/components/schemas/NtfTg_ErrorResponse' examples: token: summary: Token do bot value: success: false error: Bad Request message: Invalid bot token or Telegram API error. code: TELEGRAM_BOT_TOKEN_INVALID terms: summary: Termos USER value: success: false error: Bad Request message: >- USER mode requires acceptUserTerms: true (risks of automation and ToS). code: TELEGRAM_USER_TERMS_REQUIRED '401': description: Chave ausente ou inválida. content: application/json: schema: $ref: '#/components/schemas/NtfTg_ErrorResponse' example: success: false error: Unauthorized message: Invalid or missing API Key code: UNAUTHORIZED '402': description: Workspace suspenso ou plano expirado. content: application/json: schema: $ref: '#/components/schemas/NtfTg_ErrorResponse' example: success: false error: Payment Required message: Plan expired or suspended code: WORKSPACE_BLOCKED '403': description: Sem escopo ou limite de instâncias do plano. content: application/json: schema: $ref: '#/components/schemas/NtfTg_ErrorResponse' examples: scope: value: success: false error: Forbidden message: 'Missing scope: telegram:instances:create' code: FORBIDDEN plan: value: success: false error: Plan limit reached message: Your plan allows up to 3 instance(s). code: PLAN_LIMIT_INSTANCES '503': description: Capacidade global de instâncias esgotada (limite da plataforma). content: application/json: schema: $ref: '#/components/schemas/NtfTg_ErrorResponse' example: success: false error: Instance capacity is currently full. message: Instance capacity is currently full. code: UNKNOWN_ERROR components: schemas: NtfTg_CreateTelegramInstanceRequest: type: object required: - name - mode properties: name: type: string minLength: 2 description: Nome para identificar esta conexão no painel. mode: type: string enum: - BOT - USER description: >- **`BOT`**: robô com token. **`USER`**: conta pessoal/profissional com login por QR. botToken: type: string description: Token do bot (obrigatório quando `mode` é BOT). acceptUserTerms: type: boolean description: >- Obrigatório `true` no modo USER — confirma que você entende as regras de automação. termsVersion: type: string maxLength: 32 description: >- Opcional. Rótulo da versão dos termos aceitos no modo **USER** (ex.: `2026-04` ou `v2`), usado só para registro e auditoria. Se omitido, o servidor grava um valor padrão (`v1`). Não altera o funcionamento da API. generateShareableLink: type: boolean default: false description: >- Gera um link para outra pessoa concluir o login. Omita para receber o QR na resposta. NtfTg_CreateTelegramInstanceResponse: type: object properties: success: type: boolean data: type: object properties: id: type: string name: type: string status: type: string mode: type: string botUsername: type: string nullable: true webhookUrl: type: string description: Presente no modo BOT message: type: string description: Instruções no modo USER code: type: string NtfTg_ErrorResponse: type: object properties: success: type: boolean example: false error: type: string description: 'Rótulo HTTP do erro (ex.: Unauthorized, Bad Request, Not Found).' message: type: string description: >- Mensagem legível para exibir ao usuário (localizada via Accept-Language / x-locale quando aplicável). code: type: string description: >- Código estável da API v1 (enum). Sempre presente em erros. Use com o status HTTP para decidir retry ou correção. Ver [Respostas de erro](/guides/conceitos/resposta-de-erros). details: type: array items: type: object properties: field: type: string message: type: string required: - success - error - message - code securitySchemes: ntfTgBearerAuth: type: http scheme: bearer bearerFormat: API Key description: 'Authorization: Bearer sk_live_xxxxx' ntfTgApiKeyHeader: type: apiKey in: header name: x-api-key ````