Ir para o conteúdo

Como enviar mensagem de retorno

Mensagens de retorno são conversas via Whatsapp da empresa cliente em que o usuário final iniciou a conversa. Este tipo de mensagem não possui um template pré-definido. Este documento explica como fazer o envio de mensagens de retorno que podem ser do tipo:

  • Texto
  • Mídia
  • Mensagens interativas
  • Reação
  • Localização
  • Contatos
  • Marcar mensagem como lida

1. Primeiro passo - Obter token de acesso

Antes de solicitar o envio de mensagens de retorno sem cabeçalho utilizando o endpoint para envio de mensagens de retorno, 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 tipo de mensagem de retorno escolhida seja Mídia, deve-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].

3. Terceiro passo - Definição do payload da mensagem de retorno

Após obter o token de acesso, a aplicação cliente deve montar o payload da requisição de envio de mensagens de retorno.

Este payload será enviado no corpo da mensagem de retorno e abaixo há um exemplo para cada tipo de mensagem de retorno:

Mensagens de texto

Texto

Mensagem de Texto 

{
    "destinatario": "CONTATO",
    "preview_url": false,
    "body": "MENSAGEM_TEXTO"
}

Para mensagens com 'preview_url' como true devem apresentar uma URL, então a mensagem deve iniciar com 'http://' ou 'https://'

Web

Mensagem de Texto

Celular

Mensagem de Texto

{
    "destinatario": "CONTATO",
    "preview_url": true,
    "body": "LINK_TEXTO"
}

Mensagens de mídia

Mensagem de Texto

Mídia

{
    "destinatario": "CONTATO",
    "tipoMedia": "image",
    "idMedia": "ID_MEDIA",
    "caption":"texto abaixo da imagem"
}

Campo caption é opcional, serve para enviar um texto embaixo da imagem. 

{
    "destinatario": "CONTATO",
    "tipoMedia": "image",
    "linkMedia": "LINK_MEDIA",
    "caption":"texto abaixo da imagem"
}

Campo caption é opcional, serve para enviar um texto embaixo da imagem.

Documento

O parâmetro 'nomeArquivo' deve ser utilizado para o tipo de mídia document, o que auxilia o app do usuário a identificar a mídia e verificar um aplicativo indicado para tratar tal arquivo.

Web

Mensagem de Texto

Celular

Mensagem de Texto 

{
    "destinatario": "CONTATO",
    "tipoMedia": "document",
    "idMedia": "ID_MEDIA",
    "nomeArquivo":"NOME_ARQUIVO"
}

Áudio

Mensagens de áudio básicas

Mensagens de áudio exibem um ícone de áudio e um link para um arquivo de áudio. Quando o usuário toca no ícone, o cliente do WhatsApp carrega e reproduz o arquivo.

Mensagem de Áudio

{
    "destinatario": "CONTATO",
    "tipoMedia": "audio",
    "idMedia": "ID_MEDIA",
}
Tipos de áudio suportados
Tipo de áudio Extensão Tipo MIME Tamanho máximo
AAC .aac áudio/aac 16 MB
AMR .amr áudio/amr 16 MB
MP3 .mp3 áudio/mpeg 16 MB
Áudio MP4 .m4a áudio/mp4 16 MB
Áudio OGG .ogg áudio/ogg (somente codecs OPUS; áudio/ogg básico não suportado.) 16 MB

Mensagens de voz

Uma mensagem de voz (às vezes chamada de nota de voz, memorando de voz ou áudio) é uma gravação de uma ou mais pessoas falando e pode incluir sons de fundo, como música. As mensagens de voz incluem recursos como download automático, foto de perfil e ícone de voz, não disponíveis em uma mensagem de áudio básica. Se o usuário tiver configurado a transcrição de mensagens de voz para Automática , uma transcrição em texto da mensagem também será incluída.

  • As mensagens de voz exigem arquivos .ogg codificados com o codec OPUS . Se você enviar um tipo de arquivo diferente ou um arquivo codificado com um codec diferente, a transcrição da mensagem de voz falhará.
  • O ícone de reprodução só aparecerá se o arquivo tiver 512 KB ou menos; caso contrário, será substituído por um ícone de download (uma seta apontando para baixo).
  • A imagem de perfil da sua empresa é usada como imagem de perfil, acompanhada por um ícone de microfone.

Mensagem de Áudio

{
    "destinatario": "CONTATO",
    "tipoMedia": "audio",
    "idMedia": "ID_MEDIA",
    "voice":true
}

Mensagens interativas

Lista

Mensagem de Texto

Celular

Mensagem de Texto

Web

Mensagem de Texto 

