API de Nuvem

Componentes de conversa

Os componentes de conversa são recursos de bate-papo que podem ser habilitados em números de telefone comercial. Eles facilitam a interação dos usuários do WhatsApp com sua empresa. Você pode configurar comandos fáceis de usar, disponibilizar quebra-gelos tocáveis e saudar os novos usuários com uma mensagem de boas-vindas.

Limitações

Se um usuário do WhatsApp tocar em um link universal (ou seja, um link wa.me) configurado com texto predefinido, as interfaces do usuário para quebra-gelos serão ignoradas automaticamente.

Configurar via Gerenciador do WhatsApp

Você pode configurar esses recursos no Gerenciador do WhatsApp em números da sua escolha:

  1. Acesse o painel Meus apps no site Meta for Developers.
  2. Selecione o app e clique em Configurações dentro de WhatsApp no painel esquerdo.
  3. Em Telefones, selecione Gerenciar telefones.
  4. À direita do número de telefone a ser configurado, selecione o ícone de engrenagem sob Configurações.
  5. Selecione Automações.
  6. Acesse e configure os componentes de conversa.

Os provedores de soluções podem configurar esses recursos para os clientes se tiverem acesso à respectiva conta do WhatsApp Business no Gerenciador do WhatsApp.

Mensagens de boas-vindas

É possível receber uma notificação pelo webhook sempre que um usuário do WhatsApp iniciar um bate-papo com você pela primeira vez. Isso pode ser útil caso você queira responder a esses usuários com uma mensagem especial de boas-vindas de sua autoria.

As mensagens de boas-vindas são ótimas para interações de serviço, como suporte ou atendimento ao cliente. Por exemplo, é possível adicionar um botão do WhatsApp ao seu app ou site. Ao tocar no botão, os usuários serão redirecionados para o WhatsApp, onde receberão uma mensagem de boas-vindas que fornece contexto sobre como interagir com você.

Se esse recurso estiver habilitado e um usuário enviar uma mensagem para você, o cliente do WhatsApp verificará se há mensagens antigas trocadas entre esse usuário e seu número de telefone comercial. Caso não exista nenhuma conversa registrada, o cliente disparará um webhook messages com type definido como request_welcome. Você poderá então responder ao usuário com a mensagem de boas-vindas de sua autoria.

O webhook request_welcome aciona a janela de atendimento ao cliente, permitindo que a empresa envie mensagens em formato livre para responder aos clientes.

