Telegram Bot API — APIFacil

PRO

Por que Telegram

Vantagens do canal Telegram

O Telegram Bot API é a integração oficial do Telegram para bots. Você cria um bot via @BotFather, conecta na APIFacil e passa a enviar/receber mensagens via API HTTP — igual ao WhatsApp, mas sem risco de banimento.

SEM BANIMENTO

Bots oficiais — rate limits respeitados automaticamente

GRUPOS E CANAIS

Suportados nativamente (chat_id negativo)

SEM TELEFONE

Identificação por chat_id numérico

TEXTO LIVRE

Sem templates HSM — mensagens sem aprovação prévia

MÍDIA COMPLETA

Imagem, áudio, vídeo, documento, localização

BOTÕES INLINE

inline_keyboard com callback_data

Como funciona: Você cria um bot no @BotFather (dentro do Telegram), recebe um bot_token, cola no painel da APIFacil e configura o webhook. A APIFacil guarda o token criptografado e gerencia o webhook automaticamente.

AUTH

Autenticação

Todas as rotas usam o mesmo token da APIFacil no header Authorization: {seu_token} (sem prefixo "Bearer "). O token é gerado no painel do usuário. A APIFacil autentica você no Telegram internamente — você não precisa enviar o bot_token na API.

BASH

# Header correto: Authorization + token direto (SEM "Bearer")
curl -X POST https://apifacil.dev/api/v1/whatsapp/enviar-mensagem \
  -H "Authorization: SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"mensagem":"Olá","telefone":"123456789","instancia":"10"}'

Importante: O campo telefone na API é usado como chat_id para Telegram. Envie o chat_id numérico (ex: 123456789 para privado, -1001234567890 para grupo/canal).

Identificador da instância: O campo instancia aceita o ID, código ou public_token da instância Telegram. O roteamento é automático pelo tipo_conexao=telegram.

FLOW

Como o envio funciona

Fluxo de roteamento

1

Requisição HTTP
POST /api/v1/whatsapp/enviar-mensagem

→

2

Roteia por tipo_conexao
telegram → TelegramMessageSender

→

3

Anti-spam Redis
1/s por chat, 20/min por grupo

→

4

Telegram Bot API
POST api.telegram.org/bot<token>/sendMessage

→

5

Job async + webhook status
sent/delivered/read

O RoteiaEnvioPorTipo trait identifica que a instância é Telegram e despacha para o SendTelegramMessageJob na fila telegram_messages. O job respeita os rate limits e re-enfileira com Retry-After em caso de HTTP 429.

BOT

Criar o bot no BotFather

Passo a passo no Telegram

O BotFather é o bot oficial do Telegram que cria e gerencia bots. Todo bot Telegram nasce aqui. O processo leva menos de 2 minutos e é gratuito.

Passo a passo (conversa com @BotFather):

BotFather

VOCÊ: Abra o Telegram e busque por @BotFather

VOCÊ: Toque em /start para iniciar o BotFather

VOCÊ: Envie /newbot para criar um novo bot

BOTFATHER: "Alright, a new bot. How are we going to call it? Please choose a name for your bot."

VOCÊ: Digite o nome do bot (ex: APIFacil Suporte Bot) — é o nome que aparece no perfil

BOTFATHER: "Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot."

VOCÊ: Digite o username (ex: apifacil_suporte_bot) — deve ser único e terminar com bot

BOTFATHER: "Done! Congratulations on your new bot. You will find it at t.me/apifacil_suporte_bot. [...] Use this token to access the HTTP API:" 123456789:AAH_DUMMY_TOKEN_REPLACE_WITH_REAL_ONE_xyz

BOTFATHER: "Keep your token secure and store it safely, it can be used by anyone to control your bot."

Pronto! Você tem o bot_token. Guarde com segurança — ele dá controle total do bot. Cole no painel da APIFacil na aba "Telegram" da instância.

CMD

Comandos do BotFather

Configurações opcionais

Além de criar o bot, o BotFather permite configurar opções úteis:

COMANDO	O QUE FAZ	RECOMENDADO
/newbot	Cria um novo bot	SIM — obrigatório
/setname	Altera o nome de exibição	Opcional
/setdescription	Descrição do bot (perfil)	SIM
/setabouttext	Sobre o bot (texto curto)	SIM
/setuserpic	Foto de perfil do bot	SIM
/setcommands	Lista de comandos do bot (menu)	SIM — ex: /start, /ajuda
/token	Gera um novo token (revoga o anterior)	Só se comprometer
/revoke	Revoga o token atual e gera novo	Só se comprometer
/deletebot	Remove o bot permanentemente	Cuidado

