Trabalhando com mensagens interativas do WhatsApp

As Mensagens Interativas são um recurso do WhatsApp para Empresas. O Messages API da Vonage permite que você aproveite esse recurso por meio do uso de seus pontos de extremidade da API e webhooks.

Fluxo básico do aplicativo

O fluxo básico para trabalhar com as Mensagens Interativas do WhatsApp é o seguinte:

Envie um POST solicitação à /v1/messages ponto de extremidade. O corpo da solicitação deve conter os dados JSON necessários, com o channel definir como whatsapp e o message_type definir como custom. O custom o campo deve ser preenchido com um valor devidamente formatado objeto personalizado. A estrutura real do objeto personalizado varia de acordo com o tipo de mensagem interativa que está sendo enviada (por exemplo, botão de resposta ou lista).
O tipo de mensagem apropriado será então exibido no chat do WhatsApp especificado. O cliente poderá interagir com a mensagem, por exemplo, clicando em um botão de resposta ou selecionando uma opção de uma lista (dependendo do tipo de mensagem). A Messages API informará você sobre essa interação por meio de um callback com o conteúdo da mensagem, utilizando uma configuração pré-definida webhook de mensagem recebida
Com base no conteúdo da carga útil recebida por meio do callback, você pode realizar as ações que julgar adequadas, como enviar uma nova solicitação.

NOTA: O webhook de mensagens recebidas para receber os callbacks deve ser criado como parte de um Aplicativo Vonage

Configurando seu aplicativo

Você pode configurar seu aplicativo da Vonage de várias maneiras, como, por exemplo, por meio do Painel de controle, por meio de uma chamada à API de Aplicativos ou pela CLI da Vonage. A seguir, descrevemos como configurar um aplicativo pelo Painel de Controle.

Crie um novo aplicativo na seção “Seus aplicativos” (atribuindo-lhe um nome adequado, etc.)
Na seção “Recursos”, ative a opção “Mensagens”
Ao ativar as mensagens, devem ser exibidos campos para webhooks de entrada e de status. Defina o webhook de entrada com a URL na qual você deseja receber os callbacks das Mensagens Interativas do WhatsApp.
Defina a versão da Messages API como v1 usando o menu suspenso
Clique em “Gerar novo pedido”
Assim que o aplicativo for gerado, será exibida uma aba “Vincular canais sociais”. Nessa aba, você poderá vincular seu número do WhatsApp Business

UI for Messages webhook and version settings

NOTA: Os aplicativos da Vonage exigem o uso de JWT (JSON Web Tokens) para autenticar solicitações à API; ou seja, a autenticação HTTP Basic não é uma opção ao usar a Messages API v1 com webhooks. Saiba mais sobre os JWTs.

Mensagens interativas: exemplos

A estrutura do objeto JSON varia de acordo com o tipo de mensagem interativa e também de mensagem para mensagem. No entanto, como regra geral, você precisará incluir o from e to números, um channel chave definida como whatsapp, e um message_type de custom. Em seguida, você precisará definir um custom chave, cujo valor é um objeto personalizado. O objeto personalizado deve ter um type chave de interactive, e um interactive chave, cujo valor é, por sua vez, um objeto.

O interactive O objeto define a mensagem interativa. Ele deve ter um type chave definida como button ou list, e geralmente também incluirá quatro partes principais: header, body, footer, e action. O action determina os elementos interativos da mensagem, como botões ou opções de lista.

Botões de resposta: Exemplo

Aqui está um exemplo do corpo de uma solicitação para enviar uma mensagem interativa no WhatsApp com três botões de resposta:

{
"from": "YOUR_WABA_NUMBER",
"to": "USERS_NUMBER",
"channel": "whatsapp",
"message_type": "custom",
"custom": {
    "type": "interactive",
    "interactive": {
      "type": "button",
      "header": {
          "type": "text",
          "text": "Delivery time"
      },
      "body": {
          "text": "Which time would you like us to deliver your order at?"
      },
      "footer": {
          "text": "Please allow 15 mins either side of your chosen time"
      },
      "action": {
          "buttons": [
              {
                  "type": "reply",
                  "reply": {
                      "id": "slot-1",
                      "title": "15:00"
                  }
              },
              {
                  "type": "reply",
                  "reply": {
                      "id": "slot-2",
                      "title": "16:30"
                  }
              },
              {
                  "type": "reply",
                  "reply": {
                      "id": "slot-3",
                      "title": "17:15"
                  }
              }
          ]
      }
    }
  }
}

A mensagem resultante ficará assim:

Na interface do WhatsApp, a mensagem muda de aparência como se o usuário tivesse respondido a ela com o texto de um dos botões. Além disso, esse botão fica indisponível para clicar, enquanto os demais permanecem disponíveis.

Se o usuário selecionar a primeira opção, você receberá, em seguida, algo como isto por meio do webhook de entrada:

{
    "to": "YOUR_WABA_NUMBER",
    "from": "USERS_NUMBER",
    "channel": "whatsapp",
    "message_uuid": "00000000-0000-0000-0000-000000000000",
    "timestamp": "2021-08-10T00:00:00Z",
    "message_type": "reply",
    "reply": {
        "id": "slot-1",
        "title": "15:00"
    }
}

Listar mensagens: Exemplo

Aqui está um exemplo do corpo de uma solicitação para o envio de uma mensagem interativa do WhatsApp com quatro opções, organizadas em duas seções:

{
"from": "YOUR_WABA_NUMBER",
   "to": "USERS_NUMBER",
   "channel": "whatsapp",
   "message_type": "custom",
   "custom": {
    "type": "interactive",
    "interactive": {
      "type": "list",
      "header": {
        "type": "text",
        "text": "Select which pill you would like "
      },
      "body": {
        "text": "You will be presented with a list of options"
      },
      "footer": {
        "text": "There are no wrong choices"
      },
      "action": {
        "button": "Select",
        "sections": [
          {
            "title": "Section A - pills",
            "rows": [
              {
                "id": "row1",
                "title": "Red",
                "description": "Take the red pill"
              },
              {
                "id": "row2",
                "title": "Blue",
                "description": "Take the blue pill"
              },
              {
                "id": "row3",
                "title": "Green",
                "description": "Take the green pill"
              }
            ]
          },
          {
            "title": "Section B - no pills",
            "rows": [
              {
                "id": "row4",
                "title": "Nothing",
                "description": "Do not take a pill"
              }
            ]
          }
        ]
      }
    }
  }
}

A mensagem resultante ficará assim:

Quando o usuário clica no botão “Selecionar”, as opções disponíveis são exibidas. Em seguida, o usuário pode selecionar uma opção (no máximo) e clicar no botão “Enviar”.

A aparência da mensagem muda como se o usuário tivesse respondido à mensagem com o texto dos campos “título” e “descrição” da solicitação da API.

Se o cliente selecionasse a primeira opção da Seção A, você receberia, em seguida, algo como isto por meio do webhook de entrada:

{
    "to": "YOUR_WABA_NUMBER",
    "from": "USERS_NUMBER",
    "channel": "whatsapp",
    "message_uuid": "00000000-0000-0000-0000-000000000000",
    "timestamp": "2021-08-10T00:00:00Z",
    "message_type": "reply",
    "reply": {
        "id": "row1",
        "title": "Red",
        "description": "Take the red pill"
    }
}

Mais informações

Guia para desenvolvedores do WhatsApp: Envio de mensagens interativas