> ## 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.

# Alcances clave API

> Qué permisos necesita su clave para conectarse, enviar y administrar Telegram en Notifique.

<Tip>
  La **clave API** es su tarjeta de acceso: cada **alcance** abre una puerta. En producción, conceda solo lo que su integración necesita.
</Tip>

## En breve

* Los alcances `telegram:*` cubren instancias, envío, lectura y edición.
* **`instanceIds`** restringe **qué conexiones** puede utilizar la clave.
* Guía general: [Claves API](/es/guides/api-key/index). Conexión: [Inicio rápido](/es/telegram-api/como-funciona/quick-start).

***

## Cómo enviar la clave

```http theme={null}
Authorization: Bearer sk_live_xxxxx
```

Alternativa: `x-api-key: sk_live_xxxxx`.

<Warning>
  Alcances **vacíos** al crear = acceso **ADMIN** (todo). En producción, restrinja siempre.
</Warning>

***

## Combinaciones listas

<CardGroup cols={2}>
  <Card title="Bot básico" icon="robot">
    `telegram:instances:create`, `telegram:instances:list`, `telegram:send`
  </Card>

  <Card title="Enviar y consultar" icon="magnifying-glass">
    `telegram:send`, `telegram:read`
  </Card>

  <Card title="Con cancelación" icon="clock">
    `telegram:send`, `telegram:cancel`
  </Card>

  <Card title="Flujo completo" icon="list-check">
    `telegram:send`, `telegram:read`, `telegram:cancel`, `telegram:update`, `telegram:delete`
  </Card>
</CardGroup>

***

## Alcances disponibles

<AccordionGroup>
  <Accordion title="telegram:instances:list">
    Listar conexiones, ver detalles y QR (modo USER).
  </Accordion>

  <Accordion title="telegram:instances:create">
    Crear bot con token o iniciar cuenta USER (QR o sesión).
  </Accordion>

  <Accordion title="telegram:instances:delete">
    Eliminar conexión.
  </Accordion>

  <Accordion title="telegram:send">
    Enviar texto, medios vía URL HTTPS y ubicación (modo bot).
  </Accordion>

  <Accordion title="telegram:read">
    Historial de enviados, lista de chats e inbound.
  </Accordion>

  <Accordion title="telegram:cancel">
    Cancelar mensaje en cola o programado.
  </Accordion>

  <Accordion title="telegram:update">
    Editar texto enviado.
  </Accordion>

  <Accordion title="telegram:delete">
    Eliminar mensaje en el chat.
  </Accordion>
</AccordionGroup>

***

## Restringir por conexión (`instanceIds`)

Además del alcance (el **qué**), `instanceIds` define **dónde**:

| Situación                            | Resultado                                                 |
| ------------------------------------ | --------------------------------------------------------- |
| Envío en instancia fuera de la lista | **403**                                                   |
| Lista vacía / omitida                | Todas las instancias del espacio de trabajo (con alcance) |

***

## Errores comunes

| HTTP / `code`                            | Qué hacer                                  |
| ---------------------------------------- | ------------------------------------------ |
| **401** `UNAUTHORIZED`                   | Verifique `Authorization: Bearer sk_...`   |
| **403** alcance ausente                  | Agregue el alcance de la ruta a la clave   |
| **403** instancia fuera de `instanceIds` | Ajuste la lista en la clave                |
| `TELEGRAM_BOT_TOKEN_INVALID`             | Token BotFather inválido al crear          |
| `TELEGRAM_USER_TERMS_REQUIRED`           | Modo USER requiere `acceptUserTerms: true` |

Catálogo completo: [Respuestas de error](/es/guides/conceitos/resposta-de-erros).

***

## Próximos pasos

* [Inicio rápido](/es/telegram-api/como-funciona/quick-start)
* [Eventos webhook](/es/telegram-api/como-funciona/eventos-do-webhooks)
* [Modos de conexión](/es/telegram-api/como-funciona/modos-de-conexao)