{
    "destinatario": "CONTATO",
    "textoBody":"TEXTO_BODY",
    "secoes": [
                {
                "titulo":"TITULO",
                "rows":[
                    {"id":"1",
                    "titulo":"TITULO_1",
                    "descricao":"DESCRICAO_1"},
                    {"id":"2",
                    "titulo":"TITULO_2",
                    "descricao":"DESCRICAO_2"},
                    {"id":"3",
                    "titulo":"TITULO_3",
                    "descricao":"DESCRICAO_3"}
                ]
                }
        ],
        "button":"Selecione uma opção"
}

Botões de resposta

Mensagem de Texto 

{
    "destinatario": "CONTATO",
    "textoBody":"TEXTO_BODY",
        "buttons": [
                {
                "titulo":"TITULO_1",
                "id":"ID_TITULO_1"
                },
            {
                "titulo":"TITULO_2",
                "id":"ID_TITULO_2"
                },
            {
                "titulo":"TITULO_3",
                "id":"ID_TITULO_3"
                }
        ]
}

Flows

Mensagem de retorno com flow

Formulário de pesquisa

{
    "destinatario": "CONTATO",
    "header": {
        "tipo": "text",
        "texto": "Agendamento"
    },
    "textoBody" : "Preencha o formulário abaixo:",
    "parametros": {
        "flow_token": "FLOW_TOKEN",
        "flow_id": "FLOW_ID",
        "flow_cta": "Responder",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "FLOW_SCREEN"
        }
    }
}

Botão URL

Mensagem de Texto

{
    "destinatario": "CONTATO",
    "parametros": {
        "display_text": "Texto do Botão",
        "url": "http://exemplo.com"
  }
}

Solicitação localização atual

Mensagem de Texto

{
  "destinatario": "CONTATO",
  "textoBody": "Envie sua Localização",
  "wabaId": "VALOR_ID_WABA_META"
}

Reação

Mensagem de Texto

{
    "destinatario": "CONTATO",
    "message_id": "wamid.HBgNNTUyMTk5MzU0MjUwMBUCABIYIDdBMjQ1QUNERTlERUQ5ODEwMDc5RDQ0OEU3QUM5MTRGAA==",
        "emoji":    "🙂"
}

Localização

Mensagem de Texto 

{
    "destinatario": "CONTATO",
    "latitude": -15.7801,
    "longitude": -47.9292,
    "nome": "CIDADE",
    "endereco": "ESTADO-SG"
}

Contatos

Web

Mensagem de Texto

Mensagem de Texto

Celular

Mensagem de Texto 

{
    "destinatario": "CONTATO",
    "contatos":[
        {
            "nome": {
                "nome_formatado": "NOME_FORMATADO",
                "primeiro_nome": "PRIMEIRO_NOME",
                "ultimo_sobrenome": "ULTIMO_SOBRENOME"
            },
            "telefones": [
                {
                    "telefone": "TELEFONE",
                    "tipo": "WORK"
                }
            ],
            "enderecos": [
                {
                    "rua": "RUA",
                    "cidade": "CIDADE",
                    "estado": "ESTADO",
                    "pais": "PAIS"
                }
            ],
            "emails": [
                {
                    "email": "EMAIL",
                    "tipo": "WORK"
                }
            ],
            "data_nascimento": "ANO-MES-DIA"
        }
    ]
}

Marcar mensagem como lida

Mensagem de Texto

Ao receber um webhook de mensagens indicando uma mensagem recebida, você pode usar o message_id para marcar a mensagem como lida.

{
    "message_id": "wamid.HBgNNTUyMTk5NjExMTA4MxUCABIYFDNBMTQ3NjdBRTU1NDNEQkYxNzBDAA=="
}
Você pode exibir um indicador de digitação para que o usuário do WhatsApp saiba que você está preparando uma resposta. Essa é uma boa prática se você levar alguns segundos para responder.

Mensagem de Texto

O indicador de digitação será desativado assim que você responder ou após 25 segundos, o que ocorrer primeiro. Para evitar uma experiência ruim para o usuário, exiba o indicador de digitação apenas se você for responder.

{  
  "message_id": "wamid.HBgNNTUyMTk5ODUxMTMyNBUCABIYIEFDMUQ4QkQzNjg0QjE1MzZCNzMwQTk1ODNBMEI3NUM2AA==",
  "typing_indicator": {
    "type": "text"
  }
}

4. Respostas contextuais

As respostas contextuais são uma forma especial de responder a mensagens de usuários do WhatsApp. Ao citar a mensagem anterior em um balão, a resposta contextual deixa claro qual mensagem está sendo respondida:

Respostas contextuais

