API e Integrações do Telegram Ads: Automatize Seu Fluxo de Trabalho

O Telegram não publica nenhuma API para anunciantes: o site para desenvolvedores lista uma Bot API, uma API de cliente, a TDLib, uma Gateway API e uma Payments API, e nenhuma delas cria campanhas de anúncios nem gera relatórios sobre elas. A ADSLY se conecta às suas contas de anúncios por uma sessão autorizada e coloca por cima três pontos de integração: uma API REST que lê as suas estatísticas e, se você permitir, gerencia as suas campanhas; webhooks assinados; e um endpoint que recebe conversões do seu tracker.

Como funciona a «API» do Telegram Ads

A plataforma de anúncios do Telegram fica em ads.telegram.org e é operada pela interface web. Conferimos a documentação para desenvolvedores do Telegram em outubro de 2026: core.telegram.org apresenta a Bot API (com uma Payments API para bots), a TDLib, a Gateway API e a Telegram API para criar aplicativos cliente. Os dois artigos ligados a anúncios são Sponsored Messages, que explica aos aplicativos cliente como exibir anúncios, e outro sobre a receita publicitária de donos de canais e bots; nenhum deles serve a um anunciante que gerencia campanhas. O guia de primeiros passos da própria plataforma também não menciona API alguma.

Por isso a ADSLY trabalha por meio de uma sessão da conta do Telegram que é dona da conta de anúncios. Há três formas de conectar uma conta: informar o número de telefone e confirmar a solicitação no Telegram, usar a nossa extensão de navegador enquanto você está logado em ads.telegram.org, ou colar você mesmo o token de sessão. A solicitação conecta apenas a conta de anúncios, não o seu Telegram pessoal. Contas vindas do Adstat são conectadas com o seu login do Adstat. Depois de conectadas, contas Euro, TON e Stars são tratadas do mesmo jeito.

O que a ADSLY faz depois que a conta está conectada

Tudo o que na interface web é feito clique a clique vira uma ação no painel:

Criação de campanhas — uma campanha com todas as configurações, ou uma criação em massa: vários textos × vários links × uma lista de canais, com a opção de dividir em uma campanha por país, por tema ou por dispositivo.

Mudanças de CPM e orçamento — definir, aumentar ou reduzir o lance de todas as campanhas selecionadas, por um valor ou por um percentual; adicionar orçamento, reduzi-lo ou retirar o que sobrou.

Pausar, retomar e excluir — para uma seleção, um grupo ou todas as campanhas que batem com o filtro atual.

Sincronização de estatísticas — visualizações, cliques, ações, gasto, CTR e CPM são gravados uma vez por hora para cada campanha.

Edição de texto, título e mídia — em massa, sem recriar as campanhas.

Acompanhamento de saldos — o painel inicial lista cada conta com o saldo e a contagem de campanhas ativas, em revisão, recusadas e paradas, atualizados a cada sincronização.

Exportação de dados e relatórios

O painel guarda mais histórico do que uma aba de estatísticas mostra e deixa você levar esses dados embora:

Exportação para Excel, CSV e PDF — um arquivo de dados com as colunas que você escolher, ou um relatório em PDF, para uma conta inteira, um grupo ou campanhas selecionadas. Disponível nos planos Pro e Agency.

Dados de desempenho por hora — um snapshot por campanha por hora, guardado por 30 dias; períodos mais longos usam totais diários. Não temos medição por hora do dia entre contas, então use o gráfico por hora das suas próprias campanhas para achar os seus horários.

Análise de todas as contas — a página Análise soma visualizações, cliques e ações de cada conta a que você tem acesso. O gasto continua separado por moeda: euros, TON e Stars nunca são somados.

Histórico de alterações — cada mudança de status, de lance e de orçamento de uma campanha fica registrada junto com quem ou o que a fez, incluindo regras e Auto CPM.

Hooks de automação

Regras e ações automáticas rodam depois de cada sincronização horária, sem ninguém olhando o painel:

Regras IF/THEN — condições sobre visualizações, cliques, ações, CTR, CVR, gasto, CPC, CPA, CPM e orçamento, cada uma medida sobre todo o histórico ou sobre as últimas 1–168 horas. Ações: pausar, ativar, definir o CPM, aumentar ou reduzir o CPM por um valor ou um percentual, adicionar ou reduzir orçamento, ou apenas notificar. Exemplo: SE o CPM ficar acima de €2,50 nas últimas 6 horas, ENTÃO reduzir o lance em 15%. Uma regra pode ficar em uma campanha, em um grupo, em uma seleção ou na conta inteira.

