Contactos

Listar, buscar (también por teléfono o correo exactos), crear y actualizar los contactos de tu CRM por la API: campos, formato del teléfono, upsert y ejemplos.

El contacto

{
  "id": 481,
  "name": "Lucía Pérez",
  "phone": null,
  "email": "[email protected]",
  "whatsapp_id": "5215512345678",
  "tags": ["clienta", "vip"],
  "created_at": "2026-05-02T18:22:11.000Z",
  "updated_at": "2026-07-01T09:14:03.000Z"
}
CampoQué es
idIdentificador del contacto en Yolani
nameNombre
phoneTeléfono capturado aparte, tal como lo escribieron (en el panel o en tu petición a la API). En los contactos que llegaron por WhatsApp casi siempre viene null: su número está en whatsapp_id
emailCorreo
whatsapp_idEl número con el que el contacto escribe por WhatsApp, solo dígitos y con código de país. Viene null en los contactos de Instagram y Facebook, y empieza con api_ si diste de alta el contacto solo con correo
tagsEtiquetas del contacto
created_at / updated_atFechas en UTC (ISO 8601)

Formato del teléfono:

Para crear o buscar un contacto puedes mandar el teléfono en cualquier formato: +52 1 55 1234 5678, 55 1234 5678, 525512345678 y 5215512345678 son el mismo número. Si no trae código de país, se toma como número de México. Yolani lo guarda en whatsapp_id como lo entrega WhatsApp (en México, 521 + los 10 dígitos), así que el contacto que creas por la API es el mismo que después te escribe por WhatsApp.

Listar contactos

GET /api/v1/contacts

Scope: contacts:read

Devuelve los más recientes primero. No incluye visitantes anónimos del chat web, grupos de WhatsApp, chats personales ni contactos fusionados con otro.

ParámetroTipoDescripción
searchstringBusca un texto dentro del nombre, el correo o el teléfono. No distingue mayúsculas, pero sí acentos: lucia no encuentra a "Lucía"
phonestringTeléfono exacto, en cualquier formato (ver arriba). Útil para saber si alguien ya es tu contacto
emailstringCorreo exacto, sin distinguir mayúsculas
limitnumberCuántos por página: de 1 a 100, 50 si no lo mandas
offsetnumberCuántos saltar, para paginar
curl "https://api.yolani.co/api/v1/contacts?search=5512345678&limit=20" \
  -H "Authorization: Bearer yol_TU_TOKEN"

Para buscar a una persona por su número exacto:

curl "https://api.yolani.co/api/v1/contacts?phone=%2B52%201%2055%201234%205678" \
  -H "Authorization: Bearer yol_TU_TOKEN"

Respuesta:

{
  "success": true,
  "data": [
    {
      "id": 481,
      "name": "Lucía Pérez",
      "phone": null,
      "email": "[email protected]",
      "whatsapp_id": "5215512345678",
      "tags": ["clienta", "vip"],
      "created_at": "2026-05-02T18:22:11.000Z",
      "updated_at": "2026-07-01T09:14:03.000Z"
    }
  ],
  "meta": { "total": 1, "limit": 50, "offset": 0 }
}

Dos diferencias con el panel:

Hoy el listado no trae a los contactos que solo te han escrito por Instagram o Facebook; los puedes consultar por su id (viene en contact_id de sus conversaciones) con GET /api/v1/contacts/:id. Y al revés, sí trae a los contactos que borraste en el panel.

Crear o actualizar un contacto (upsert)

POST /api/v1/contacts

Scope: contacts:write

Busca primero por teléfono (en cualquiera de sus formas) y luego por correo. Si encuentra al contacto, le actualiza los datos que mandaste; si no, lo crea. Responde 201 al crear y 200 al actualizar, con meta.created en true o false.

CampoTipoRequeridoDescripción
phonestringphone o emailTeléfono, en cualquier formato (ver arriba)
emailstringphone o emailCorreo del contacto
namestringNoNombre
curl -X POST https://api.yolani.co/api/v1/contacts \
  -H "Authorization: Bearer yol_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "5215512345678", "name": "Lucía Pérez", "email": "[email protected]"}'

Respuesta (contacto nuevo):

{
  "success": true,
  "data": {
    "id": 482,
    "name": "Lucía Pérez",
    "phone": "5215512345678",
    "email": "[email protected]",
    "whatsapp_id": "5215512345678",
    "tags": [],
    "created_at": "2026-10-23T17:05:40.000Z",
    "updated_at": "2026-10-23T17:05:40.000Z"
  },
  "meta": { "created": true }
}

Crear un contacto no le manda ningún mensaje. Para escribirle, abre una conversación con POST /api/v1/conversations.

Consultar un contacto

GET /api/v1/contacts/:id

Scope: contacts:read

Devuelve el contacto en data, o 404 con NOT_FOUND si no existe o no es de tu cuenta.

curl https://api.yolani.co/api/v1/contacts/481 \
  -H "Authorization: Bearer yol_TU_TOKEN"

Actualizar un contacto

PATCH /api/v1/contacts/:id

Scope: contacts:write

Solo cambia los campos que mandas (name, email, phone). Mandar uno en null o vacío lo borra. Un nombre que pones por la API cuenta como escrito a mano: tu agente no lo reemplaza después con el nombre que le dé el cliente.

curl -X PATCH https://api.yolani.co/api/v1/contacts/481 \
  -H "Authorization: Bearer yol_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Lucía Pérez Garza"}'

Responde con el contacto ya actualizado.

Crear o actualizar contactos por la API dispara los webhooks contact.created y contact.updated con "source": "api". Ver Webhooks.