Crie já

API do Telegram Bot vs API do Telegram: Qual delas você precisa?

API do Bot do Telegram vs API do Telegram

API do Telegram Bot vs API do Telegram: Qual delas você precisa?

O API do bot do Telegram e o API do Telegram (também chamada de Telegram User API, construída sobre o MTProto) resolvem problemas diferentes. Uma executa uma conta de bot via HTTP. A outra executa uma conta de usuário real por meio de um protocolo binário que você mesmo implementa. Este guia detalha onde cada uma delas cria obstáculos, endpoint por endpoint, e quanto realmente custa construir e manter um cliente da API de Usuário do Telegram versus conectar uma conta existente através do Unipile.
Construir com Unipile
Veja a documentação

can-i-message-first.js
// Bot API: bloqueado, o usuário nunca enviou mensagem para o bot const res = await robô.sendMessage(userId, "Olá"); // -> 403 Proibido: o bot foi bloqueado pelo usuário ou nunca iniciou uma conversa // API de Usuário do Telegram via Unipile: funciona, é uma conta real // POST /v2/:account_id/chats/send const chat = await unipilar.bate-papos.create({ account_id: contaDoTelegramId, user_ids: [nome de usuário], text: "Olá" });
chat.status: "enviado"
Os dois modelos

API de Bot do Telegram vs API de Usuário do Telegram, em uma tabela

Se você já sabe que o Telegram tem várias APIs e só quer saber qual delas se aplica ao seu projeto, esta tabela leva você até lá em dez segundos. Se você ainda precisa do panorama completo de todas as três APIs do Telegram, leia o guia de introdução primeiro. Aqui, nós vamos um nível mais fundo nos dois que as pessoas realmente usam para construir: a Bot API e a Telegram User API.
CritériosAPI do bot do TelegramAPI de Usuário do Telegram (MTProto)
O que ele conectaUma conta de bot, criada e de propriedade do seu aplicativoUma conta real de usuário do Telegram, vinculada a número de telefone
ProtocoloHTTP padrão, solicitações e respostas em JSONMTProto, um protocolo binário personalizado que você implementa
CredenciaisUm token de bot emitido por @BotFatherapi_id + api_hash from my.telegram.org
Identidade nos chatsMostra um selo de "bot" visível, distinto de uma pessoaIndistinguível de uma pessoa usando o aplicativo
Quem pode enviar mensagens para quemO bot só pode responder uma vez que o usuário iniciar o chatA conta pode enviar mensagens para qualquer pessoa, como qualquer usuário do Telegram
Implementação típicaQualquer cliente HTTP, SDKs oficiais e da comunidadeTelethon, Pyrogram, GramJS, TDLib ou uma conta vinculada via Unipile
CustoGrátis para usarGratuito para uso, custo apenas de infraestrutura auto-hospedada
API do bot do Telegram
ConectaUma conta de robô
ProtocoloHTTP, JSON
CredenciaisToken do bot (BotFather)
IdentidadeDistintivo de bot visível
Quem pode enviar mensagensApenas usuários que enviaram mensagem primeiro
CustoGrátis
API de Usuário do Telegram (MTProto)
ConectaUma conta de usuário real
ProtocoloMTProto, binário
Credenciaisapi_id + api_hash
IdentidadeIndistinguiável de uma pessoa
Quem pode enviar mensagensQualquer pessoa, como um usuário normal
CustoGratuito, auto-hospedado, apenas o custo
Construa sua integração com o Telegram
A pergunta que decide

Para quem você quer escrever primeiro?

Todas as outras diferenças entre a API de Bots do Telegram e a API de Usuários do Telegram são secundárias em relação a esta. Responda a isso primeiro e o resto deste guia se tornará uma lista de verificação, não uma decisão.
Um bot não pode iniciar uma conversa com um usuário que nunca mandou uma mensagem para ele primeiro
Esta é uma regra da plataforma Telegram, não uma limitação da Unipile ou um bug de biblioteca. Uma conta de bot só pode responder dentro de um chat que o usuário já abriu, ou após o usuário tocar em um t.me deep link ou entra em um grupo em que o bot está. Se o seu caso de uso exige entrar em contato com alguém que ainda não interagiu com o seu bot, a API do Bot não é uma opção, não importa qual framework ou biblioteca esteja por cima dela.
A API do Bot funciona

