Contatos

/v1/contacts

Use o nó contacts para gerenciar os usuários do WhatsApp no seu banco de dados. Para fazer isso, valide-os antes de enviar mensagens e verifique a identidade deles por meio de hashes de identidade.

Veja o que você pode fazer com o nó contacts:

• Verifique se um número de telefone no banco de dados pertence a uma conta do WhatsApp válida. É preciso garantir que o status seja valid antes de enviar mensagens a um usuário.
• Obtenha o ID do WhatsApp de um número de telefone. Os IDs do WhatsApp são necessários para enviar mensagens e notificações do usuário.

Antes de começar

Você precisa fornecer aos clientes a opção de ativar a comunicação no WhatsApp com sua empresa. Esse fluxo de ativação é mantido pela sua empresa. Depois que o cliente aceitar, use o nó contacts para validar o número registrado. Consulte Obter aceitação para o WhatsApp para mais informações.

Limitações

• Use esse ponto de extremidade para verificar se um número de telefone no banco de dados da empresa pertence a uma conta do WhatsApp válida.
• O número de chamadas não deve exceder a quantidade de mensagens que o telefone está enviando.

Monitoramento

Se uma empresa usar o ponto de extremidade de forma indevida, serão realizadas as seguintes ações:

• Todos os administradores do Gerenciador de Negócios receberão um aviso por email caso haja suspeita de uso indevido.
• Após o recebimento do email, a empresa terá 7 dias para ajustar o comportamento.
• Se as chamadas não forem ajustadas dentro desse prazo, o número de telefone será desabilitado permanentemente.

Recomendações

Recomendamos verificar os contatos antes de enviar mensagens. No entanto, você não precisa verificar os contatos ao responder às mensagens dos clientes, já que é possível fazer isso usando o wa_id fornecido. Não há custo adicional quando os resultados são armazenados em cache.

Criação

Antes de enviar mensagens a usuários que ativaram a comunicação, envie uma solicitação POST ao ponto de extremidade /v1/contacts para criar uma solicitação de validação do usuário da conta do WhatsApp. Na sua chamada, inclua a lista dos números de telefone que você quer validar.

Exemplo

POST /v1/contacts
{
  "blocking": "wait" | "no_wait",
  "contacts": [
  	"16315551000",
  	"+1 631 555 1001",
  	"6315551002",
  	"+1 (631) 555-1004",
  	"1-631-555-1005"
  ],
  "force_check": false | true
}

Você receberá uma resposta com o status atual dos números solicitados e os respectivos IDs do WhatsApp (wa_id):

{
  "contacts": [ {
    "wa_id": "16315551000",
    "input": "16315551000",
    "status": "valid"
  },
  {
    "wa_id": "16315551001",
    "input": "+1 631 555 1001",
    "status": "processing" # Only applicable when request is non-blocking
  },
  {
    "input": "6315551002",
    "status": "invalid"
  },
  {
    "input": "+163155588",
    "status": "failed"
  }
}

Salve os IDs do WhatsApp para números que retornaram o status de valid. Os usuários válidos são aqueles com uma conta do WhatsApp. Use os IDs do WhatsApp para enviar mensagens e notificações.

Repita essas etapas com frequência para gerenciar sua lista de usuários válidos. Os resultados são armazenados em cache no banco de dados do cliente da API Local do WhatsApp Business por 7 dias.

Parâmetros

Os parâmetros a seguir são compatíveis com as chamadas POST para /v1/contacts:

Bordas

As seguintes bordas estão relacionadas ao nó:

Bloqueio

Há duas opções para o parâmetro blocking: no_wait e wait. Se o parâmetro blocking não for especificado em uma chamada, ele será definido como no_wait por padrão.

O parâmetro blocking determina se a solicitação deve aguardar o processamento ser concluído (síncrono) ou não (assíncrono).

Formatos de números de telefone

Os números de telefone na solicitação contacts podem estar em qualquer formato discável.

Confira a seguir alguns exemplos que demonstram esse comportamento. Nestes casos, o cliente da API Local do WhatsApp Business está registrado com um número de telefone indiano (que tem o código do país +91):

Campos retornados

A carga da resposta contacts contém a mesma matriz de números de telefone enviada na solicitação com as propriedades input, status e wa_id:

Além do status processing, você verá um status HTTP de 200 OK.

Se um modelo de mensagem for enviado a um número de telefone que não tenha uma conta do WhatsApp, você receberá a mensagem de erro "User is not valid" com o código de erro 1013.

Caso a resposta retorne outros erros, consulte Mensagens de erro e status.

Como bloquear contatos

O bloqueio pode ser considerado um recurso de defesa para impedir que indivíduos mal-intencionados continuem executando ações prejudiciais. Para bloquear um contato, é preciso que você tenha recebido uma mensagem dele nas últimas 24 horas.

Exemplo

Envie uma chamada de API a /v1/contacts/{phone_number}/block com um motivo para o bloqueio de outra conta do WhatsApp.

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked"
}

A resposta bem-sucedida inclui o status HTTP 200 e não tem o objeto "errors".

A resposta com falha é semelhante a esta:

{   
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

Parâmetros

Os parâmetros a seguir são compatíveis com as chamadas POST para /v1/contacts/{phone_number}/block:

Como desbloquear contatos

Faça esta chamada para desbloquear um contato.

Exemplo

Envie uma chamada de API para /v1/contacts/{phone_number}/unblock.

POST /v1/contacts/+16315551000/unblock

A resposta bem-sucedida inclui o status HTTP 200 e não tem o objeto "errors".

A resposta com falha é semelhante a esta:

{   
    "errors": [
        {
            "code": 1009,
            "title": "Parameter value is not valid",
            "details": "Provided WhatsApp ID is not valid. Please provide a valid WhatsApp ID or a phone number with a country code"
        }
    ]
}

Parâmetros

Os parâmetros a seguir são compatíveis com as chamadas POST para /v1/contacts/{phone_number}/unblock:

Lista de bloqueio

Veja como obter uma lista dos seus contatos bloqueados.

Exemplo

Envie uma chamada de API para /v1/contacts/blocklist a fim de receber uma lista paginada dos seus contatos bloqueados.

GET /v1/contacts/blocklist?limit=10&offset=0

Você receberá uma resposta com uma página da sua lista de bloqueio e informações de paginação.

{
   "contacts": [
       {
           "wa_id": "16315551000@s.whatsapp.net"
       }
   ],
   "pagination": {
       "limit": 10,
       "offset": 0,
       "total": 1
   }
}

Parâmetros

Os parâmetros a seguir são compatíveis com chamadas GET para /v1/contacts/blocklist:

Geração de relatórios

Os relatórios fornecem sinais cruciais para criar uma solução preventiva contra indivíduos mal-intencionados. Para denunciar um contato, é preciso que você tenha recebido uma mensagem dele nas últimas 24 horas.

Exemplo

Envie uma chamada de API para /v1/contacts/{phone_number}/report incluindo um motivo caso você esteja bloqueando outra conta do WhatsApp.

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked",
   "block": "true | false optional boolean with default of false",
   "message_id": "message-id. Optional reported message id"
}

A resposta bem-sucedida inclui o status HTTP 200 e não tem o objeto "errors".

A resposta com falha é semelhante a esta:

{  
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

Parâmetros

Os parâmetros a seguir são compatíveis com as chamadas POST para /v1/contacts/{phone_number}/report: