> ## 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. # Crear instância Telegram > Conecta una cuenta de Telegram a su workspace — el canal por donde entran y salen los mensajes. Elija el ejemplo: - **Bot con token** — robot automatizado (@BotFather). - **Cuenta de usuario: QR en su pantalla** — usted muestra el código e inicia sesión al momento. - **Cuenta de usuario: enlace para el cliente** — envía un enlace; la persona termina el login en su Telegram. Ámbito: **telegram:instances:create**. ## OpenAPI ````yaml /es/telegram-api/api-reference/openapi-telegram.json post /v1/telegram/instances openapi: 3.0.3 info: title: Notifique API — Telegram description: >- Envíe mensajes de Telegram y gestione conexiones. Autentíquese con `Authorization: Bearer sk_live_...` o `x-api-key`. version: 1.0.0 servers: - url: https://api.notifique.dev description: Producción security: - ntfTgBearerAuth: [] - ntfTgApiKeyHeader: [] tags: - name: Mensajes description: Enviar y gestionar mensajes - name: Instancias description: Crear y conectar bots o cuentas USER - name: Chats description: Listar chats paths: /v1/telegram/instances: post: tags: - Instâncias summary: Crear instância Telegram description: >- Conecta una cuenta de Telegram a su workspace — el canal por donde entran y salen los mensajes. Elija el ejemplo: - **Bot con token** — robot automatizado (@BotFather). - **Cuenta de usuario: QR en su pantalla** — usted muestra el código e inicia sesión al momento. - **Cuenta de usuario: enlace para el cliente** — envía un enlace; la persona termina el login en su Telegram. Ámbito: **telegram:instances:create**. operationId: ntfTg_postV1TelegramInstances requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NtfTg_CreateTelegramInstanceRequest' examples: botWithToken: summary: Bot con token description: Bot de Telegram — pegue el token de @BotFather. value: name: Atención mode: BOT botToken: 123456:ABC-DEF userQrOnYourScreen: summary: 'Cuenta de usuario: QR en su pantalla' description: Usted muestra el QR en su interfaz; el login debe hacerse ahí. value: name: Mi cuenta TG mode: USER acceptUserTerms: true userLinkForCustomer: summary: 'Cuenta de usuario: enlace para el cliente' description: >- Envíe el enlace para que otra persona termine el login en Telegram. value: name: Atención TG mode: USER acceptUserTerms: true generateShareableLink: true responses: '200': description: >- Cuenta registrada. El bot queda **ACTIVE** con `webhookUrl`. La cuenta de usuario suele quedar **PENDING** hasta completar el login (QR o enlace). 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 instancias 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 instancias 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: Nombre para identificar esta conexión en el panel. mode: type: string enum: - BOT - USER description: >- **`BOT`**: bot con token. **`USER`**: cuenta personal/pro con login por QR. botToken: type: string description: Token del bot (obligatorio cuando `mode` es BOT). acceptUserTerms: type: boolean description: >- Obligatorio `true` en modo USER — confirma que entiende las reglas de automatización. 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`). No altera o funcionamento da API. generateShareableLink: type: boolean default: false description: >- Devuelve un enlace para que otra persona termine el login. Omita para recibir el QR en la respuesta. 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: >- Mensaje 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 [Respuestas 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 ````