O usuário fala com o seu bot primeiro

Bots de suporte, ferramentas orientadas por comandos, opt-ins de notificação, chatbots vinculados ao seu produto. O usuário encontra o seu bot, inicia o chat e tudo a partir daí é uma troca normal que a API do Bot gerencia bem.
API do bot bloqueada

Você precisa dar o primeiro passo

Prospecção de vendas, recrutamento, mensagens para clientes vinculadas a uma lista de contatos existente, ou qualquer fluxo de trabalho em que seu produto inicie contato com um usuário do Telegram. Isso requer uma conta de usuário real, o que significa a API de Usuário do Telegram (MTProto), e não a API de Bot.
Matriz de capacidade

O que realmente funciona, de endpoint a endpoint

Além da diferença no título, é aqui que cada opção limita você na prática. "Telegram User API (raw)" significa um cliente MTProto construído por você mesmo com uma biblioteca como Telethon, Pyrogram, GramJS ou TDLib. "Unipile" significa a mesma conta de usuário real, conectada sem que você precise escrever código MTProto.
CapacidadeAPI de BotAPI de Usuário do Telegram (bruta)Unipile
Olá! Como posso ajudar você hoje?NãoSim, sujeito às configurações de privacidade do usuárioSim, mesma regra de qualquer conta do Telegram
Enviar e receber mensagens de textoSim, nos chats dos quais o bot faz parteSimSim
Ler o histórico de mensagens de antes de o bot entrarNãoSimSim
Lista de participantes do grupo, adicionar, removerLimitado às próprias permissões do botSim, se você construirSim, getParticipantsList, addParticipant, removeParticipant
Administração de grupos: aprovar, promover, revogarSim, apenas se o bot for um administradorSim, se você construirNão suportado
Canais, comunidades, transmissõesSim, se adicionado como administradorSimNão suportado
Bate-papos secretosNão se aplicaSim, se você construirNão suportado
Contato, localização, enquete, anexos de eventosSimSimNão suportado
Chamadas de voz e vídeoNãoPossível, alto esforço de implementaçãoNão suportado
Tema do chat, arquivamento, exclusão do chatNão se aplicaSim, se você construirNão suportado
Identidade da contaSeparar a identidade do bot, selo visívelIdentidade de usuário real, vinculada a número de telefoneIdentidade de usuário real, sua conta existente
Gerenciamento de sessões e dispositivosBaseado em token, sem conceito de dispositivoVocê gerencia a chave de autenticação do MTProto e a verificação em duas etapas por conta própriaGerenciado através do recurso Aparelhos do próprio Telegram
Iniciar um chat frio
API de BotNão
API do Usuário (bruta)Sim, dependente de privacidade
UnipileSim
Histórico de mensagens antes de entrar
API de BotNão
API do Usuário (bruta)Sim
UnipileSim
Participantes do grupo (obter / adicionar / remover)
API de BotLimitado às permissões do bot
API do Usuário (bruta)Sim, autoconstruído
UnipileSim, endpoints dedicados
Administração do grupo
API de BotSim, se bot administrador
API do Usuário (bruta)Sim, autoconstruído
UnipileNão suportado
Canais, comunidades, transmissões
API de BotSim, como administrador
API do Usuário (bruta)Sim
UnipileNão suportado
Bate-papos secretos
API de BotNão se aplica
API do Usuário (bruta)Sim, autoconstruído
UnipileNão suportado
Anexos de contato / localização / enquete / evento
API de BotSim
API do Usuário (bruta)Sim
UnipileNão suportado
Chamadas de voz e vídeo
API de BotNão
API do Usuário (bruta)Possível, grande esforço
UnipileNão suportado
Gerenciamento de sessões / dispositivos
API de BotBaseado em token
API do Usuário (bruta)Chave de autenticação auto-gerenciada + 2FA
UnipileRecurso Dispositivos do próprio Telegram
O que o Unipile não cobre no Telegram
Canais, comunidades e transmissões, tema do chat, chats secretos, contato, localização, anexos de enquete e evento, administração de grupo (aprovar, promover, revogar), exclusão de chat, arquivamento e chamadas de voz ou vídeo. Se o seu projeto precisa de qualquer um destes, apenas um cliente da API de Usuário do Telegram construído por você mesmo cobre toda a superfície.
Construa com Unipile
O custo real

