La API de Yolani conecta tu propio sistema, tu ERP o una herramienta de automatización (n8n, Make, Zapier o código propio) con tu cuenta: lees y das de alta contactos, abres conversaciones, mandas mensajes por el canal de cada cliente y enciendes o pausas al agente IA.
¿Qué puedes hacer?
- Contactos: listar, buscar, crear y actualizar los contactos de tu CRM.
- Conversaciones: listarlas, consultar su estado, abrir una nueva por WhatsApp, marcarlas como resueltas y moverlas de etapa en tu embudo.
- Mensajes: leer el historial y enviar texto o archivos por el canal de la conversación (WhatsApp, Instagram, Facebook o chat web).
- Plantillas: enviar plantillas aprobadas de WhatsApp API, con envío como texto en los canales que no las aceptan.
- Agente IA: encender o pausar al agente en una conversación.
- Webhooks: recibir en tu servidor, al momento, lo que pasa en tu cuenta (mensaje recibido, cita agendada, cambio de etapa...). Se configuran en el panel o los da de alta tu sistema por la API; ver Webhooks.
¿En qué planes viene?
| Automatiza | Profesional | Escala | Enterprise (a la medida) | |
|---|---|---|---|---|
| API (API keys) | ✅ | ✅ | ||
| Webhooks salientes | ✅ | ✅ | ✅ |
Enterprise no tiene precio publicado: se arma con el equipo de ventas. Si tu cuenta ya tiene contratado Corporativo, también incluye la API y los webhooks; Esencial no trae ninguno de los dos. Si tienes otro plan y necesitas la API, el equipo de Yolani puede activarla en tu cuenta.
Requisitos
- Un plan con API: Escala o Enterprise (arriba).
- Una API key. La crea el dueño o un administrador de la cuenta en Configuración → Desarrolladores → API Keys. Ver Autenticación.
- Al menos un canal conectado si vas a enviar mensajes.
URL base
https://api.yolani.co/api/v1
Todas las peticiones van por HTTPS, con el cuerpo en JSON (Content-Type: application/json).
Endpoints
| Método | Endpoint | Qué hace | Permiso (scope) |
|---|---|---|---|
| GET | /api/v1/me | Verifica tu API key y devuelve tu empresa | Cualquiera |
| GET | /api/v1/webhooks/event-types | Lista los eventos de webhook que existen | Cualquiera |
| POST | /api/v1/webhooks | Da de alta un webhook (REST Hook) | webhooks:manage + lectura del evento |
| GET | /api/v1/webhooks | Lista los webhooks dados de alta por la API | webhooks:manage |
| DELETE | /api/v1/webhooks/:id | Da de baja un webhook dado de alta por la API | webhooks:manage |
| GET | /api/v1/webhooks/samples | Ejemplos de un evento con datos de tu cuenta | Lectura del evento |
| GET | /api/v1/contacts | Lista y busca contactos (también por teléfono o correo exactos) | contacts:read |
| POST | /api/v1/contacts | Crea o actualiza un contacto por teléfono o correo | contacts:write |
| GET | /api/v1/contacts/:id | Consulta un contacto | contacts:read |
| PATCH | /api/v1/contacts/:id | Actualiza nombre, correo o teléfono | contacts:write |
| GET | /api/v1/conversations | Lista conversaciones (por estado, canal o contacto) | conversations:read |
| POST | /api/v1/conversations | Abre (o reactiva) una conversación de WhatsApp | conversations:write |
| GET | /api/v1/conversations/:id | Consulta una conversación | conversations:read |
| PATCH | /api/v1/conversations/:id | Cambia el estado (activa, en espera, resuelta) | conversations:write |
| POST | /api/v1/conversations/:id/stage | Mueve la conversación de etapa en el embudo | conversations:write |
| GET | /api/v1/pipelines | Lista tus embudos con sus etapas | conversations:read |
| GET | /api/v1/conversations/:id/messages | Lista los mensajes de una conversación | conversations:read |
| POST | /api/v1/conversations/:id/messages | Envía un mensaje (texto o archivo) | messages:send |
| GET | /api/v1/templates | Lista tus plantillas aprobadas de WhatsApp | messages:send_template |
| POST | /api/v1/conversations/:id/messages/template | Envía una plantilla | messages:send_template |
| POST | /api/v1/conversations/:id/bot | Enciende o pausa al agente IA | bot:manage |
Formato de respuesta
Las respuestas correctas llegan así. meta solo viene en los listados:
{
"success": true,
"data": [ ],
"meta": { "total": 120, "limit": 50, "offset": 0 }
}
Y los errores:
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "phone o email requerido"
}
}
Hay dos excepciones con otra forma (exceso de peticiones y suscripción vencida); están en Errores y límites.
Paginación
Los listados aceptan limit (de 1 a 100; 50 si no lo mandas) y offset (desde 0). meta.total dice cuántos hay en total.
# Segunda página de 100 contactos
curl "https://api.yolani.co/api/v1/contacts?limit=100&offset=100" \
-H "Authorization: Bearer yol_TU_TOKEN"
Especificación OpenAPI
La especificación completa en formato OpenAPI 3.1, para importarla en Postman, Insomnia o tu generador de clientes:
Próximos pasos
- Autenticación: crea tu API key y elige sus permisos.
- Mensajes: el endpoint más usado.
- Webhooks: entérate al momento de lo que pasa en tu cuenta.