Saltar al contenido principal

Entorno de pruebas para contactos con nombre de usuario compartido

  • Actualización

  1. Visión general

  2. Endpoint

  3. Campos de la solicitud

  4. Reglas

  5. Solicitud

  6. Estructura del payload

  7. Cuándo utilizar

  8. Posibles errores

  9. Consideraciones

 

Visión general

Blip está poniendo a disposición un endpoint para realizar el registro de contactos que serán usados para pruebas asociados a un número de teléfono en WhatsApp. En este escenario de prueba, el contacto registrado se comporta como un contacto que adoptó el recurso y Nombre de usuario y que, por lo tanto, no comparte el número de teléfono. Este contacto será creado teniendo un GUID como identidad del contacto.

El endpoint permite informar los datos básicos del contacto, como nombre para mostrar y número de teléfono, mediante una solicitud set dirigida al recurso /phone-numbers/test-contacts.

Este recurso puede ser utilizado en escenarios en los que sea necesario configurar o actualizar contactos de prueba para la validación de integraciones y funcionalidades relacionadas con el nombre de usuario de WhatsApp.

 

Endpoint

La operación se realiza mediante el endpoint de comandos de la organización:

POST https://{ORGANIZATION_ID}.http.msging.net/commands

Headers

Content-Type: application/json
Authorization: Key {YOUR_TOKEN}

Donde:

  • ORGANIZATION_ID: identificador de la organización/cuenta en Blip.

  • YOUR_TOKEN: clave de autorización del bot utilizada para realizar la solicitud.
     

Campos de la solicitud

La solicitud utiliza el formato de comando de la plataforma Blip.

Campo Descripción
id Identificador único de la solicitud. Puede generarse automáticamente, por ejemplo, utilizando {{$guid}}.
to Destinatario del comando. Para esta operación, debe usarse postmaster@wa.gw.msging.net.
method Método de la operación. Para registro o actualización del contacto, debe usarse set.
type Tipo del recurso enviado en la solicitud. Debe ser application/vnd.iris.whatsapp.phonenumber+json.
uri Recurso que será manipulado. Para contactos de prueba, debe ser /phone-numbers/test-contacts.
resource Objeto que contiene los datos del contacto de prueba.
resource.displayName Nombre para mostrar del contacto de prueba. (no obligatorio)
resource.number Número de teléfono asociado al contacto.

 

Reglas

Para que un número pueda ser registrado como Contact Test, se deben respetar algunas reglas:

  • El número debe ser nuevo, es decir, aún no debe estar registrado como Contact Test.

  • Se permite registrar máximo 2 números como Contact Test.

  • El número no puede haber sido utilizado anteriormente para conversar con el Bot.

  • El número debe informarse en formato internacional, incluyendo el código del país. Ejemplo: +5511999999999

⚠️ Importante: no es posible eliminar un número del entorno de prueba. Después de que el número es agregado, siempre se comportará como un número creado como Guid. Este estado no puede ser revocado.
 

Solicitud

Ejemplo de solicitud para registrar un contacto de prueba:

POST https://{ORGANIZATION_ID}.http.msging.net/commands HTTP/1.1
Content-Type: application/json
Authorization: Key {YOUR_TOKEN}
{
    "id": "{{$guid}}",
    "to": "postmaster@wa.gw.msging.net",
    "method": "set",
    "type": "application/vnd.iris.whatsapp.phonenumber+json",
    "uri": "/phone-numbers/test-contacts",
    "resource": {
        "displayName": "prueba",
        "number": "+5511999999999"
    }
}

Ejemplo de los datos utilizados

En el ejemplo anterior:

  • Nombre del contacto: prueba

  • Número: +5511999999999

  • Método: set

  • Recurso: /phone-numbers/test-contacts

El número debe informarse en formato internacional, incluyendo el código del país.
 

Estructura del payload

El objeto resource concentra la información del contacto que será configurado:

"resource": {
    "displayName": "prueba",
    "number": "+5511999999999"
}

displayName (no obligatorio)

Representa el nombre para mostrar asociado al contacto de prueba.

Ejemplo:

"displayName": "prueba"

number

Representa el número de teléfono del contacto en formato +DDI_DDD_NÚMERO

Ejemplo:

"number": "+5511999999999"

Se recomienda informar el número usando el formato internacional, incluyendo el + y el código del país.
 

Cuándo utilizar

El endpoint puede usarse en escenarios donde es necesario configurar contactos de prueba sin número de teléfono conocido relacionados con números de teléfono de WhatsApp, por ejemplo:

  • Pruebas de funcionalidades relacionadas con WhatsApp;

  • Configuración de contactos usados en entornos de prueba;

  • Automatización del registro de contactos de prueba;

  • Actualización de los datos de un contacto de prueba.

Punto de atención: sustituya {ORGANIZATION_ID} por la organización correspondiente y {YOUR_TOKEN} por una clave de autorización válida antes de realizar la llamada.
 

Posibles errores

Durante el uso del endpoint /phone-numbers/test-contacts, algunas situaciones pueden impedir el registro del contacto de prueba.

1. Contact cannot be registered as test contact

Descripción:

Este error puede ocurrir cuando el contacto no cumple con los criterios necesarios para ser utilizado como un número de prueba. 

2. Maximum number of test contacts

Descripción:

Indica que se ha alcanzado el límite máximo de contactos de prueba permitidos.

En caso de éxito en el registro del Contact Test, la API devolverá el HTTP Status 200 (OK), indicando que la operación se realizó con éxito. 
 

Consideraciones

El endpoint debe utilizarse exclusivamente para el propósito de gestión de los contactos de prueba soportados por el recurso /phone-numbers/test-contacts.

La estructura del resource debe respetar el formato esperado por el endpoint, especialmente los campos displayName y number.


 

¿Necesitas más ayuda? Explora nuestros contenidos en la Blip Academy o Blip Community, mira tutoriales en nuestro canal de YouTube o resuelve tus dudas en nuestro canal de atención 😃

Artículos relacionados