É possível enviar qualquer tipo de mensagem de retorno (exceto mensagens de reação) como resposta contextual.

Limitações

A bolha contextual não aparecerá acima da mensagem entregue se:

  • A mensagem anterior tiver sido excluída ou movida para o armazenamento de longo prazo. As mensagens são normalmente movidas para esse armazenamento após 30 dias, a menos que você tenha habilitado o armazenamento local;
  • Você tiver respondido com áudio, imagem ou vídeo, e o usuário do WhatsApp estiver executando o KaiOS;
  • Você usar o cliente do WhatsApp para responder com uma mensagem do tipo push-to-talk, e o usuário do WhatsApp estiver executando o KaiOS;
  • Você responder com um modelo de mensagem.

Para inclusão do contexto é necessário incluir o parâmetro message_id no corpo da mensagem.

Exemplo: 

{ 
    "destinatario": {{Destinatario}},    
    "message_id": "wamid.HBgNNTUyMTk5ODUxMTMyNBUCABIYIEVGRUEzQkM0N0IxQjI2MkNBRjlFQzU0RENDQTJDOTg1AA==",    
    "preview_url": false, 
    "body": "Mensagem de retorno com contexto" 
}

5. Quarto passo - Solicitar envio de mensagens de retorno

Para solicitar o envio de mensagens de retorno deve-se fazer uma requisição HTTP POST para o endpoint específico para cada tipo de mensagem, enviando o payload no corpo da requisição, conforme exemplo abaixo usando curl.

URI

Tipo: Texto
URI: https://api.whatsapp.serpro.gov.br/client/{fromPhoneNumberId}/v2/requisicao/mensagem/texto
Método: POST

Tipo: Media
URI:https://api.whatsapp.serpro.gov.br/client/{fromPhoneNumberId}/v2/requisicao/mensagem/media
Método: POST

Tipo: Reação
URI: https://api.whatsapp.serpro.gov.br/client/{fromPhoneNumberId}/v2/requisicao/mensagem/reacao
Método: POST

Tipo: Botôes de resposta
URI: https://api.whatsapp.serpro.gov.br/client/{fromPhoneNumberId}/v2/requisicao/mensagem/interativa-botoes
Método: POST

Tipo: Lista
URI: https://api.whatsapp.serpro.gov.br/client/{fromPhoneNumberId}/v2/requisicao/mensagem/interativa-lista
Método: POST

Tipo: Localização
URI: https://api.whatsapp.serpro.gov.br/client/{fromPhoneNumberId}/v2/requisicao/mensagem/localizacao
Método: POST

Tipo: Contatos
URI: https://api.whatsapp.serpro.gov.br/client/{fromPhoneNumberId}/v2/requisicao/mensagem/contatos
Método: POST

Tipo: Marcar mensagem como lida
URI: https://api.whatsapp.serpro.gov.br/client/{fromPhoneNumberId}/v2/requisicao/informacao-de-leitura
Método: POST

Tipo: Botão URL
URI: https://api.whatsapp.serpro.gov.br/client/{fromPhoneNumberId}/v2/requisicao/interativa-url
Método: POST

Tipo: Solicitação localização atual
URI: https://api.whatsapp.serpro.gov.br/client/{fromPhoneNumberId}/v2/requisicao/interativa-localizacao
Método: POST

FROM_PHONE_NUMBER_ID

Este campo deve ser o mesmo informado no client_id na geração do token.

Exemplo com curl

curl --request POST \
  --url https://api.whatsapp.serpro.gov.br/client/{fromPhoneNumberId}/v2/requisicao/mensagem/texto \
  --header 'VALOR DO TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "destinatario": "CONTATO",
    "preview_url": false,
    "body": "MENSAGEM_TEXTO"
}'

6. Quinto passo - Resultado da solicitação de envio de mensagens de retorno

A resposta do serviço de envio da mensagem de retorno é um objeto json contendo três informações, conforme exemplo abaixo:

Este exemplo ilustra uma resposta com sucesso na internalização da solicitação de envio de mensagens de retorno.

{
    "id": "55b54c8e-fa26-444d-b806-e7f08f2d4fc0",
    "acoes": [
        {
            "rel": "status",
            "uri": "#/client/100872459478491/v2/requisicao/55b54c8e-fa26-444d-b806-e7f08f2d4fc0",
            "method": "GET"
        }
    ]
}

7. Sexto passo - Consultar status da solicitação de envio de mensagens de retorno

Em caso de sucesso no requisição de envio de mensagens de retorno o próximo passo é consultar o status do envio das mensagens, conforme descrito no guia Como consultar status de envio de mensagens.