Exemplo de comandos (para /setcommands):

start - Iniciar conversa
ajuda - Mostrar ajuda
status - Verificar status do bot

KEY

O bot_token

Formato e segurança

O bot_token é a chave completa de acesso ao bot. Quem tiver o token pode enviar e receber mensagens em nome do bot. Nunca faça commit no git, não cole em chat público e não exponha no frontend.

FORMATO

123456789:AAH_DUMMY_TOKEN_REPLACE_WITH_REAL_ONE_xyz
# [bot_id]:[35-40 caracteres alfanuméricos e _-]
# O número antes dos : é o bot_id
# A parte depois dos : é o segredo

Na APIFacil: O bot_token é criptografado com Laravel Crypt (AES-256) antes de ser salvo no banco. Nunca é retornado em endpoints da API. O painel mostra apenas bot_username e status.

Se comprometer o token: Abra o @BotFather → /revoke → ele gera um novo token e invalida o antigo. Depois cole o novo no painel da APIFacil.

PAIN

Configurar no painel APIFacil

Após ter o bot_token

1

Criar instância
Tipo: Telegram

→

2

Aba Telegram
Painel › WhatsApp › [instância] › Telegram

→

3

Colar bot_token
Clica em "Conectar Bot"

→

4

Configurar webhook
Clica em "Configurar Webhook"

→

5

Bot operacional
status=connected

Ao colar o token e clicar "Conectar Bot", o painel chama getMe na API do Telegram para validar. Se o token for válido, salva bot_id, bot_username e bot_first_name automaticamente.

Ao clicar "Configurar Webhook", o painel gera um secret_token aleatório (32 chars) e chama setWebhook no Telegram com a URL https://apifacil.dev/api/v1/telegram/webhook/{credencial_id}. O Telegram passa a enviar updates para esta URL.

Pronto para usar! O bot agora recebe mensagens (via webhook) e envia via API. Teste enviando /start para o bot no Telegram — o webhook será disparado.

POST

Envio de Mensagens

Endpoints da API

POST /api/v1/whatsapp/enviar-mensagem Enviar texto ▶

Envia uma mensagem de texto para um chat (privado, grupo ou canal). Para Telegram, o campo telefone é o chat_id.

PARÂMETRO	TIPO	OBRIG	DESCRIÇÃO
mensagem	string	SIM	Texto da mensagem (máx 4096 chars)
telefone	string	SIM	chat_id numérico (ex: 123456789 ou -1001234567890 para grupo)
instancia	string	SIM	ID/código/public_token da instância Telegram

BASH

# Enviar mensagem de texto para chat privado
curl -X POST https://apifacil.dev/api/v1/whatsapp/enviar-mensagem \
  -H "Authorization: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mensagem":"Olá do Telegram!","telefone":"123456789","instancia":"10"}'

200 OK Mensagem enfileirada para envio

JSON
{
  "error": false,
  "message": "Mensagem enfileirada",
  "message_id": "msg_abc123"
}

POST /api/v1/whatsapp/enviar-foto Enviar imagem (URL) ▶

Envia uma imagem via URL. O Telegram baixa a imagem do URL e envia como photo.

PARÂMETRO	TIPO	OBRIG	DESCRIÇÃO
url	string	SIM	URL da imagem (HTTPS)
telefone	string	SIM	chat_id
instancia	string	SIM	ID da instância
caption	string	NÃO	Legenda da imagem (máx 1024 chars)

BASH

curl -X POST https://apifacil.dev/api/v1/whatsapp/enviar-foto \
  -H "Authorization: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://exemplo.com/foto.jpg","telefone":"123456789","instancia":"10","caption":"Nova foto"}'

POST /api/v1/whatsapp/enviar-arquivo Enviar documento (URL) ▶

Envia um arquivo qualquer (PDF, DOCX, ZIP, etc) via URL.

PARÂMETRO	TIPO	OBRIG	DESCRIÇÃO
url	string	SIM	URL do arquivo (HTTPS)
telefone	string	SIM	chat_id
instancia	string	SIM	ID da instância
caption	string	NÃO	Legenda do arquivo

POST /api/v1/whatsapp/enviar-audio Enviar áudio (URL) ▶

Envia um arquivo de áudio via URL. O Telegram envia como audio (reprodutor nativo).

POST /api/v1/whatsapp/enviar-video Enviar vídeo (URL) ▶

Envia um vídeo via URL. Suporta mp4 e formatos comuns.

POST

Enviar com Botões

POST /api/v1/whatsapp/enviar-botao Botões inline (callback) ▶

