Contactos

/v1/contacts

Usa el nodo contacts para administrar los usuarios de WhatsApp de tu base de datos mediante una validación previa al envío de mensajes y una verificación de su identidad con hashes de identidad.

Con el nodo contacts puedes hacer lo siguiente:

• Verificar que un número de teléfono de la base de datos pertenece a una cuenta válida de WhatsApp. Debes asegurarte de que el valor de status sea valid para poder enviar mensajes a un usuario.
• Obtener el identificador de WhatsApp de un número de teléfono. Los identificadores de WhatsApp son necesarios para enviar mensajes y notificaciones de usuario.

Antes de empezar

Debes presentar una opción a los clientes para que acepten participar en conversaciones de WhatsApp con tu empresa. Tu empresa es responsable de mantener este proceso de consentimiento. Cuando el cliente otorgue su consentimiento, usa el nodo contacts para validar el número registrado. Consulta Obtener el consentimiento para WhatsApp a fin de obtener más información.

Limitaciones

• Utiliza este extremo para verificar que un número de teléfono de la base de datos de una empresa pertenece a una cuenta válida de WhatsApp.
• El número de llamadas no debe superar el número de mensajes que envía el número de teléfono.

Cumplimiento

Si una empresa usa el extremo de forma indebida, se llevarán a cabo las acciones siguientes:

• Todos los administradores enumerados en Business Manager recibirán una advertencia inicial por correo electrónico si se sospecha un uso indebido.
• Una empresa dispondrá de siete días tras la recepción de la advertencia para corregir el comportamiento.
• Si una vez transcurridos siete días no se han ajustado las llamadas, el número de teléfono se inhabilitará de forma permanente.

Recomendaciones

Recomendamos comprobar los contactos antes de enviarles mensajes. Sin embargo, no es necesario que lo hagas cuando respondas a mensajes entrantes de clientes, ya que puedes responder de inmediato con el campo wa_id proporcionado. No existe ningún coste adicional, ya que los resultados están almacenados en caché.

Crear

Antes de enviar mensajes a los usuarios que hayan otorgado su consentimiento, envía una solicitud POST al extremo /v1/contacts para crear una solicitud de validación del usuario de la cuenta de WhatsApp. En la llamada, incluye una lista de los números de teléfono que quieras validar.

Ejemplo

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
}

Recibirás una respuesta con el valor actual de status de los números solicitados y sus identificadores de 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"
  }
}

Guarda los identificadores de WhatsApp de los números que devuelvan el campo status establecido en valid. Los usuarios válidos son aquellos que tienen una cuenta de WhatsApp. Usa los identificadores de WhatsApp para enviar mensajes y notificaciones.

Repite estos pasos de manera regular para administrar tu lista de usuarios válidos. Los resultados se almacenan en caché en la base de datos del cliente de la API local de WhatsApp Business durante siete días.

Parámetros

Los parámetros siguientes son compatibles con las llamadas POST a /v1/contacts:

Perímetros

Los perímetros siguientes están conectados a este nodo:

Bloqueo

Hay dos opciones para el parámetro blocking: no_wait y wait. Si el parámetro blocking no se especifica en una llamada, el valor predeterminado es no_wait.

El parámetro blocking determina si la solicitud debe esperar a que se termine el procesamiento (síncrona) o no (asíncrona).

Formatos de número de teléfono

Los números de teléfono de la solicitud contacts pueden estar en cualquier formato que se pueda marcar.

A continuación, se incluyen algunos ejemplos en los que se muestra este comportamiento. En ellos, se supone que el cliente de la API local de WhatsApp Business está registrado con un número de teléfono de la India (es decir, el código de país es +91):

Campos devueltos

La carga útil de la respuesta de contacts contiene la misma matriz de números de teléfono enviada en la solicitud con las propiedades input, status y wa_id:

Junto con el estado processing, deberías ver el estado HTTP 200 OK.

Si se envía un mensaje de plantilla a un número de teléfono sin cuenta de WhatsApp, recibirás un mensaje de error en el que se indica “El usuario no es válido” con el código de error 1013.

Para otros errores en la respuesta, consulta Mensajes de error y de estado.

Bloquear contactos

El bloqueo se puede considerar una función defensiva para impedir que personas malintencionadas prosigan sus acciones nocivas. Para bloquear un contacto, tiene que haberte enviado un mensaje en las últimas 24 horas.

Ejemplo

Envía una llamada a la API a /v1/contacts/{phone_number}/block con un motivo para bloquear otra cuenta de WhatsApp.

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

Una respuesta correcta tiene el estado HTTP 200 y ningún objeto “errors”.

Las respuestas que no se completan correctamente tienen este aspecto:

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

Parámetros

Los parámetros siguientes son compatibles con las llamadas POST a /v1/contacts/{phone_number}/block:

Desbloquear contactos

Realiza esta llamada para desbloquear un contacto.

Ejemplo

Envía una llamada a la API a /v1/contacts/{phone_number}/unblock.

POST /v1/contacts/+16315551000/unblock

Una respuesta correcta tiene el estado HTTP 200 y ningún objeto “errors”.

Las respuestas que no se completan correctamente tienen este aspecto:

{   
    "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

Los parámetros siguientes son compatibles con las llamadas POST a /v1/contacts/{phone_number}/unblock:

Lista de bloqueo

Sigue los pasos siguientes para obtener una lista de los contactos bloqueados.

Ejemplo

Envía una llamada a la API a /v1/contacts/blocklist para recibir una lista paginada de los contactos bloqueados.

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

Recibirás una respuesta con una página de la lista de bloqueo junto con información sobre la paginación.

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

Parámetros

Los parámetros siguientes son compatibles con las llamadas GET a /v1/contacts/blocklist:

Informes

Los informes proporcionan señales cruciales para crear una solución preventiva contra personas malintencionadas. Para poder denunciar a un contacto, tiene que haberte enviado un mensaje en las últimas 24 horas.

Ejemplo

Envía una llamada a la API a /v1/contacts/{phone_number}/report con un motivo si bloqueas otra cuenta de 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"
}

Una respuesta correcta tiene el estado HTTP 200 y ningún objeto “errors”.

Las respuestas que no se completan correctamente tienen este aspecto:

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

Parámetros

Los parámetros siguientes son compatibles con las llamadas POST a /v1/contacts/{phone_number}/report: