Creando contactos con Webhooks externos

Updated 18/9/2024 by Manu da Silva

Creando contactos con Webhooks externos

En este artículo, te mostraremos de forma simple cómo traer contactos de tu plataforma externa a nuestra plataforma de flujos.

La plataforma de flujos cuenta con docenas de APIs que pueden ser consumidas para diversas funcionalidades; en este artículo nos enfocaremos estrictamente en la integración de contactos para automatizar tu comunicación.

Los contactos son los registros de cada persona dentro de un determinado canal de comunicación, en los que pueden guardarse campos estándar como Nombre, Correo Electrónico, Teléfono y WhatsApp, así como campos personalizados que pueden ser creados y utilizados libremente en la comunicación.

Normalmente, los Webhooks se disparan a partir de un determinado evento dentro del software asociado, como por ejemplo:

Al crear, actualizar o eliminar un registro de Cliente.
Al cambiar el estado de un registro de Lead en una plataforma CRM.

Cuando se llaman estos eventos, se deben realizar solicitudes a la plataforma de flujos para actualizar los registros de contactos, lo que permite que toda la automatización de la comunicación se modifique en tiempo real.

Adicionando Contatos

Puedes agregar un nuevo contacto enviando una solicitud POST a esta URL con los siguientes datos:

Name: el nombre completo del contacto (string, opcional).
Language: el idioma preferido del contacto (Código ISO de 3 dígitos, opcional).
Urns: una lista de URNs que deseas asociar a este contacto (array de hasta 100 strings, opcional). Dentro de las URNs se utiliza un prefijo con el canal a través del cual se puede iniciar la comunicación con este contacto. Aquí tienes algunos ejemplos:

-tel: Teléfono para envíos de SMS y Llamadas.

-whatsapp: Teléfono de WhatsApp para comunicación por este canal; en este caso, se deben utilizar 8 o 9 dígitos para el teléfono, dependiendo de cómo esté registrado en WhatsApp.

-mailto: Correo electrónico, no es un canal de recepción, solo para envío.

-ext: Identificador externo que puede usarse para un canal externo o para facilitar la búsqueda de un contacto mediante un identificador cualquiera.

groups: una lista de UUIDs de los grupos a los que pertenece este contacto; los grupos se explican a continuación (array de hasta 100 strings, opcional).
fields: los campos de contacto que deseas configurar o actualizar para este contacto; los campos deben estar previamente creados (diccionario con hasta 100 elementos, opcional).

Ejemplo:

POST /api/v2/contacts.json
{
    "name": "Manu Silva",
    "language": "por",
    "urns": [
        "tel:+558299331122", 
        "whatsapp:558299331122",
        "mailto:manu@weni.ai",
        "ext:123456"
    ],
    "groups": ["6685e933-26e1-4363-a468-8f7268ab63a9"],
    "fields": {
      "nickname": "Manu",
      "side_kick": "Emanoela da Silva"
    }
}

Actualizando Contactos

Una solicitud POST también puede ser utilizada para actualizar un contacto existente si especificas en la URL tanto su UUID como una de sus URNs. Solo los campos incluidos en el cuerpo serán actualizados en el contacto, los demás permanecerán intactos.

Si estás utilizando una URN en la URL, no la incluyas en el cuerpo de la solicitud. Además, si no existe un contacto con esa URN, crearemos uno nuevo y recibirás una respuesta 201 en ese caso.

Ejemplos:

POST /api/v2/contacts.json?uuid=09d23a05-47fe-11e4-bfe9-b8f6b119e9ab
{
    "name": "Manu Silva",
    "language": "por",
    "urns": ["tel:+558299331122", "whatsapp:5582999990000"],
    "groups": [
        {
            "name": "Devs", 
            "uuid": "6685e933-26e1-4363-a468-8f7268ab63a9"
        }
    ],
    "fields": {}
}

POST /api/v2/contacts.json?urn=tel%3A%2B90987877
{
    "fields": {"nickname": "Manu"}
}

Creando contactos con Webhooks externos