Carga do webhook

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_NAME>"
                },
                "wa_id": "<WHATSAPP_USER_ID>"
              }
            ],
            "messages": [
              {
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<TIMESTAMP>",
                "type": "request_welcome"  // Indicates first time message from WhatsApp user
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Quebra-gelos

Os quebra-gelos são textos tocáveis personalizados que aparecem em um tópico da mensagem na primeira vez que você conversa com um usuário. Por exemplo, "Planeje uma viagem" ou "Monte um plano de treinos".

Os quebra-gelos são ótimos para interações de serviço, como suporte ou atendimento ao cliente. Por exemplo, é possível adicionar um botão do WhatsApp ao seu app ou site. Ao tocar no botão, os usuários serão redirecionados para o WhatsApp, onde poderão escolher um item de um conjunto de comandos personalizados, que fornecem contexto sobre como interagir com você.

É possível configurar até 4 quebra-gelos em um número de telefone comercial. Cada quebra-gelo pode ter no máximo 80 caracteres. Não há compatibilidade com emojis.

Quando um usuário toca em um quebra-gelo, essa ação dispara um webhook de mensagem recebida padrão com a string do quebra-gelo atribuída à propriedade body na carga. Se o usuário tentar enviar uma mensagem a você em vez de tocar em um quebra-gelo, o teclado será exibido como uma sobreposição, mas poderá ser ignorado para mostrar o menu de quebra-gelos novamente.

Se um usuários do WhatsApp tocar em um link universal (wa.me ou api.whatsapp.com) configurado com texto predefinido, as interfaces do usuário para quebra-gelos serão ignoradas automaticamente.

Carga do webhook

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_NAME>"
                },
                "wa_id": "<WHATSAPP_USER_ID>"
              }
            ],
            "messages": [
              {
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<TIMESTAMP>",
                "text": {
                  "body": "Plan a trip"
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Comandos

Os comandos são strings de texto que aparecem quando os usuários do WhatsApp digitam uma barra em um tópico da conversa com sua empresa.

Eles são compostos pelo comando em si e uma dica, que dá ao usuário uma ideia do que pode acontecer ao usar o recurso. Por exemplo, você pode definir o comando:

/imagine - Create images using a text prompt

Quando o usuário do WhatsApp digitar "/imagine uma corrida de carros em Marte", essa ação disparará um webhook de mensagem recebida com essa string de texto exata atribuída à propriedade body. Assim, você pode gerar e retornar uma imagem de uma corrida de carros em Marte.

É possível definir até 30 comandos. Há um limite máximo de 32 caracteres para cada comando e de 256 caracteres para cada dica. Não há compatibilidade com emojis.

Carga do webhook

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_NAME>"
                },
                "wa_id": "<WHATSAPP_USER_ID>"
              }
            ],
            "messages": [
              {
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<TIMESTAMP>",
                "text": {
                  "body": "/imagine cars racing on Mars"
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Configurar via API

Com a API, é possível configurar componentes de conversa e visualizar valores configurados.

A API de Componentes de Conversa tem dois pontos de extremidade:

POST </PHONE_NUMBER_ID>/conversational_automation, usado para configurar componentes de conversa em um número de telefone específico.

GET /<PHONE_NUMBER_ID>/conversational_automation, que retorna os valores atuais de campos de prompt, comandos e enable_welcome_message em um número de telefone específico.

Configurar componentes conversacionais via API

Você pode configurar componentes de conversa em um número de telefone específico fazendo uma chamada ao ponto de extremidade POST.

Sintaxe da solicitação

// Enable or disable the Welcome Message for the given phone number ID
POST /<PHONE_NUMBER_ID>/conversational_automation?enable_welcome_message=<ENABLE_DISABLE>

// Configure Commands with names and descriptions
POST /<PHONE_NUMBER_ID>/conversational_automation?commands=<COMMAND_LIST>

// Configure Prompts
POST /<PHONE_NUMBER_ID>/conversational_automation?prompts=<PROMPT>

Propriedades do corpo


Espaço reservadoDescriçãoExemplo de valor

<PHONE_NUMBER_ID>

Número inteiro

Obrigatório.


A identificação do número de telefone no WhatsApp Business.

+12784358810

<ENABLE_DISABLE>

Booleano

Opcional.


Um booliano para habilitar ou desabilitar a mensagem de boas-vindas no número de telefone.


true

<COMMAND_LIST>

JSON

Opcional.


Uma lista de comandos a serem configurados.


"commands": {
     "command_name": "generate"
     "command_description": "Create a new image",
     “command_name”: “rethink”
     “command_description”: “Generate new images from existing images”,
}

<PROMPTS>

Lista de string

Opcional.


Os prompts a serem configurados.


"prompts": ["Book a flight","plan a vacation"]

Exemplo de solicitação

   curl -X POST \
 'https://graph.facebook.com/v19.0/PHONE_NUMBER_ID/conversational_automation' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
   "enable_welcome_message": true/false,
   "commands": [
     {
       "command_name": "tickets",
       "command_description": "Book flight tickets",
     },
     {
       "command_name": "hotel",
       "command_description": "Book hotel",
     }
   ],
 "prompts": ["Book a flight","plan a vacation"]
}'

Exemplo de resposta

{
  "success": true
}

Verificar a configuração atual via API

Você pode visualizar a configuração atual dos componentes de conversa em um número de telefone específico fazendo uma chamada ao ponto de extremidade GET.

Sintaxe da solicitação

GET  /<PHONE_NUMBER_ID>?fields=conversational_automation

Exemplo de resposta

{
  "conversational_automation": {
    "enable_welcome_message": true
    "prompts": [
      "Find the best hotels in the area",
      "Find deals on rental cars"
    ],
    "commands": [
      {
        "command_name": "tickets",
        "command_description": "Book flight tickets",
      },
      {
        "command_name": "hotel",
        "command_description": "Book hotel",
      }
    ],
  }
  "id": "123456"
}

Testes

Para testar os componentes de conversa que já foram configurados, abra o cliente do WhatsApp e inicie um bate-papo com seu número de telefone comercial.

Para mensagens de boas-vindas e quebra-gelos, se você já tiver trocado mensagens com o número de telefone comercial, exclua a conversa no bate-papo primeiro:

  1. Abra a conversa no cliente do WhatsApp.
  2. Toque no perfil do número de telefone comercial.
  3. Toque em Limpar conversa > Limpar todas as mensagens.
  4. Excluir bate-papo.
  5. Inicie uma nova conversa de bate-papo com essa empresa.

Você poderá então enviar uma mensagem ao número de telefone comercial, o que deve disparar o webhook request_welcome.