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"
}
| Campo | Qué es |
|---|---|
id | Identificador del contacto en Yolani |
name | Nombre |
phone | Telé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 |
email | Correo |
whatsapp_id | El 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 |
tags | Etiquetas del contacto |
created_at / updated_at | Fechas 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ámetro | Tipo | Descripción |
|---|---|---|
search | string | Busca un texto dentro del nombre, el correo o el teléfono. No distingue mayúsculas, pero sí acentos: lucia no encuentra a "Lucía" |
phone | string | Teléfono exacto, en cualquier formato (ver arriba). Útil para saber si alguien ya es tu contacto |
email | string | Correo exacto, sin distinguir mayúsculas |
limit | number | Cuántos por página: de 1 a 100, 50 si no lo mandas |
offset | number | Cuá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.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
phone | string | phone o email | Teléfono, en cualquier formato (ver arriba) |
email | string | phone o email | Correo del contacto |
name | string | No | Nombre |
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.