O custo real de construir sobre o MTProto

A API de Usuário do Telegram é gratuita, mas o "gratuito" cobre apenas a licença. Construir e manter um cliente da API de Usuário do Telegram por conta própria tem um custo de engenharia real que uma integração com a Bot API nunca tem. É assim que esse custo realmente se parece.
01

Gerenciamento de sessões e chaves de autenticação

O MTProto é um protocolo binário, não REST. Você implementa o esquema TL, a troca de chaves de autenticação e persiste a sessão resultante por conta própria. Perca a sessão e o usuário terá que se reautenticar do zero.
02

Autenticação de dois fatores

Contas com senha na nuvem exigem o tratamento do fluxo de 2FA baseado em SRP do Telegram durante o login. É mais uma máquina de estados para construir, testar e manter funcionando em cada atualização do protocolo do Telegram.
03

Um api_id por número de telefone

api_id e api_hash são emitidos em my.telegram.org em "ferramentas de desenvolvimento de API" e requerem uma conta ativa do Telegram. O Telegram permite uma única api_id por número de telefone, o que molda a forma como você provisiona credenciais de teste e de produção.
04

Contas sob observação automática

Clientes não oficiais são colocados sob observação automática pelo Telegram. Envio excessivo de mensagens (flooding), spam e inflação artificial de contadores podem desencadear um banimento permanente, o que significa que a limitação de taxa (rate limiting) e o aquecimento são de sua responsabilidade, e não um padrão da biblioteca.

shared-api-id-in-open-source.log
// Copiando e colando um api_id de amostra de um repositório de código aberto // em vez de registrar o seu próprio em my.telegram.org Erro: API_ID_PUBLISHED_FLOOD // Sinalizadores do Telegram api_id publicados em código público. Todo aplicativo que você lança precisa do seu próprio api_id / api_hash, // um por número de telefone, ou seus usuários finais encontrarão este erro.
Pule o trabalho de protocolo
Nada disso é necessário para conectar uma conta real do Telegram
O Unipile gerencia a sessão do MTProto, o fluxo de login e o ciclo de vida das credenciais para você. Você obtém uma conta real e humana do Telegram conectada ao seu produto sem precisar escrever um cliente do zero.
Comece a construir agora
A terceira via

Conectar uma conta existente, pular a compilação do MTProto

A maioria das equipes na verdade não quer construir um cliente do Telegram. Elas querem os recursos de uma conta de usuário real: iniciar conversas, ler o histórico completo, gerenciar participantes de grupos, sem precisar criar uma implementação de protocolo binário. É isso que o Unipile API do Telegram é para.
Conecte-se através do recurso de Dispositivos do próprio Telegram
O Unipile vincula uma conta de usuário existente do Telegram por meio da função Dispositivos do Telegram, o mesmo mecanismo que permite fazer login no Telegram Desktop ou Telegram Web. O login ocorre por código QR ou por Autenticação Hospedada (Hosted Auth) com provedores: "TELEGRAM" para um fluxo de conexão integrado.
Sem api_id, sem api_hash, sem MTProto para escrever
Você nunca lida com a troca de chave de autenticação, o esquema TL ou a 2FA por conta própria. A conta vinculada se comporta como um usuário real do Telegram porque ela é um, não um bot e não um cliente simulado.
Participantes do grupo, por meio de endpoints dedicados
obterListaDeParticipantes, adicionarParticipante, removerParticipante, exposto via POST, OBTERe DELETE /v2/{account_id}/chats/{chat_id}/participants. Nenhuma chamada MTProto personalizada para escrever para o gerenciamento básico de membros.
Status da sessão vinculado à lista de dispositivos do Telegram
Se o dispositivo Unipile for removido das sessões ativas da conta dentro do Telegram, o status da conta muda para desconectado. O ciclo de vida da sessão é visível e previsível, não uma caixa preta que você depura sozinho.
Construa seu recurso do Telegram
Explore a API do Telegram

