O que é um pacote de requisições

Um pacote de requisições corresponde à solicitação de envio de uma mensagem de notificação para um ou mais destinatários. Na prática é o payload enviado na chamadas dos serviços de envio de mensagens de notificação Como enviar mensagem de notificação.

O pacote de requisições deve ser utilizado para muitos destinatários quando o exato mesmo conteúdo deve ser enviado para vários contatos. Esta mensagem pode até ser parametrizada, mas o valor do parâmetro deve ser o mesmo para todos os destinatários. Se o valor de algum parâmetro tiver que ser diferente, um pacote de requisições específico deve ser usado para cada valor diferente do parâmetro. Não há como em um mesmo pacote ter valores diferentes para o mesmo parâmetro.

Como exemplo apresentamos o payload abaixo. Ele representa um pacote com solicitação de envio de mensagens para os destinatários CONTATO_1, CONTATO_2 e CONTATO_N. O conteúdo da mensagem a ser enviada para os três contatos será determinado pelo template NOME_DO_TEMPLATE_META, aplicando-se o valor "10 dias" ao único parâmetro do mesmo.

{
    "nomeTemplate": "NOME_DO_TEMPLATE_META",
    "wabaId": "VALOR_ID_WABA_META",
    "destinatarios": [ "CONTATO_1", "CONTATO_2", "CONTATO_N" ],
    "body": {
        "parametros": [ 
            { 
                "tipo": "text", 
                "valor": "10 dias" 
            }
        ]
    }
}

Estrutura completa do payload do pacote de requisições

Abaixo segue um exemplo de uma estrutura json com todos os parâmetros que podem aparecer em um payload de requisição de envio de mensagens. Alguns destes campos são obrigatórios, enquanto outros são opcionais mas devem ser informados dependendo do template utilizado.

{
    "nomeTemplate": "NOME_TEMPLATE_META",
    "wabaId": "WABA_ID",
    "destinatarios": [ "CONTATO_1", "CONTATO_2", "CONTATO_N" ],
    "header": {
        "idMedia": "ID_MEDIA",
        "parametros": [ 
            { 
                "tipo": "text", 
                "valor": "VALOR_PARAMETRO_HEADER" 
            }
        ]
    },
    "body": {
        "parametros": [ 
            { 
                "tipo": "text", 
                "valor": "VALOR_PARAMETRO_BODY"
            }
        ]
    }
}

Atributos do pacote de requisições e validações

A consequência da obrigatoriedade dos campos pode variar de acordo com cada campo. Os campos nomeTemplate, wabaId e destinatarios, por exemplo, causam erro de requisição mal formada caso estes não estejam presentes no payload.

Já os atributos idMedia ou os parâmetros (tanto de cabeçalho quanto de corpo do texto) podem causar erro na chamada à API da Meta para envio de mensagem ou até mesmo ter uma mensagem incorreta enviada ao destinatário final.

Campo	Pai na estrutura do payload	Obrigatório	Descrição
nomeTemplate	-	Sim	Nome do template que será usado para compor a mensagem. Este template deve ser previamente cadastrado na interface de gereciamento de negócios da Meta.
wabaId	-	Sim	Identificador da WhatsApp Business Account (WABA), que deve ser previamente cadastrada na interface de gerenciamento de negócios da Meta.
destinatarios	-	Sim	Lista de destinatários para os quais a mensagem será enviada.
header	-	Deve ser informado se o template tem cabeçalho e se este contém alguma informação dinâmica. Informações dinâmicas são parâmetros em cabeçalhos do tipo texto ou id da Mídia em caso de cabeçalho do tipo mídia.	Objeto de configuração do cabeçalho a ser incluído na mensagem.
idMedia	header	Deve ser informado o template tem cabeçalho do tipo mídia. Este valor é retornado no serviço de upload de mídia.	Identificador da mídia na Cloud API da Meta.
linkMedia	header	Deve ser informado quando o template tem cabeçalho do tipo mídia. Este valor é retornado no serviço de upload de mídia.	Endereço de localização da mídia.
filename	header	Não. Use somente com mídia de documento. A extensão do nome do arquivo especificará o formato em que o documento será exibido no WhatsApp.	Nome do arquivo da mídia.
parametros	header	Deve ser informado quando o template tem cabeçalho do tipo texto e este contém parâmetros em seu valor. Deve haver uma entrada para cada parâmetro declarado no template. O atributo tipo indica o tipo de parâmetro (atualmente apenas text é aceito) e o atribuito valor contém o valor do parâmetro.	Lista com parâmetros do cabeçalho de texto a ser incluído na mensagem.
body	-	Deve ser informado se o corpo da mensagem no template contém alguma informação dinâmica. Informações dinâmicas no corpo da mensagem somente existe na forma de parâmetro.	Objeto de configuração de parâmetros do corpo de texto da mensagem.
parametros	body	Deve ser informado quando o corpo da mensagem no template contém parâmetros em seu texto. Deve haver uma entrada para cada parâmetro declarado no template. O atributo tipo indica o tipo de parâmetro (atualmente apenas text é aceito) e o atribuito valor contém o valor do parâmetro.	Lista com parâmetros do cabeçalho de texto a ser incluído na mensagem
tipo	parametros (tanto header quanto body)	Sim	Tipo do parâmetro. No momento atual apenas text é aceito.
valor	parametros (tanto header quanto body)	Sim	Valor do parâmetro. Conteúdo textual que será incluído na mensagem no local definido pelo parâmetro.

Outras validações

Mídia

Uma das validações que é feita é em relação à mídia utilizada no cabeçalho do template. No pacote de requisições há o campo idMedia, que contém um identificador de uma mídia que foi feito upload para a Cloud API da Meta. Quando uma requisição é recebida, se este valor é informado ele é validado através de chamada à API da Meta. Se o id é válido esta retorna os dados da mídia. Com o resultado em mãos é validado se o tipo da mídia é um dos permitidos: image, video ou document.

Lista de destinatários

O tamanho da lista de destinatários não pode exceder um limite máximo pré-configurado, que atualmente é 1000.