Envia mensagem com botões inline. Quando o usuário toca, o Telegram dispara um callback_query no webhook com o callback_data.

PARÂMETRO	TIPO	OBRIG	DESCRIÇÃO
mensagem	string	SIM	Texto acima dos botões
botoes	array	SIM	Array de botões [{id, texto}]
telefone	string	SIM	chat_id
instancia	string	SIM	ID da instância

BASH

curl -X POST https://apifacil.dev/api/v1/whatsapp/enviar-botao \
  -H "Authorization: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mensagem":"Escolha uma opção:",
    "botoes":[
      {"id":"sim","texto":"Sim, quero"},
      {"id":"nao","texto":"Não, obrigado"}
    ],
    "telefone":"123456789",
    "instancia":"10"
  }'

Quando o usuário toca em um botão, o webhook recebe tipo: "interactive" com interacao.tipo: "button_reply" e interacao.id: "sim" (o callback_data).

POST

Enviar Localização

POST /api/v1/whatsapp/enviar-localizacao Latitude + longitude ▶

Envia um ponto no mapa (latitude e longitude) para o chat.

PARÂMETRO	TIPO	OBRIG	DESCRIÇÃO
lat	float	SIM	Latitude (-90 a 90)
lng	float	SIM	Longitude (-180 a 180)
telefone	string	SIM	chat_id
instancia	string	SIM	ID da instância

TIP

Tipos de Mensagem

TIPO	ENDPOINT	FORMATO TELEGRAM
Texto	enviar-mensagem	sendMessage
Imagem	enviar-foto	sendPhoto (URL)
Documento	enviar-arquivo	sendDocument (URL)
Áudio	enviar-audio	sendAudio (URL)
Vídeo	enviar-video	sendVideo (URL)
Botões	enviar-botao	sendMessage + inline_keyboard
Localização	enviar-localizacao	sendLocation

HOOK

Webhook de Eventos

Mensagens recebidas + status

Quando o Telegram envia um update (mensagem recebida, callback de botão, status), a APIFacil processa e encaminha para o webhook do cliente (configurado no painel) no formato universal — mesmo formato da Meta Cloud API, com o campo extra chat_id.

Importante: O webhook do cliente é diferente do webhook do Telegram. O Telegram envia para /api/v1/telegram/webhook/{credencial_id} (validado por secret_token). A APIFacil processa e reenvia para a URL do cliente no formato universal.

JSON

Formato do Payload (Universal)

Igual ao Meta, com chat_id extra

JSON · MENSAGEM RECEBIDA
{
  "evento": "received",
  "instancia": "abcd-1234-efgh",
  "message_id": "tg_12345",
  "tipo": "text",
  "de": "987654321",
  "para": "123456789",
  "chat_id": "987654321",
  "contato": "João",
  "texto": "Olá, tudo bem?",
  "timestamp": "2026-08-05T10:30:00Z"
}

JSON · STATUS DE ENVIO
{
  "evento": "status",
  "instancia": "abcd-1234-efgh",
  "message_id": "msg_abc123",
  "status": "delivered",
  "chat_id": "987654321",
  "timestamp": "2026-08-05T10:30:01Z"
}

CAMPO	TIPO	EVENTO	DESCRIÇÃO
evento	string	ambos	received ou status
instancia	string	ambos	Código UUID da instância
message_id	string	ambos	ID da mensagem no Telegram
tipo	string	received	text, image, audio, video, document, sticker, location, interactive
de	string	received	chat_id de origem (quem enviou)
para	string	ambos	bot_id (seu bot)
chat_id	string	ambos	Telegram extra — chat_id numérico
contato	string	received	Nome do remetente (first_name do Telegram)
texto	string	received	Conteúdo textual ou caption da mídia
midia	object	received	Dados da mídia (file_id, mime_type, nome, tamanho, url)
localizacao	object	received	latitude, longitude
interacao	object	received	tipo: button_reply, id (callback_data)
status	string	status	sent, delivered, read, failed
erro	object	status	código, detalhe (quando status=failed)
timestamp	string	ambos	ISO 8601

Compatibilidade: O formato é idêntico ao da Meta Cloud API. Se você já integra com o webhook da APIFacil para WhatsApp, não precisa mudar nada — basta tratar o campo extra chat_id.

SEC

Validação secret_token

Segurança do webhook Telegram

O Telegram envia um header X-Telegram-Bot-Api-Secret-Token em cada update. A APIFacil compara com o secret_token gerado no setWebhook usando hash_equals (timing-safe). Se não bater, retorna 401 e o update é descartado.

VALIDAÇÃO
# Header enviado pelo Telegram
X-Telegram-Bot-Api-Secret-Token: aB3xY9kL2mN7pQ4rS6tU8vW0xZ1aB3cD

