Com a Papo (https://papo.global/), você pode usar a API REST para enviar modelos de mensagem aprovados (HSM) no WhatsApp, automatizando notificações transacionais e campanhas sem acessar a interface. A API permite listar as caixas de entrada Cloud API da sua conta, recuperar os modelos aprovados pela Meta e dispará-los para um ou vários contatos, desde que você tenha um token de API e os modelos estejam sincronizados na plataforma.
| Ação da API | O que faz | Exemplo de uso |
|---|---|---|
| Listar caixas WhatsApp | Retorna as caixas de entrada WhatsApp Cloud API associadas à conta | Selecionar a caixa correta antes do envio |
| Listar templates aprovados | Devolve os modelos de mensagem (HSM) com status “aprovado” para um determinado inbox | Conferir os HSMs disponíveis para disparo |
| Enviar HSM para um contato | Dispara um modelo aprovado para um único número de telefone, preenchendo as variáveis | Notificação de pedido, lembrete de agendamento |
| Enviar HSM para vários contatos | Envia o mesmo modelo para uma lista de contatos de uma só vez | Campanha de marketing, comunicado em massa |
Como funciona o envio de HSM pela API
A API da Papo espelha as funcionalidades da plataforma. Para enviar um modelo de mensagem do WhatsApp, você não precisa criar nada novo via código: os modelos são criados e submetidos diretamente no Gerenciador de Negócios da Meta e, após aprovados, aparecem automaticamente na sua conta Papo. A API apenas consulta a lista de modelos aprovados e realiza o disparo.
O fluxo típico de integração consiste em:
- Gerar um token de API no painel da Papo.
- Identificar a caixa de entrada do WhatsApp Cloud API onde o modelo foi sincronizado.
- Obter a lista de modelos aprovados (HSM) dessa caixa.
- Preparar a requisição com os parâmetros necessários: ID do modelo, idioma, número do destinatário com código do país e os valores das variáveis (se o modelo contiver
{{1}},{{2}}etc.). - Enviar a requisição — seja para um único contato ou para um conjunto de números, cada um com suas respectivas variáveis personalizadas.
Passo a passo para utilizar a API
1. Gere um token de API
No menu de configurações da sua conta Papo, acesse a seção de API ou tokens de acesso. Crie um token com as permissões necessárias para gerenciar conversas e mensagens. Guarde o token em local seguro; ele será enviado no cabeçalho de todas as requisições.
2. Liste as caixas de WhatsApp disponíveis
Antes de enviar qualquer modelo, você precisa saber qual caixa de entrada (inbox) contém os modelos aprovados. Utilize o endpoint que retorna as caixas WhatsApp Cloud API da sua conta. Anote o identificador da caixa que pretende usar — ele será obrigatório nos passos seguintes.
3. Consulte os modelos aprovados (HSM)
Com o identificador da caixa em mãos, chame o endpoint que lista os templates com status APPROVED. A resposta trará para cada modelo o nome, o idioma disponível, a categoria (Marketing, Utilidade ou Autenticação) e os parâmetros esperados. Esse passo é importante para confirmar que o modelo está liberado e para saber quais variáveis preencher.
4. Monte a requisição de envio
A operação de envio para um único contato exige basicamente:
- O ID do modelo (ou o nome, dependendo da implementação).
- O idioma do modelo (por exemplo,
pt_BR). - O número do telefone do contato, incluindo o código do país (ex.:
5511999999999). - Um objeto com os valores das variáveis, se o modelo contiver placeholders.
Para envio em lote (múltiplos contatos), a chamada aceita uma lista de destinatários, cada um com seu número e, opcionalmente, suas próprias variáveis. O modelo é o mesmo para todos.
5. Dispare e verifique a resposta
A API retorna uma confirmação síncrona de que o pedido de envio foi aceito. Para acompanhar o status real de entrega (entregue, lido, falha), você pode configurar um webhook outbound — a Papo notifica em tempo real os eventos da conversa. O artigo sobre recebimento de eventos em tempo real (listado em “Leia também”) explica como ativar esse recurso.
Quem deve usar a API para envio de HSM
Qualquer negócio que queira automatizar comunicações transacionais a partir de sistemas externos se beneficia da API. Em vez de depender da interface da Papo para cada notificação, você pode integrar o envio diretamente ao seu ERP, CRM ou plataforma de e-commerce. Exemplos comuns:
- Confirmação de compra ou atualização de status do pedido.
- Lembrete de consulta ou agendamento enviado 24 horas antes.
- Cobrança de fatura vencida com o link de pagamento.
- Comunicação de alteração de voo ou reserva.
A API é especialmente útil quando a regra que determina quando enviar o modelo vive em outro software — por exemplo, um sistema de logística que dispara a notificação de entrega assim que o pacote sai para transporte.
Perguntas frequentes
A API da Papo tem custo adicional?
A API está disponível nos planos da Papo. Você pode gerar tokens e usar os endpoints conforme o plano contratado. Os detalhes de limites e taxas por requisição estão na página de planos e na documentação da API.
Preciso criar os modelos de mensagem via API?
Não. Os modelos devem ser criados e submetidos à aprovação no Gerenciador de Negócios da Meta. Assim que aprovados, eles são sincronizados automaticamente na Papo e aparecem na listagem de templates da API.
Posso enviar HSM para números que não estão no CRM da Papo?
Sim. O destinatário não precisa estar previamente cadastrado no CRM da plataforma. Basta informar o número do WhatsApp (com DDI e DDD) na requisição. No entanto, você deve ter o consentimento (opt-in) do cliente para receber a comunicação, especialmente se o modelo for da categoria Marketing.
Como sei se a mensagem foi entregue?
A resposta imediata da API confirma que a solicitação foi aceita e enviada ao WhatsApp. Para monitorar falhas, entregas e leituras em tempo real, é necessário ativar o webhook de eventos (outbound) da Papo. Consulte o guia de webhooks na central de ajuda.
Existe limite de velocidade para os envios via API?
Sim. A Papo aplica limites de taxa para proteger a estabilidade do serviço e respeitar as políticas do WhatsApp. Recomenda-se manter velocidades moderadas — evitar picos súbitos ajuda a preservar a saúde do número. Os valores exatos estão na documentação da API.
Posso usar a API para campanhas de marketing em massa?
Sim, desde que utilize exclusivamente modelos aprovados de categoria Marketing e tenha opt-in explícito dos destinatários. Enviar mensagens indesejadas pode gerar denúncias e colocar seu número em risco de bloqueio. Planeje os disparos com controle de cadência e sempre respeite as políticas do WhatsApp.
Leia também
- Como receber eventos em tempo real da Papo via Webhook (outbound)
- Como usar a API da Papo para criar e atualizar contatos em massa
Comece a automatizar seus envios de HSM agora – teste grátis →
Crie sua conta na Papo e envie modelos de mensagem aprovados sem custo no primeiro usuário.