Como enviar mensagem de notificação
Mensagens de notificação são conversas via Whatsapp iniciadas pela empresa cliente em que o usuário final não iniciou uma conversa. Este tipo de mensagem precisa ter um template previamente cadastrado e aprovado na Meta. Este documento explica como fazer o envio de mensagens de notificação, passando parâmetros para o template. Estes parâmetros podem ser do tipo:
- Texto
- Mídia
- Localização
- Mensagem interativa
Uma mensagem de notificação pode conter mais de um usuário destinatário. Os parâmetros definidos são os mesmos para todos os destinatários, que corresponde ao pacote de requisições de envio de mensagens, conforme explicado na documentação O que é um pacote de requisições.
1. Primeiro passo - Obter token de acesso
Antes de fazer requisições HTTP para qualquer endpoint aqui citado, a aplicação cliente deve obter o token de acesso às APIs, conforme descrito no guia Como autenticar.
2. Segundo passo - Upload de mídia para Cloud Api da Meta [Opcional]
Caso o template possua Mídia, pode-se fazer primeiro o upload da mídia para a Cloud Api da Meta, conforme descrito no guia Como enviar mídia para Cloud Api da Meta [Opcional]. Pode-se, também, utilizar o link para esta mídia. Para isso, o ativo precisa estar em um servidor público acessível. Caso contrário, a mensagem não será enviada.
3. Terceiro passo - Definição do pacote de requisições
Após obter o token de acesso (e opcionalmente o id da mídia a ser usada no envio da mensagem), a aplicação cliente deve montar o payload da requisição de envio de mensagens de notificação, que corresponde ao pacote de requisições de envio de mensagens.
O valores definidos no template, que não possuírem valores dinâmicos, como o footer e em alguns casos os botões de resposta rápida e de chamada a ação, não devem ser passados na requisição, somente é necessário passar os parâmetros.
Este payload será enviado no corpo da requisição de envio de mensagens de notificação e abaixo há exemplos para cada tipo de parâmetro.
Texto
Quando o template possui um parâmetro do tipo texto no corpo.
{
"nomeTemplate": "NOME_DO_TEMPLATE_META",
"wabaId": "VALOR_ID_WABA_META",
"destinatarios": [ "CONTATO_1", "CONTATO_2", "CONTATO_N" ],
"body": {
"parametros": [
{
"tipo": "text",
"valor": "10 dias"
}
]
}
}
Quando o template possui um parâmetro do tipo texto no cabeçalho.
{
"nomeTemplate": "NOME_DO_TEMPLATE_META",
"wabaId": "VALOR_ID_WABA_META",
"destinatarios": [ "CONTATO_1", "CONTATO_2", "CONTATO_N" ],
"header": {
"parametros": [
{
"tipo": "text",
"valor": "TEXTO"
}
]
}
}
Mídia
Web
Celular
A mídia é sempre utilizada no cabeçalho do template.
Exemplo utilizando o id da mídia. Perceba que o campo idMedia que contém o identificador obtido da chamada ao serviço de upload para a Meta e que esse campo faz parte do cabeçalho do template (header).
{
"nomeTemplate": "NOME_DO_TEMPLATE_META",
"wabaId": "VALOR_ID_WABA_META",
"destinatarios": [ "CONTATO_1", "CONTATO_2", "CONTATO_N" ],
"header": {
"idMedia": "ID_MEDIA"
},
"body": {
"parametros": [
{
"tipo": "text",
"valor": "10 dias"
}
]
}
}
Exemplo utilizando o link da mídia. Perceba que o campo linkMedia que contém o endereço para acesso à mídia.
{
"nomeTemplate": "NOME_DO_TEMPLATE_META",
"wabaId": "VALOR_ID_WABA_META",
"destinatarios": [ "CONTATO_1", "CONTATO_2", "CONTATO_N" ],
"header": {
"linkMedia": "LINK_MEDIA"
},
"body": {
"parametros": [
{
"tipo": "text",
"valor": "10 dias"
}
]
}
}
Localização
Localização utilizada no cabeçalho do template.
{
"nomeTemplate": "NOME_DO_TEMPLATE_META",
"wabaId": "VALOR_ID_WABA_META",
"destinatarios": [ "CONTATO" ],
"header": {
"localizacao": {
"latitude": -15.7801,
"longitude": -47.9292,
"nome": "Nome Local",
"endereco": "Endereço Local"
}
},
"body": {
"parametros": [
{
"tipo": "text",
"valor": "VALOR"
}
]
}
}
Mensagem interativa
As mensagens interativas podem conter botões de resposta rápida, sendo no máximo três ou botões de chamada a ação, podendo haver um para URL e um para número de telefone. Esses valores geralmente virão preenchidos no template, mas a URL pode ser dinâmica, dessa forma, quando houver uma URL dinâmica deve ser passado o objeto buttons conforme exemplo abaixo.
Exemplos de mensagens de notificação interativas.
URL
{
"nomeTemplate": "NOME_DO_TEMPLATE_META",
"wabaId": "VALOR_ID_WABA_META",
"destinatarios": [ "CONTATO_1", "CONTATO_2", "CONTATO_N" ],
"body": {
"parametros": [
{
"tipo": "text",
"valor": "102030"
}
]
},
"buttons": [
{
"sub_type": "url",
"index": "0",
"parametros": [
{
"tipo": "text",
"valor": "102030"
}
]
}
]
}
Flows
Template
Formulário
As mensagens interativas podem conter formulários denominados flows. Veja mais detalhes sobre flows e os parâmetros utilizados na guia O que são Flows?
{
"nomeTemplate": "NOME_DO_TEMPLATE_META",
"idiomaTemplate": "pt_BR", // opcional
"wabaId": "VALOR_ID_WABA_META",
"destinatarios": [ "CONTATO_1", "CONTATO_2", "CONTATO_N" ],
"buttons": [
{
"sub_type": "flow",
"index": "0",
"parametros": [
{
"tipo": "action",
"acao": {
"flow_token": "FLOW_TOKEN" // opcional
"flow_action_data": { ... } // opcional
}
}
]
}
]
}
{
"nomeTemplate": "NOME_DO_TEMPLATE_META",
"wabaId": "VALOR_ID_WABA_META",
"destinatarios": [ "CONTATO_1", "CONTATO_2", "CONTATO_N" ],
"buttons": [
{
"sub_type": "flow",
"index": "0",
"parametros": [
{
"tipo": "action"
}
]
}
]
}
Mensagem de segurança
Para mensagens de template do tipo segurança, ou one time password, é necessário passar o body com um parâmetro do tipo text e valor correspondente ao código, além de passar um button, com subtype url, index relativo a posição do botão (0 para o primeiro ou 1 para o segundo) e o parâmetro do tipo texto com o mesmo código. Este button será usado para gerar o botão "copiar código" para o usuário.
Segue exemplo de mensagem de segurança:
{
"nomeTemplate": "nome_do_template",
"wabaId": "waba_id",
"destinatarios": [ "numero" ],
"body": {
"parametros": [
{
"tipo": "text",
"valor": "102030"
}
]
},
"buttons": [
{
"sub_type": "url",
"index": "0",
"parametros": [
{
"tipo": "text",
"valor": "102030"
}
]
}
]
}
Os templates poderão ser criados em diferentes idiomas, a saber:
- Português (BR)
- Inglês (US)
- Espanhol (ESP)
- Francês
- Italiano
Importante!
O que identifica um template é o seu nome e o seu idioma. Logo, podem existir templates de mesmo nome, porém com idiomas diferentes.
4. Quarto passo - Solicitar envio de mensagens de notificação
Para solicitar o envio de mensagens de notificação deve-se fazer uma requisição HTTP POST para o endpoint https://api.whatsapp.serpro.gov.br/client/{id}/v2/requisicao/mensagem/template, enviando o payload do pacote de requisições no corpo da requisição, conforme exemplo abaixo usando curl.
URI
URI: https://api.whatsapp.serpro.gov.br/client/{fromPhoneNumberId}/v2/requisicao/mensagem/template
Método: POST
FROM_PHONE_NUMBER_ID
Este campo deve ser o mesmo informado no client_id na geração do token.
Exemplo de envio de mensagem de notificação com curl
curl -v --request POST \
--url 'https://api.whatsapp.serpro.gov.br/client/{fromPhoneNumberId}/v2/requisicao/mensagem/template' \
--header 'Authorization: Bearer VALOR_TOKEN' \
--header 'Content-Type: application/json' \
-d ' {
"nomeTemplate": "NOME_DO_TEMPLATE_META",
"wabaId": "VALOR_ID_WABA_META",
"destinatarios": [ "CONTATO_1", "CONTATO_2", "CONTATO_N" ],
"header": {
"idMedia": "ID_MEDIA"
},
"body": {
"parametros": [
{
"tipo": "text",
"valor": "10 dias"
}
]
}
}
'
5. Quinto passo - Resultado da solicitação de envio de mensagens de notificação
A resposta do serviço de envio de requisições de mensagens de notificação é um objeto json, conforme exemplo abaixo:
Este exemplo ilustra uma resposta com sucesso na internalização da solicitação de envio de mensagens de notificação. O campo id contém o identificador interno do pacote de requisições, que deverá ser usado posteriormente na consulta ao status da solicitação de envio.
{
"id": "7f6546e3-a591-4c9a-bbfd-4e67f4839019",
"acoes": [
{
"rel": "status",
"uri": "#/client/260923873768685/v2/requisicao/7f6546e3-a591-4c9a-bbfd-4e67f4839019",
"method": "GET"
}
]
}
Em caso de falha na solicitação de envio de mensagens de notificação, o retorno conterá a lista de erros encontrados na internalização da solicitação de envio. No exemplo abaixo, a solicitação falhou porque o template informado na requisição não foi previamente cadastrado na Cloud Api da Meta, conforme os requisitos para envios de mensagens.
{
[
"O template exemplo_de_confirmao_de_envio_inexistente não foi encontrado na lista de templates cadastrados."
]
}
6. Sexto passo - Consultar status da solicitação de envio de mensagens de notificação
Em caso de sucesso no requisição de envio de mensagens de notificação o próximo passo é consultar o status do envio das mensagens, conforme descrito no guia Como consultar status de envio de mensagens.