Regras sobre as suas próprias conversões — quando o tracker passa a enviar postbacks, o mesmo motor pode agir sobre leads, conversões, compras, receita, ROAS, custo por lead e custo por venda. Uma conta que não envia postbacks nunca é pausada por uma regra dessas: ausência de dados é tratada como desconhecido, não como zero.

Rascunhos de regras para várias contas — um rascunho salvo fica no seu login da ADSLY, e Aplicar às contas (Apply to cabinets) copia a regra para cada conta que você marcar.

Auto CPM — uma vez por hora o painel verifica se o anúncio está de fato aparecendo nos canais e bots que ele segmenta. Aparece na maioria: o lance cai 10%. Não aparece na maioria: sobe 10%. São necessárias duas verificações seguidas que concordem; o intervalo entre mudanças é de três horas, com no máximo seis por dia por campanha.

Recriar e AI Recreate — um anúncio recusado é reenviado automaticamente; com o AI Recreate, cada tentativa leva o texto reescrito. Não publicamos nenhum percentual de recuperação.

Casos de integração para agências

Quatro montagens que essas peças tornam possíveis:

Relatórios para clientes — exporte um PDF ou um Excel por conta de cliente ou por grupo, ou puxe /v1/stats para a ferramenta de relatórios que você já usa.

Alertas — uma regra com a ação de notificar entra no resumo horário, entregue no Telegram, por e-mail ou dentro do aplicativo. Para os seus próprios sistemas, o webhook status_change dispara quando uma campanha passa para Declined, Active ou qualquer outro status.

Dashboards próprios — /v1/stats/total devolve totais e pontos de gráfico por conta; uma sincronização típica são três ou quatro requisições, bem abaixo das 60 por minuto que uma chave permite.

Fechar o ciclo com um tracker — envie leads e vendas para o endpoint de postback e a tabela de campanhas mostra o custo por lead e por venda ao lado das colunas do Telegram. O painel traz modelos de postback prontos para colar para Keitaro, RedTrack, Binom e Voluum.

API REST e webhooks da ADSLY

A API está no ar para contas Pro e Agency. Abra API no menu, clique em + Nova chave (+ New key) e escolha a quais contas a chave tem acesso — uma, várias ou todas — e se ela também pode gerenciar campanhas. Até cinco chaves podem ficar ativas ao mesmo tempo.

URL base: https://app.adsly.pro/api/v1 · Autenticação: cabeçalho X-API-Key · Limite: 60 requisições por minuto por chave

Toda chave pode ler:

• GET /v1/account/info — as contas que esta chave enxerga

• GET /v1/campaigns — campanhas com as métricas; filtros por status, título, nome de usuário do bot ou canal, domínio da página de destino e tipo de anúncio; paginação por cursor

• GET /v1/stats — estatísticas por campanha em um período, agrupadas por conta

• GET /v1/stats/total — totais e pontos de gráfico por conta

• GET /v1/stats/analytics — análise do período com as principais campanhas

• GET /v1/campaigns/:adId/history — uma campanha ao longo de um período

• GET /v1/conversions — conversões recebidas por postback, por campanha

Gerenciar campanhas (Manage campaigns). Enquanto você não liga essa opção numa chave, ela só lê. Com a opção ligada, a chave também cria campanhas (até 100 por chamada), edita texto, link, CPM e teto diário, pausa e retoma, adiciona orçamento ou retira o que sobrou, copia, roda ações em massa em até 1.000 campanhas de uma vez, exclui e envia mídia. Nenhuma chave consegue tirar dinheiro de uma conta: o orçamento só circula entre o saldo da conta e as campanhas dela. Toda alteração feita pela API aparece no histórico da campanha no painel, e as chamadas de criação, orçamento, cópia e ações em massa aceitam um Idempotency-Key, então repetir após um timeout não executa nada duas vezes.

A documentação completa fica em adsly.pro/docs/api (em inglês), com uma versão em Markdown de cada página e um índice llms.txt para assistentes de IA.

Duas coisas derrubam as primeiras integrações. Os campos monetários (spent, budget, cpm, cpc, cpa, ctr) chegam como strings para preservar a precisão, então converta antes de fazer contas. E ad_id é único apenas dentro de uma conta — o Telegram reutiliza os identificadores —, portanto guarde sempre junto com account_id.

Webhooks. Coloque uma Postback URL em uma chave e a ADSLY envia JSON assinado para ela: status_change quando o status de uma campanha muda na sincronização, e hourly_digest cinco minutos depois de cada hora cheia, com visualizações, cliques, gasto e ações por campanha da hora que acabou de fechar. Cada requisição leva uma assinatura HMAC-SHA256 em X-Adsly-Signature, um timestamp e um identificador de entrega único. O endpoint precisa ser HTTPS público; uma entrega que falha é repetida uma vez.

