Base de conhecimento GetMyBot

Canais: Telegram, WhatsApp e VK

Conecte Telegram, WhatsApp e VK ao mesmo projeto. Veja as diferenças entre os canais e saiba para onde o bot envia cada resposta.

Nesta página

Um projeto do GetMyBot pode responder no Telegram, WhatsApp e VK. Por exemplo, a mesma regra sobre horários de aula pode funcionar nos três aplicativos. A resposta é enviada pelo canal em que a pessoa escreveu.

Ao conectar outro aplicativo, confira os botões e as ações: cada plataforma oferece recursos diferentes. Abaixo estão as principais diferenças e os passos de conexão.

O que é um canal

Um canal é o lugar de comunicação conectado ao projeto: um bot específico do Telegram, um número do WhatsApp Business ou uma comunidade do VK. Um projeto do GetMyBot pode ter vários canais. As reações são compartilhadas: se uma pessoa escrever no WhatsApp, a mensagem será tratada pelas mesmas reações usadas no Telegram, e a resposta voltará pelo WhatsApp.

Botões, formatação e ações não funcionam em todos os canais. O editor pode ocultar uma opção indisponível ou adaptá-la. Teste a mensagem em cada canal conectado antes de começar a atender pessoas.

Canal principal (primary_channel)

Cada bot tem um canal principal (primary_channel), a plataforma à qual ele é associado primeiro. Geralmente é o Telegram, mas você também pode criar um bot de WhatsApp ou VK sem conectar Telegram. O canal principal é definido na criação e aparece na lista de bots. Os demais canais são adicionados depois.

Recursos de cada canal

A API fornece a lista atualizada de recursos em GET /api/channels/capabilities. Estas são as principais diferenças:

Telegram: botões abaixo da mensagem e teclado de resposta, cliques que iniciam reações, reações com emoji, link direto com /start, edição, exclusão e encaminhamento de mensagens, resposta a uma mensagem como gatilho, eventos de participantes, permissões e moderação. Um carrossel de fotos pode ser percorrido por botões em uma única mensagem. O texto pode usar Plain, HTML ou Markdown. Modelos de mensagem, listas interativas e janela de atendimento não fazem parte dos recursos do Telegram.

WhatsApp, por meio da WhatsApp Cloud API: botões, cliques que iniciam reações, reações com emoji, link direto com /start, modelos de mensagem, listas interativas e janela de atendimento de 24 horas. O texto pode usar Plain ou Markdown. Não oferece teclado de resposta, edição, exclusão ou encaminhamento de mensagens, resposta como gatilho, eventos de participantes, permissões de grupo ou a passagem entre fotos em uma única mensagem. Veja WhatsApp.

VK: mensagens e anexos, botões e teclado de resposta, cliques que iniciam reações, reações com emoji, link direto com /start, edição, exclusão e encaminhamento de mensagens, eventos de participantes, banimento e restauração de acesso, aprovação de uma solicitação já enviada a uma comunidade fechada e eventos da assinatura paga VK Donut. A formatação é apenas texto simples: HTML e Markdown são removidos. Não oferece modelos do WhatsApp, listas interativas, passagem entre fotos em uma única mensagem ou janela de atendimento.

Todos os canais oferecem botões, cliques que iniciam reações, reações com emoji e link direto com /start. O bloco de carrossel de fotos funciona nos canais que aceitam fotos. No Telegram, as fotos podem ser percorridas dentro de uma única mensagem quando todas têm identificadores de arquivo compatíveis. No WhatsApp e no VK, e também no Telegram quando esses identificadores não estão disponíveis, os cartões são enviados como mensagens de foto separadas. Veja Mensagens e botões.

VK Donut

Se a comunidade usa VK Donut, o bot pode receber eventos sobre assinaturas pagas. No editor em português, os nomes desses eventos ainda aparecem em inglês:

Evento mostrado no editorCódigoDados disponíveis
VK Donut: subscription created (assinatura iniciada)donut_subscription_created{{event.donut_amount}}, {{event.donut_amount_without_fee}}
VK Donut: subscription prolonged (assinatura renovada)donut_subscription_prolonged{{event.donut_amount}}, {{event.donut_amount_without_fee}}
VK Donut: subscription expired (assinatura vencida)donut_subscription_expirednenhum valor de pagamento
VK Donut: subscription cancelled (assinatura cancelada)donut_subscription_cancellednenhum valor de pagamento

