Skip to main content
Quatro chamadas separam uma credencial nova de uma notificação extrajudicial certificada, com laudo. As três primeiras não custam nada.
A terceira chamada envia de verdade. Não há ambiente de teste, veja Ambiente. Use um número seu até ter certeza do formato.
1

Pegue sua credencial

Em Conta → API Keys, crie uma credencial. O segredo completo aparece uma única vez.
Confirme que ela funciona antes de seguir. Um 404 aqui é boa notícia: significa que a credencial autenticou e o identificador é que não existe.
2

Leia o modelo

O texto do envio vem sempre de um modelo, e é do modelo que saem as chaves de parameters. Por isso esta chamada não é opcional: sem ela você não consegue montar a próxima.Para começar sem preparar nada, use este modelo pré-aprovado, disponível para qualquer organização:
É um modelo de convocação de comparecimento por WhatsApp, só texto, já aprovado. Serve para o quickstart inteiro.
No painel esse modelo aparece como Pré-aprovado. Na API o valor é template_status: "APPROVED" com template_origin: "SYSTEM": não existe um status PRE_APPROVED. É a mesma coisa com dois nomes.
Os modelos da sua organização ficam em Conta → Modelos. Abra o modelo e copie o template_id. Ele também está na URL da página, no formato /conta/modelos/PBD_TPL_....Você também pode criar um com POST /templates. Se fizer isso, guarde o template_id que a resposta devolve. Não é mais a única chance de obtê-lo, porque GET /templates lista os seus modelos e os pré-aprovados, mas guardar poupa uma chamada. Em WhatsApp o modelo novo ainda precisa da aprovação da Meta antes do primeiro envio.Para enviar por e-mail você vai precisar de um modelo seu com channel: "email".
O campo variables vem assim:
A chave de parameters é o marcador literal, "{{1}}". Não é o índice e não é o variable_name.Em WhatsApp, os marcadores do rodapé do remetente aparecem no body do modelo mas não em variables: é o Pombo que os preenche, a partir do sender do envio.
3

Envie

Esta chamada entrega uma mensagem real e desconta um envio do saldo. Use um número seu.
Os cinco parameters abaixo são as variáveis do modelo pré-aprovado do passo anterior. Troque recipient_phone, recipient_full_name e recipient_tax_id pelos seus dados e o corpo está pronto.As cinco são obrigatórias. Faltando qualquer uma, a chamada é recusada com 400 INVALID_PARAMETERS antes de qualquer envio, e uma chave que o modelo não tem é recusada da mesma forma. Faltando várias, a resposta traz todas de uma vez, separadas por |:
O rodapé do modelo de WhatsApp também traz marcadores, mas eles não são seus. O Pombo preenche os três com o que você declarou em sender, por isso não aparecem em variables. Enviar qualquer um deles em parameters faz a chamada ser recusada.
Guarde o notification_id. É por ele que você acompanha a entrega e baixa o laudo. Se você perder, GET /notifications devolve os seus envios da mais recente para a mais antiga, então dá para recuperá-lo, mas depende de você reconhecer a notificação certa na lista.
Para enviar um anexo, o arquivo viaja nesta mesma chamada, em multipart/form-data. Em WhatsApp o anexo exige um modelo DOCUMENT ou IMAGE: o pré-aprovado deste guia é só texto e recusa o arquivo. As partes, os tipos aceitos e os limites estão em Cria uma notificação extrajudicial.
Troque channel por "EMAIL" e recipient_phone por recipient_email. E-mail exige um modelo seu com channel: "email": o modelo pré-aprovado acima é de WhatsApp.O endereço de origem é resolvido pelo Pombo. Sem endereço dedicado verificado, o e-mail sai do endereço compartilhado do Pombo, que é o caso comum. Se a organização já verificou um endereço próprio, passa a haver mais de um endereço utilizável e o envio é recusado com 422 SENDER_CHOICE_REQUIRED. Nesse caso, fale com o suporte do Pombo.
4

Acompanhe e baixe o laudo

Não há notificação ativa de eventos: o acompanhamento é por consulta, até o status ser terminal.
Python
Leia notification_delivery_status, não notification_status. O segundo descreve o processamento interno e não acompanha a entrega.Os eventos certificados (sent, delivered, read e failed) vêm com sua atestação, com proof_hash e certified_at. enqueued não é certificado: attestation é sempre null nele. É isso que o laudo consolida.
A certificação é assíncrona e conclui depois de notification_delivery_status chegar ao estado final. Se você parar de consultar assim que o estado for terminal, pode ler attestation: null em eventos que ainda vão ser certificados. Continue consultando até a atestação aparecer, ou baixe o laudo, que só é montado quando está completo.

​
Deu errado?

Dois tropeços são deste caminho em particular: Todos os outros estão em Erros, com o envelope, a ordem de validação e a ação sugerida para cada status.

​
Depois daqui

Idempotência

Como repetir uma chamada sem enviar duas vezes.

Glossário

Laudo, atestação, modelo, remetente: o vocabulário do Pombo.