Conversões de entrada. Ative Receber postbacks (Receive postbacks) em uma chave e então envie POST /v1/postback do seu backend com a chave no cabeçalho, ou passe ao seu tracker a URL somente de escrita gerada em Gerar URL do tracker (Generate tracker URL). Os eventos são lead, conversion e purchase, com valor e moeda opcionais; cabem até 1.000 eventos em uma requisição, e uma chave aceita 20 eventos por segundo. Um evento é associado à campanha pelo valor que vai no link do anúncio: o parâmetro ?start= em anúncios de bot, o parâmetro do seu tracker em anúncios de site.

Segurança e acesso

Essas contas movimentam orçamento de verdade, então cada ponto de entrada é estreito de propósito:

Sessão, não senha — uma conta de Telegram Ads é conectada confirmando uma solicitação no Telegram, pela extensão de navegador ou com um token de sessão. A conexão cobre a conta de anúncios, não o seu Telegram pessoal.

Somente leitura por padrão, guardadas em hash — uma chave só lê até o dono ligar Gerenciar campanhas, e mesmo assim não consegue tirar dinheiro de uma conta. As chaves ficam guardadas como hashes SHA-256, de modo que uma chave perdida não pode ser recuperada, apenas revogada e substituída.

Webhooks assinados — verifique a assinatura HMAC e rejeite requisições com timestamp de mais de cinco minutos. A ADSLY se recusa a entregar para endereços sem HTTPS, de loopback ou privados.

Acesso da equipe por conta — no plano Agency, cada pessoa recebe o nível Viewer, Manager ou nenhum acesso para cada conta. Os membros criam as próprias chaves de API, e cada chave alcança só as contas compartilhadas com aquele membro: somente leitura onde ele é Viewer, com alterações permitidas onde é Manager.

Automatize o seu fluxo de trabalho no Telegram Ads. A ADSLY gerencia 500,000+ campanhas — e uma conta Euro abre para qualquer país. Os três tipos de conta (TON, Euro, Stars). Regras IF/THEN, operações em massa, API para estatísticas e gestão de campanhas, webhooks e exportação. Comece grátis — Teste Pro de 3 dias →

Perguntas frequentes

Existe uma API pública do Telegram Ads?

Para anunciantes, não. O site para desenvolvedores do Telegram lista a Bot API, a API de cliente, a TDLib, uma Gateway API e uma Payments API (consultado em outubro de 2026); nenhuma delas gerencia campanhas de anúncios, e a seção Sponsored Messages é para aplicativos que exibem anúncios. A plataforma de anúncios em ads.telegram.org é operada pela interface web. A ADSLY trabalha por cima dela, por meio de uma sessão autorizada.

Como a ADSLY se conecta à minha conta de Telegram Ads?

Por meio de uma sessão da conta do Telegram que é dona da conta de anúncios. Você confirma uma solicitação no Telegram depois de informar o número de telefone, usa a extensão de navegador ou cola o token de sessão. A solicitação conecta apenas a conta de anúncios. Contas Euro, TON e Stars são conectadas assim; contas vindas do Adstat são conectadas com um login do Adstat.

Meus dados do Telegram Ads estão seguros na ADSLY?

Os pontos de integração são estreitos por desenho. As chaves de API só leem enquanto você não liga Gerenciar campanhas, nunca conseguem tirar dinheiro de uma conta e ficam guardadas em hash; toda alteração feita pela API fica no histórico da campanha; os webhooks são assinados com um segredo próprio de cada chave e só vão para endpoints HTTPS públicos; a URL somente de escrita do tracker consegue enviar conversões, mas não lê nada; e no plano Agency o acesso é concedido por conta e por pessoa.

Posso exportar dados do Telegram Ads para o Google Sheets?

Não existe um conector direto com o Google Sheets. Exporte um arquivo CSV ou Excel do painel e importe, ou leia a API a partir de um script — /v1/stats devolve os números por campanha para qualquer período.

A ADSLY tem webhooks para o Telegram Ads?

Sim. Uma chave com Postback URL recebe status_change sempre que o status de uma campanha muda e hourly_digest uma vez por hora com visualizações, cliques, gasto e ações por campanha. Os dois são assinados com HMAC-SHA256, e o botão Test da chave envia um ping para você conferir o seu receptor.

A API REST da ADSLY já está disponível?

Sim, nos planos Pro e Agency, e você mesmo cria as chaves no painel. Toda chave lê a lista de contas, campanhas, estatísticas, análise, histórico por campanha e conversões recebidas, a 60 requisições por minuto por chave. Uma chave com Gerenciar campanhas ligado também cria, edita, pausa, retoma, abastece, copia e exclui campanhas e envia mídia. Documentação: adsly.pro/docs/api.