conectar-conta-telegram.js
Conectar uma conta de usuário existente do Telegram // via Hosted Auth, nenhum código MTProto necessário const link = await unipilar.Autenticação Hospedada.create({ provedores ["TELEGRAMA"], expiraEm: "2026-12-31T23:59:59.000Z" }); // O usuário escaneia o código QR com o aplicativo Telegram // O status da conta torna-se "conectado" // GET /v2/{account_id}/chats/{chat_id}/participants const membros = await unipilar.bate-papos.obterListaDeParticipantes(ID do chat);
conta.status: "conectado"
Mesmas regras, sem atalhos para contorná-las
Uma conta vinculada ainda é uma conta do Telegram e segue os limites do próprio Telegram: evite contas novinhas em folha para uso intenso, aumente o volume progressivamente e mantenha pelo menos 10 a 20 segundos entre as mensagens. Veja o Guia da API do Telegram e o guia de envio de mensagens para a configuração completa.
Árvore de decisão

Qual é o correto para o seu caso

Três perguntas, em ordem. Pare na primeira que corresponder ao seu projeto.
1
O usuário sempre envia a mensagem para você primeiro, e o bot só precisa responder a comandos e mensagens?
->Bots de suporte, notificações baseadas em consentimento, ferramentas de comando onde o usuário inicia o contato.API de Bot
2
Você precisa entrar em contato primeiro e também precisa de canais, chats secretos, administração de grupos ou chamadas?
->Cobertura completa de plataforma, e você está disposto a criar e manter seu próprio cliente MTProto com Telethon, Pyrogram, GramJS ou TDLib.API de Usuário do Telegram, construída por conta própria
3
Você precisa entrar em contato primeiro, agir como uma conta real e começar sem possuir o MTProto?
->Mensagens, histórico de bate-papo e gerenciamento de participantes de grupos em uma conta de usuário conectada, com a sessão gerenciada para você.Unipile
A maioria das equipes para aqui
Conecte uma conta real do Telegram sem criar um cliente
Se o seu projeto precisa fazer o primeiro contato, mas não precisa de canais, chats secretos ou chamadas, uma conta vinculada via Unipile permite que você alcance esse objetivo sem a necessidade de manter uma implementação da API de Usuário do Telegram.
Construa com Unipile

API do Bot do Telegram vs API do Telegram - FAQ

Dúvidas comuns sobre a escolha entre a API de Bots do Telegram e a API de Usuário do Telegram (MTProto).
A Bot API é uma interface HTTP que controla uma conta de bot e expõe uma superfície deliberadamente limitada. A API do Telegram, também chamada de API de Cliente, utiliza o protocolo binário MTProto e controla uma conta de usuário real com o conjunto completo de recursos. Elas são tipos de contas diferentes, não duas versões da mesma coisa.
Pergunte para quem você precisa escrever. Se seus usuários enviarem mensagem para você primeiro e a identidade de um bot for aceitável, use a API de Bots. Se você precisar alcançar pessoas que não entraram em contato com você, ou agir como uma pessoa real, você precisa de acesso à conta de usuário.
Não. O usuário deve iniciar a conversa primeiro. Este é o único limite que afasta a maioria dos produtos da API de Bots, e nenhum endpoint contorna isso.
Não. A Bot API precisa apenas do token do bot que o BotFather fornece. api_id e api_hash vêm de my.telegram.org e são para a Client API, sendo permitido um api_id por número de telefone.
Difícil o bastante para que quase ninguém o escreva do zero. Você gerencia persistência de sessão, autenticação de dois fatores, reconexão e um protocolo binário. A maioria das equipes usa Telethon, Pyrogram, GramJS ou TDLib, e ainda assim controla o ciclo de vida da sessão.
É outro nome para a API do Cliente, a interface MTProto que se autentica como um usuário real do Telegram em vez de um bot.
Sim. Conectar uma conta existente por meio do recurso Dispositivos do Telegram fornece acesso à conta do usuário sem implementar o MTProto. É assim que o Unipile vincula contas do Telegram, por meio de login com código QR ou um fluxo de autenticação hospedado.
Ainda tem dúvidas? Nossa equipe está aqui para ajudar.
Fale com um especialista
pt_BRBR
en_USEN fr_FRFR es_ESES de_DEDE it_ITIT nl_NLNL pl_PLPL tr_TRTR pt_BRBR