# Se não bater com o secret_token da credencial → HTTP 401
# Se a credencial não tem secret_token configurado → HTTP 401
# Se o credencial_id na URL não existe → HTTP 200 (silencioso)

Ports suportadas: O Telegram só aceita webhooks nas ports 443, 80, 88, 8443. A APIFacil usa 443 (HTTPS padrão).

LIM

Rate Limits (Anti-Spam)

Controlados automaticamente

LIMITE	VALOR	ESCOPO	AO EXCEDER
Por chat	1 msg/s	Cada conversa privada	Pausa de 1s
Por grupo	20 msg/min	Cada grupo/canal	Pausa até próximo minuto
Global	30 msg/s	Por bot (todas as conversas)	Pausa de 1s

Retry-After (HTTP 429): Se o Telegram retornar 429 com retry_after, o job é re-enfileirado com release($retryAfter + 1) segundos. O envio não é perdido — é apenas postergado.

Tudo automático via TelegramAntiSpamService (Redis). Você não precisa gerenciar rate limits no seu código.

GRP

Grupos e Canais

No Telegram, grupos e canais têm chat_id negativo (ex: -1001234567890). Chats privados têm chat_id positivo. A APIFacil identifica grupos automaticamente pelo sinal do número.

TIPO	CHAT_ID	RATE LIMIT
Chat privado	123456789	1 msg/s
Grupo	-1001234567890	20 msg/min
Canal	-1001234567891	20 msg/min

Para o bot funcionar em grupos, ele precisa ser adicionado como membro do grupo (ou administrador para canais). Sem permissão, o Telegram retorna 403.

DIF

Telegram vs Meta (WhatsApp)

Diferenças principais

ASPECTO	META (WHATSAPP)	TELEGRAM
Identidade	Telefone (5511999999999)	chat_id numérico
Grupos	@g.us no ID	chat_id negativo
Validação webhook	HMAC SHA-256	secret_token header
Rate limit	80 req/s por credencial	1/chat/s, 20/grupo/min, 30/global
Templates HSM	Sim (aprovados pela Meta)	Não (texto livre)
Janela 24h	Sim (Customer Care Window)	Não (sem limite de janela)
Mídia download	Graph API + URL	getFile + URL (bot API)
Mídia upload	URL ou upload direto	URL (sendPhoto por URL)
Botões	interactive (button/list)	inline_keyboard (callback)
Banimento	Sim (se violar política)	Não (bot oficial)
Onboarding	Wizard OAuth (5 etapas)	BotFather + colar token

CLI

Comandos Artisan

Gestão via terminal

BASH

# Configurar webhook (gera secret_token automaticamente)
php artisan telegram:set-webhook --credencial=1

# Remover webhook (para de receber updates)
php artisan telegram:delete-webhook --credencial=1

# Verificar info do bot (getMe + getWebhookInfo)
php artisan telegram:get-info --credencial=1

# Especificar URL base personalizada
php artisan telegram:set-webhook --credencial=1 --url=https://meu-dominio.com

# Usar secret_token personalizado
php artisan telegram:set-webhook --credencial=1 --secret=meu_secret_123

ERR

Erros Comuns

STATUS	CÓDIGO	CAUSA	SOLUÇÃO
401	token invalido	Token da APIFacil errado ou com Bearer	Remover "Bearer ", usar token do painel
404	instância não encontrada	ID/código não pertence ao usuário	Verificar o ID no painel
422	não é Telegram	Instância não é tipo Telegram	Verificar tipo_conexao no painel
422	credencial não ativa	Bot não conectado ou sem webhook	Colar bot_token e configurar webhook no painel
429	rate limit	Mais de 1/s por chat ou 30/s global	A APIFacil controla automaticamente (Retry-After)
403	bot sem permissão	Bot não foi adicionado ao grupo/canal	Adicionar o bot como membro do grupo
400	chat não encontrado	chat_id inválido ou usuário não iniciou conversa	Usuário deve enviar /start para o bot primeiro
400	token invalido (Telegram)	bot_token incorreto ou revogado	Verificar token no BotFather, usar /token para gerar novo
500	falha Bot API	Telegram rejeitou o envio	Verificar chat_id e se o bot tem permissão

Usuário precisa iniciar a conversa: Um bot Telegram não pode enviar mensagem primeiro para um usuário. O usuário deve enviar /start (ou qualquer mensagem) para o bot — a partir daí o bot pode responder a qualquer momento.

Suporte: Qualquer duvida, chame no WhatsApp 55 51 9 8033-1519.