Contactos

/v1/contacts

Usa el nodo contacts para administrar los usuarios de WhatsApp en tu base de datos validándolos antes de enviar mensajes y verifica la identidad de los usuarios con claves de identidad.

Con el nodo contacts puedes hacer lo siguiente:

• Verificar si un número de teléfono de tu base de datos pertenece a una cuenta de WhatsApp válida. Debes asegurarte de que la configuración de status sea valid para poder enviar un mensaje a un usuario.
• Obtener el identificador de WhatsApp de un número de teléfono. Se necesitan los identificadores de WhatsApp para enviar mensajes y notificaciones a usuarios.

Antes de empezar

Debes brindar a tus clientes la opción de suscribirse a las comunicaciones de WhatsApp con tu empresa. Tu empresa es la que administra el proceso de suscripción. Después de que un cliente se suscriba, usa el nodo contacts para validar el número registrado. Si quieres obtener más información, consulta Cómo conseguir que el usuario acepte recibir mensajes por WhatsApp.

Limitaciones

• Usa este punto de conexión para verificar si el número de teléfono de la base de datos de una empresa pertenece a una cuenta de WhatsApp válida.
• La cantidad de llamadas no debe superar a la cantidad de mensajes que se envían desde el número de teléfono.

Cumplimiento de normas

Si una empresa utiliza el punto de conexión de manera incorrecta, se tomarán las siguientes medidas:

• Todos los administradores que figuran en el administrador comercial recibirán una advertencia inicial por correo electrónico si hay sospechas de un uso indebido.
• La empresa tendrá siete días después de haber recibido la advertencia para modificar su comportamiento.
• Si después de este plazo las llamadas no se modificaron, el número de teléfono se inhabilitará de forma permanente.

Recomendaciones

La práctica recomendada es comprobar los contactos antes de enviar cada mensaje. Sin embargo, no hace falta comprobarlos para responder a un mensaje entrante de un cliente; basta con usar wa_id para responder el mensaje de inmediato. El almacenamiento en caché de los resultados no tiene ningún costo adicional.

Creación

Antes de enviar mensajes a usuarios que se hayan suscrito, envía una solicitud POST al punto de conexión /v1/contacts a fin de crear una solicitud de validación de usuario para la cuenta de WhatsApp. En la llamada, incluye una lista de números de teléfono que desees 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 status actual de los números solicitados y los 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 devuelva el parámetro status con el valor valid. Los usuarios válidos son aquellos que tienen una cuenta de WhatsApp. Utiliza los identificadores de WhatsApp para enviar mensajes y notificaciones.

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

Parámetros

Se admiten los siguientes parámetros en las llamadas POST a /v1/contacts:

Perímetros

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

Bloqueos

El parámetro blocking tiene dos opciones: no_wait y wait. Si el parámetro blocking no se especifica en una llamada, será no_wait de forma predeterminada.

El parámetro blocking determina si la solicitud debe esperar a que finalice el procesamiento (sincrónico) o no (asincrónico).

Formatos de número de teléfono

Los números de teléfono de la solicitud contacts pueden estar en cualquier formato que permita el marcado.

Aquí se proporcionan algunos ejemplos en los que se demuestra este comportamiento, suponiendo que el cliente de la API de instalaciones locales 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 respuesta de contacts incluye la misma matriz de números de teléfono que se envió en la solicitud con las propiedades input, status y wa_id.

Además del estado de processing, debes ver un estado HTTP de 200 OK.

Si se envía un mensaje de plantilla a un número de teléfono que no dispone de una cuenta de WhatsApp, recibirás un mensaje de error en el que se indicará "Usuario no válido" y el código de error 1013.

Si hay otros errores en la respuesta, consulta Mensajes de error y de estado para obtener más información.

Bloquear contactos

El bloqueo se puede considerar una función defensiva, que permite evitar que las personas malintencionadas continúen realizando acciones ofensivas. Para bloquear un contacto, es necesario que este te haya enviado un mensaje en las últimas 24 horas.

Ejemplo

Envía una llamada de la API a /v1/contacts/{phone_number}/block con un motivo para bloquear a 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 tiene estado HTTP 200 y ningún objeto "errors".

Una respuesta fallida tiene 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

Se admiten los siguientes parámetros en las llamadas POST a /v1/contacts/{phone_number}/block:

Desbloquear contactos

Haz esta llamada para desbloquear un contacto.

Ejemplo

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

POST /v1/contacts/+16315551000/unblock

Una respuesta tiene estado HTTP 200 y ningún objeto "errors".

Una respuesta fallida tiene 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

Se admiten los siguientes parámetros en las llamadas POST a /v1/contacts/{phone_number}/unblock:

Lista de bloqueo

Puedes obtener una lista de tus contactos bloqueados de la siguiente manera.

Ejemplo

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

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

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

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

Parámetros

Se admiten los siguientes parámetros en las llamadas GET a /v1/contacts/blocklist:

Informes

Los informes proporcionan señales fundamentales para crear una solución preventiva contra las personas malintencionadas. Antes de reportar un contacto, es necesario que este te haya enviado un mensaje en las últimas 24 horas.

Ejemplo

Envía una llamada de la API a /v1/contacts/{phone_number}/report que contenga un motivo, si estás bloqueando a 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 tiene estado HTTP 200 y ningún objeto "errors".

Una respuesta fallida tiene 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

Se admiten los siguientes parámetros en las llamadas POST a /v1/contacts/{phone_number}/report: