> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octasend.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Telegram
> Conecte seus bots do Telegram, vincule as pessoas, atenda em Conversas e em grupos e envie pela API
O canal Telegram funciona por um **bot seu**, criado no BotFather. Com ele você atende as conversas na inbox **Conversas**, responde com o [chatbot](https://docs.octasend.com.br/plataforma/chatbot.md), participa de **grupos** e envia comunicações pela API.
O Telegram não deixa encontrar uma pessoa pelo telefone, e um bot só consegue escrever para quem já iniciou uma conversa com ele. Por isso o envio usa um destes identificadores:
* o **chat ID** da pessoa, se você já o conhece;
* o **identificador dela no seu sistema** (`user_id`) ou o **telefone**, depois que ela se vincula pelo bot (seção 3, abaixo).
## 1. Criar o bot
Abra uma conversa com o [@BotFather](https://t.me/BotFather) no Telegram, envie `/newbot` e siga as instruções para dar nome e username ao bot. Copie o token gerado (formato `123456789:AABBcc...`).
> [!WARNING]
>
> Quem tem o token controla o bot. Nunca exponha o token no código do seu site.
## 2. Conectar o bot na plataforma
Em **Configurações → Canais → Telegram**, clique em **Adicionar bot** e preencha:
| Campo | Obrigatório | Descrição |
| - | - | - |
| Token do bot | Sim | Token copiado do BotFather |
| Mensagem de boas-vindas | Não | Texto que o bot envia depois que a pessoa confirma o telefone. Em branco, vale a mensagem padrão: *Número confirmado! Pode mandar sua mensagem.* (até 1.000 caracteres) |
Clique em **Conectar bot**. A plataforma confere o token no Telegram e registra o webhook sozinha: não há passo manual. O bot aparece na lista com o nome (`@usuario`), o estado e o chatbot vinculado.
Você pode conectar **vários bots**. Um deles é o **Padrão para disparos**: é por ele que saem as comunicações, quando a pessoa confirmou o telefone nesse bot (se não, saem pelo bot em que ela confirmou). Use **Tornar padrão** para trocar.
Ações de cada bot:
* **Testar** — confere o token e registra o webhook de novo. Use quando o bot parar de responder (o estado mostra **Precisa testar**).
* **Tornar padrão** — define o bot dos disparos.
* **Editar boas-vindas** — troca a mensagem enviada quando a pessoa confirma o telefone.
* **Remover** — o bot para de receber mensagens e quem estava inscrito nele deixa de receber disparos. As conversas continuam salvas.
> [!WARNING]
>
> Não registre o webhook manualmente (por exemplo, chamando `setWebhook` com `curl`): o registro manual não leva a chave de segurança, e as mensagens do bot são recusadas.
> [!NOTE]
>
> Trocou ou revogou o token no BotFather? Use **Adicionar bot** com o token novo: o bot é atualizado e mantém os inscritos e o chatbot.
### Já usava o Telegram antes?
Quem tinha o canal configurado na versão anterior não precisa refazer nada: ao abrir **Configurações → Canais → Telegram** pela primeira vez, o seu bot antigo é trazido para a lista automaticamente, com o aviso **Seu bot do Telegram foi trazido para esta página.** Os inscritos continuam valendo. Se a tela avisar **Não foi possível trazer seu bot antigo do Telegram**, use **Adicionar bot** com o token do BotFather.
A importação só roda para usuários com permissão de editar canais.
## 3. Vincular as pessoas ao bot
Coloque no seu site um link que abra o bot, com o identificador da pessoa no seu sistema:
```html theme={null}
Ativar notificações pelo Telegram
```
Quando a pessoa abre o link e inicia a conversa com o bot:
1. O bot guarda o vínculo entre o `ID_DO_USUARIO` e o chat dela.
2. O bot pede o telefone, com o botão **Compartilhar meu número**.
3. Quando ela compartilha, o bot guarda o vínculo entre o telefone e o chat e responde com a **Mensagem de boas-vindas**.
Se a pessoa escrever qualquer outra coisa antes de compartilhar o número, o bot mostra o botão de novo. Sem o link com `?start=`, a pessoa pode abrir só `https://t.me/SEU_BOT`: nesse caso só o telefone fica vinculado e a conversa aparece em Conversas.
> [!NOTE]
>
> O Telegram só aceita no `start` letras, números, `_` e `-`, com até 64 caracteres. Use um identificador nesse formato.
## 4. Atender na inbox Conversas
As conversas individuais com o bot aparecem em **Conversas**, junto com as dos outros canais (o filtro de canal mostra só o Telegram). A conversa só aparece depois que a pessoa **confirma o telefone**:
1. A pessoa abre o bot (`https://t.me/SEU_BOT`) e envia `/start`.
2. O bot pede o telefone, com o botão **Compartilhar meu número**. Antes disso, nada é gravado em Conversas.
3. Ao compartilhar, a plataforma cria ou encontra o contato em [Contatos](https://docs.octasend.com.br/plataforma/contatos.md) pelo telefone, o bot envia a mensagem de boas-vindas e a conversa passa a aparecer.
O telefone é obrigatório. Um cartão de contato de outra pessoa é ignorado: só vale o número do próprio remetente.
O que chega em Conversas: texto, foto, áudio e nota de voz, vídeo, documento, figurinha, localização e contato. Mídia até 15 MB é guardada; acima disso, a conversa avisa que o arquivo é grande demais. Toques em botões inline entram como mensagem interativa. O Telegram não envia confirmação de entrega nem de leitura a bots: a mensagem enviada fica como **Enviada**.
Abas, **Assumir**, **Atribuir a…**, **Devolver ao bot**, **Resolver**, respostas prontas e vínculo com contato funcionam como descrito em [Instagram e Messenger](https://docs.octasend.com.br/guias/instagram-messenger.md#atender-na-inbox-conversas). No Telegram **não há prazo para responder**: você e o bot respondem a qualquer momento. A resposta aceita texto e anexo (imagem, áudio, vídeo ou arquivo). Se a pessoa bloqueou o bot, a mensagem falha e a conversa avisa. Se o bot estiver desconectado, o campo de mensagem avisa **O bot do Telegram está desconectado. Teste o bot em Canais > Telegram.**
### Responder com o chatbot
1. Abra o bot em **Chatbot** e vá ao campo **Canais atendidos**.
2. Marque o bot do Telegram que ele deve atender e salve.
O chatbot responde sozinho enquanto a conversa não tem atendente, como nos outros canais. **Nos grupos o chatbot não responde** (veja abaixo).
## 5. Grupos do Telegram
O mesmo bot pode ficar em **grupos** do Telegram. As mensagens dos grupos aparecem em **Conversas → Grupos**, no seletor **Telegram** (quando você também usa grupos de WhatsApp, o seletor alterna entre os dois). O chatbot **não responde em grupos**: o bot só registra as mensagens e envia o que a sua equipe escreve.
**1. Adicione o bot ao grupo**
No Telegram, adicione o bot ao grupo como qualquer participante.
**2. Mande uma mensagem no grupo**
O grupo aparece sozinho na lista de **Conversas → Grupos**. Não existe "Sincronizar": o Telegram não deixa o bot listar os grupos em que está. Grupos em que o bot já estava aparecem na primeira mensagem nova.
Com mais de um bot conectado, um seletor no topo escolhe de qual bot são os grupos.
> [!WARNING]
>
> Por padrão, o Telegram entrega ao bot só comandos, respostas a ele e menções nos grupos. Se a tela mostrar **O bot só recebe menções e respostas nos grupos**, abra o @BotFather, envie `/setprivacy`, escolha o bot e **Disable**; depois adicione o bot de novo aos grupos e clique em **Testar** no bot, em **Configurações → Canais → Telegram**. Tornar o bot administrador do grupo também libera todas as mensagens daquele grupo, mas o aviso continua na tela.
Dentro do grupo, o painel tem as abas **Conversa** e **Participantes**:
* **Conversa** — histórico em tempo real. Você envia texto e mídia da biblioteca pelo bot. Mídia recebida até 20 MB aparece na conversa (limite do Telegram para bots).
* **Participantes** — total de membros, administradores e **quem já falou no grupo**. O Telegram não mostra ao bot a lista completa de membros.
Ações no topo do painel (cada uma depende da sua permissão):
| Ação | O que faz | Exige |
| - | - | - |
| **Editar grupo** | Troca o nome e a descrição do grupo | Bot **administrador** do grupo |
| **Link de convite** | Gera o link para copiar | Bot **administrador** do grupo |
| **Atualizar dados do grupo** | Lê de novo o nome, a descrição e o total de membros | — |
| **Tirar o bot do grupo** | O bot sai do grupo (pede confirmação) | — |
Se o bot for removido do grupo, o grupo fica marcado como **Inativo**, com o histórico preservado, e não dá para enviar. Se o Telegram recusar uma ação, a tela diz: **O bot precisa ser administrador do grupo para fazer isso.**, **O bot não está mais neste grupo.** ou **O Telegram limitou os envios. Tente de novo em N s.** Grupos comuns que viram supergrupos mantêm o histórico.
O que não existe: canais do Telegram (só grupos), criar grupos pelo painel e enviar campanha para grupos.
## 6. Criar o template
No template Telegram de cada [comunicação](https://docs.octasend.com.br/plataforma/comunicacoes.md):
* **Mensagem** — o texto que chega ao usuário, com variáveis `{{var}}`.
* **Formatação** — modo **Nenhum (texto puro)**, **HTML** (``, ``, ``, ``) ou **MarkdownV2**, e a opção de desativar a prévia de links.
* **Mídia (opcional)** — Foto, Vídeo, Documento, Áudio ou Animação (GIF), por URL. A mensagem vira a legenda, e a URL aceita variáveis.
* **Botões inline (opcional)** — organizados em linhas. Cada botão tem texto e **URL** *ou* `callback_data` — não os dois.
## 7. Enviar
Para enviar pela API, você precisa de um OAuth Client (o access token vem dele — veja [Autenticação](https://docs.octasend.com.br/api-reference/autenticacao.md)). Informe um destes campos em `recipient`:
| Campo | Quando usar |
| - | - |
| `telegram_chat_id` | Você já conhece o chat ID da pessoa |
| `user_id` | A pessoa abriu o link do bot com esse identificador |
| `phone` | A pessoa compartilhou esse número com o bot. Informe com o código do país (ex.: `+5511999998888`) |
Se vier mais de um, vale o primeiro da tabela.
```bash Por user_id theme={null}
curl -X POST https://api.octasend.com.br/functions/v1/send-message \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"communication_slug": "pedido-confirmado",
"recipient": { "user_id": "ID_DO_USUARIO" },
"channels": ["telegram"]
}'
```
```bash Por telefone theme={null}
curl -X POST https://api.octasend.com.br/functions/v1/send-message \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"communication_slug": "pedido-confirmado",
"recipient": { "phone": "+5511999998888" },
"channels": ["telegram"]
}'
```
```bash Por chat ID theme={null}
curl -X POST https://api.octasend.com.br/functions/v1/send-message \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"communication_slug": "pedido-confirmado",
"recipient": { "telegram_chat_id": "123456789" },
"channels": ["telegram"]
}'
```
* A escolha do bot é automática: primeiro o bot padrão em que a pessoa confirmou o telefone; se não, o bot mais recente em que ela se inscreveu.
* Telefone que ninguém compartilhou com o bot falha com *"Nenhum usuário Telegram encontrado com o telefone … O usuário precisa iniciar o bot e compartilhar o número primeiro."*
* `user_id` sem vínculo falha com *"No Telegram chat\_id found — provide recipient.phone, recipient.user\_id (registered via bot) or recipient.telegram\_chat\_id"*.
* Sem nenhum desses campos, o Telegram é pulado nessa chamada; se você pediu o canal explicitamente em `channels`, o resultado vem como `skipped`.
* [Campanhas](https://docs.octasend.com.br/plataforma/campanhas.md) encontram a pessoa pelo telefone do contato: só recebem os contatos que compartilharam esse número com o bot.
Veja todos os parâmetros em [Enviar Mensagens](https://docs.octasend.com.br/api-reference/enviar-mensagens.md).
## Checklist
* Bot adicionado em **Canais → Telegram** (token salvo e bot **Ativo**).
* Link do bot no seu site, e a pessoa abriu o bot e compartilhou o número (ou você tem o chat ID dela).
* Comunicação com template Telegram criado e mensagem preenchida.
* `send-message` retorna status `sent` e a mensagem chega no Telegram.
* Para atender em Conversas: a pessoa confirmou o telefone no bot.
* Para grupos: bot adicionado ao grupo e, se faltarem mensagens, privacidade do bot desativada no BotFather.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.