As mensagens de endereço são mensagens interativas com quatro partes principais: header, body, footer e action. Dentro do componente de ação, a empresa especifica o nome “address_message” e os parâmetros relevantes.

A tabela abaixo apresenta os campos compatíveis com as mensagens de endereço.

Nome do campo	Etiqueta de exibição	Tipo de entrada	Países compatíveis	Limitações
`name`	Nome	text	Índia	Nenhum
`phone_number`	Número de telefone	tel	Índia	Somente números de telefone válidos
`in_pin_code`	Código PIN	text	Índia	Comprimento máximo: 6
`house_number`	Número do apartamento/casa	text	Índia	Nenhum
`floor_number`	Número do andar	text	Índia	Nenhum
`tower_number`	Número da torre	text	Índia	Nenhum
`building_name`	Nome do edifício/apartamento	text	Índia	Nenhum
`address`	Endereço	text	Índia	Nenhum
`landmark_area`	Ponto de referência/área	text	Índia	Nenhum
`city`	Cidade	text	Índia	Nenhum
`state`	Estado	text	Índia	Nenhum

Exemplo de chamada de API

Veja um exemplo de chamada de API para a mensagem de endereço. O atributo country é um campo obrigatório nos parâmetros de ação. Se ele não for incluído, ocorrerá um erro de validação.

curl -X  POST \
'https://graph.facebook.com/<API_VERSION>/<FROM_PHONE_NUMBER_ID>/messages' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<PHONE_NUMBER>",
  "type": "interactive",
  "interactive": {
    "type": "address_message",
    "body": {
      "text": "Thanks for your order! Tell us what address you’d like this order delivered to."
    },
    "action": {
      "name": "address_message",
      "parameters": {
        "country": "<COUNTRY_ISO_CODE>"
      }
    }
  }
}'

Solução de erros

Se o código de área do número de telefone do país em questão não estiver correto, as empresas não conseguirão solicitar a mensagem de endereço ao destinatário. Por exemplo, as empresas não conseguirão solicitar uma mensagem de endereço a um destinatário cujo país seja "Índia", mas cujo número de telefone tenha código de área "65".

Após o envio da mensagem de endereço, a empresa aguarda o preenchimento e o envio do endereço pelo usuário. O endereço inserido pelo usuário é compartilhado por meio do webhook registrado no processo de configuração.

Etapas da mensagem de endereço

Estas são as etapas da mensagem de endereço:

A empresa envia uma mensagem de endereço ao usuário com o nome de ação address_message

O usuário interage com a mensagem clicando na CTA, que exibe a tela da mensagem de endereço. O usuário preenche o endereço e envia o formulário

Depois disso, o parceiro recebe uma notificação de webhook com os detalhes do endereço enviado pelo usuário

Exemplo de mensagem de endereço na Índia

O diagrama de sequência a seguir mostra um fluxo de integração típico de uma mensagem de endereço.

Parâmetros de ação adicionais

A empresa pode passar atributos adicionais (por exemplo, values, validation_errors ou saved_addresses) como parte dos parâmetros de ação interativos. Confira abaixo mais informações sobre o uso de cada um deles.

Parâmetro de ação	Uso
`values`	As empresas preenchem automaticamente os campos de endereço (por exemplo, preenchem automaticamente o campo "city" com "Índia")
`saved_addresses`	Para empresas, é possível transmitir endereços salvos anteriormente associados ao usuário. Para usuários, eles terão a opção de escolher o endereço salvo em vez de preenchê-lo manualmente
`validation_errors`	As empresas podem indicar erros nos campos de endereço e o WhatsApp impedirá que o usuário envie o formulário antes que os problemas sejam corrigidos.

Enviar mensagem de endereço para um usuário

Faça uma chamada POST a /PHONE_NUMBER_ID/messages usando a API do WhatsApp para enviar mensagens de endereço criptografadas de ponta a ponta para o usuário:

curl -X  POST \
'https://graph.facebook.com/<API_VERSION>/<FROM_PHONE_NUMBER_ID>/messages' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<PHONE_NUMBER>",
  "type": "interactive",
  "interactive": {
    "type": "address_message",
    "body": {
      "text": "Thanks for your order! Tell us what address you’d like this order delivered to."
    },
    "action": {
      "name": "address_message",
      "parameters": "JSON Payload"
    }
  }
}'

Para enviar uma mensagem de endereço sem endereços salvos, o WhatsApp exibirá ao usuário ou à empresa um formulário de endereço a ser preenchido com um novo endereço.

curl -X  POST \
'https://graph.facebook.com/<API_VERSION>/<FROM_PHONE_NUMBER_ID>/messages' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+91xxxxxxxxxx",
  "type": "interactive",
  "interactive": {
    "type": "address_message",
    "body": {
      "text": "Thanks for your order! Tell us what address you’d like this order delivered to."
    },
    "action": {
      "name": "address_message",
      "parameters": {
        "country": "IN",
        "values": {
          "name": "<CUSTOMER_NAME>",
          "phone_number": "+91xxxxxxxxxx"
        }
      }
    }
  }
}'

Para enviar uma mensagem de endereço com endereços salvos, o WhatsApp apresentará ao usuário ou à empresa a opção de selecionar um dos endereços salvos ou adicionar um novo. Os usuários podem ignorar o endereço salvo e inserir um novo.