{{event.donut_amount}} é o valor pago; {{event.donut_amount_without_fee}} é o valor sem a comissão do VK. Os eventos de vencimento e cancelamento não informam um pagamento. Mostrar neles o valor de uma cobrança anterior seria incorreto.

O evento informa uma mudança na assinatura, não uma mensagem da pessoa. Por isso, não libera o envio de mensagens particulares, não remove bloqueios, não atualiza a última atividade e não aumenta o contador de mensagens. Se a pessoa ainda não existir no GetMyBot, seu perfil será criado para permitir a aplicação de etiquetas e permissões.

Exemplo de um clube por assinatura:

  1. Crie uma reação para VK Donut: subscription created e outra para VK Donut: subscription prolonged. Use a ação Alterar etiquetas para adicionar «Clube» por ttl_days = 31. Envie também o link da comunidade fechada e peça à pessoa que solicite a entrada.
  2. Aprove a solicitação apenas depois que a pessoa a enviar. A ação Alterar permissões → Aprovar solicitação aceita uma solicitação já existente (groups.approveRequest). Coloque-a numa reação posterior, por exemplo, no botão «Já solicitei a entrada» ou no próximo evento de renovação.
  3. Crie uma reação para Label expired (label_expired), o evento de etiqueta vencida. Use Alterar permissões → Remover para retirar a pessoa do clube quando a etiqueta expirar, mesmo que o VK não envie o evento de vencimento da assinatura. Veja Gatilhos → Etiqueta vencida.
  4. Para VK Donut: subscription cancelled e VK Donut: subscription expired, remova a etiqueta «Clube» e, se for necessário, retire a pessoa da comunidade imediatamente.

O campo Conversa (chat_id) das ações de permissões do VK deve conter o ID da comunidade conectada, o mesmo número exibido no canal VK. O VK só pode administrar os participantes dessa comunidade. Outro ID é recusado antes do envio ao VK. Para administrar outra comunidade, conecte-a como um canal separado.

Para receber os eventos:

  • Long Poll: o bot ativa a assinatura automaticamente ao conectar o canal e a cada início da plataforma. Não é preciso alterar comunidades já conectadas.
  • Callback API: nas configurações da comunidade, abra Trabalho com API → Callback API → Tipos de eventos → VK Donut e ative os quatro eventos da tabela.

Conectar um canal

Adicione canais em Projetos:

  1. Abra Projetos e escolha o projeto.
  2. Clique em Adicionar canal no cartão do projeto.
  3. Selecione Telegram, WhatsApp ou VK.
  4. Informe os dados de conexão: token do Telegram, dados da Meta para WhatsApp ou dados da comunidade do VK.
  5. Clique em Validar para conferir os dados na plataforma escolhida.
  6. Clique em Conectar.

Depois de conectar WhatsApp ou VK, aparece um endereço de webhook no canal, com o ícone 🔗. Cadastre esse endereço na Meta ou nas configurações da comunidade VK para que as mensagens recebidas cheguem ao bot. Para WhatsApp, veja Configuração do webhook.

Próximos passos

Credenciais do canal

O Telegram usa o token completo do BotFather. Para VK, informe o token da comunidade e seu ID numérico. A Callback API também requer uma chave secreta e um código de confirmação. Para WhatsApp, informe o Phone Number ID, o ID da conta WhatsApp Business, um token com acesso à conta, o Verify Token do webhook e o App Secret do aplicativo Meta.

Confira os dados antes de conectar. Ao trocar uma chave, atualize também a configuração correspondente na plataforma: o Verify Token confirma o endereço do webhook, e o App Secret verifica a assinatura dos eventos recebidos. Nenhum deles substitui o token de acesso à API.

Mensagens recebidas e endereços de webhook

Para usar a Callback API do VK, cadastre o endereço mostrado pelo GetMyBot nas configurações do servidor da comunidade e informe a chave e o código de confirmação correspondentes. O Long Poll não precisa de endereço público nem desses dois valores. Para WhatsApp, cadastre o endereço no aplicativo Meta, configure o mesmo Verify Token e assine os eventos de mensagens necessários. Configurar apenas o envio não ativa o recebimento de mensagens.

Autorizar Instagram e Messenger

O assistente de conexão abre a autorização da Meta. Entre com a conta que administra a página do Facebook ou a conta profissional do Instagram, conceda as permissões solicitadas e escolha as contas deste projeto. O assistente verifica permissões, inscrição no webhook e disponibilidade para entrega. Resolva as verificações com erro antes de usar o canal. É possível rever as contas selecionadas em uma conexão existente.