curl -X  POST \
'https://graph.facebook.com/<API_VERSION>/<FROM_PHONE_NUMBER_ID>/messages' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "91xxxxxxxxxx",
  "type": "interactive",
  "interactive": {
    "type": "address_message",
    "body": {
      "text": "Thanks for your order! Tell us what address you’d like this order delivered to."
    },
    "action": {
      "name": "address_message",
      "parameters": {
        "country": "IN",
        "saved_addresses": [
          {
            "id": "address1",
            "value": {
              "name": "<CUSTOMER_NAME>",
              "phone_number": "+91xxxxxxxxxx",
              "in_pin_code": "400063",
              "floor_number": "8",
              "building_name": "",
              "address": "Wing A, Cello Triumph,IB Patel Rd",
              "landmark_area": "Goregaon",
              "city": "Mumbai"
            }
          }
        ]
      }
    }
  }
}'

Verificar a resposta

Uma resposta bem-sucedida inclui um objeto messages com a identificação da mensagem recém-criada.

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "<PHONE_NUMBER>",
      "wa_id": "<WHATSAPP_ID>"
    }
  ],
  "messages": [
    {
      "id": "wamid.ID"
    }
  ]
}

Respostas com falha conterão uma mensagem de erro. Consulte Mensagens de erro e status para mais informações.

Enviar uma mensagem de endereço com erros de validação

Uma mensagem de endereço será reenviada ao usuário caso ocorra um erro de validação no servidor da empresa. A empresa deverá devolver o conjunto de valores previamente inseridos pelo usuário com os respectivos erros de validação de cada campo inválido, conforme mostrado no exemplo de carga abaixo.

curl -X  POST \
'https://graph.facebook.com/<API_VERSION>/<FROM_PHONE_NUMBER_ID>/messages' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d
'{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "91xxxxxxxxxx",
  "type": "interactive",
  "interactive": {
    "type": "address_message",
    "body": {
      "text": "Thanks for your order! Tell us what address you’d like this order delivered to."
    },
    "action": {
      "name": "address_message",
      "parameters": {
          "country": "IN",
          "values": {
             "name": "CUSTOMER_NAME",
             "phone_number": "+91xxxxxxxxxx",
             "in_pin_code": "666666",
             "address": "Some other location",
             "city": "Delhi"
          },
          "validation_errors": {
             "in_pin_code": "We could not locate this pin code."
          }
       }
    }
  }
}'

Receber notificações sobre o envio de endereços

As empresas receberão notificações de envio de endereço por meio de webhooks, como no exemplo abaixo.

{
  "messages": [
    {
      "id": "gBGGFlAwCWFvAgmrzrKijase8yA",
      "from": "<PHONE_NUMBER>",
      "interactive": {
        "type": "interactive",
        "action": "address_message",
        "nfm_reply": {
          "name": "address_message",
          "response_json": "<response_json from client>",
          "body": "<body text from client>"
        },
        "timestamp": "1670394125"
      }
    }
  ]
}

A notificação de webhook tem os valores a seguir.

Nome do campo	Tipo	Descrição
`interactive`	Objeto	Contém a resposta do cliente
`type`	String	Seria `nfm_reply`, indicando que se trata de uma resposta do fluxo nativo (NFM) do cliente
`nfm_reply`	Objeto	Contém os dados recebidos do cliente
`response_json`	String	Os valores dos campos de endereço preenchidos pelo usuário no formato JSON que sempre estão presentes
`body` (opcional)	String	O corpo do texto do cliente, o que o usuário vê
`name` (opcional)	String	Seria `address_message`, indicando o tipo de resposta de ação NFM do cliente

Confira abaixo uma resposta do tipo NFM enviada na solicitação de mensagem de endereço na Índia.

{
  "messages": [
    {
      "context": {
        "from": "FROM_PHONE_NUMBER_ID",
        "id": "wamid.HBgLMTIwNjU1NTAxMDcVAgARGBI3NjNFN0U5QzMzNDlCQjY0M0QA"
      },
      "from": "<PHONE_NUMBER>",
      "id": "wamid.HBgLMTIwNjU1NTAxMDcVAgASGCA5RDhBNENEMEQ3RENEOEEzMEI0RUExRDczN0I1NThFQwA=",
      "timestamp": "1671498855",
      "type": "interactive",
      "interactive": {
        "type": "nfm_reply",
        "nfm_reply": {
          "response_json": "{\"saved_address_id\":\"address1\",\"values\":{\"in_pin_code\":\"400063\",\"building_name\":\"\",\"landmark_area\":\"Goregaon\",\"address\":\"Wing A, Cello Triumph, IB Patel Rd\",\"city\":\"Mumbai\",\"name\":\"CUSTOMER_NAME\",\"phone_number\":\"+91xxxxxxxxxx\",\"floor_number\":\"8\"}}",
          "body": "CUSTOMER_NAME\n +91xxxxxxxxxx\n 400063, Goregaon, Wing A, Cello Triumph,IB Patel Rd, Mumbai, 8",
          "name": "address_message"
        }
      }
    }
  ]
}

Recurso não compatível

Caso o cliente não ofereça suporte para address_message, as mensagens serão removidas silenciosamente. Além disso, a empresa receberá uma mensagem de erro por meio do webhook. Confira abaixo a notificação enviada por webhook:

{
  "statuses": [
    {
      "errors": [
        {
          "code": 1026,
          "href": "/docs/whatsapp/api/errors",
          "title": "Receiver Incapable"
        }
      ],
      "id": "gBGGFlAwCWFvAgkyHMGKnRu4JeA",
      "message": {
        "recipient_id": "+91xxxxxxxxxx"
      },
      "recipient_id": "91xxxxxxxxxx",
      "status": "failed",
      "timestamp": "1670394125",
      "type": "message"
    }
  ]
}

Você achou esta página útil?