Introducción

Qué puedes hacer con la API de Yolani (contactos, conversaciones, embudo, mensajes, plantillas, webhooks y el agente IA), en qué planes viene, la URL base y la lista completa de endpoints.

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?

AutomatizaProfesionalEscalaEnterprise (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

  1. Un plan con API: Escala o Enterprise (arriba).
  2. Una API key. La crea el dueño o un administrador de la cuenta en Configuración → Desarrolladores → API Keys. Ver Autenticación.
  3. 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étodoEndpointQué hacePermiso (scope)
GET/api/v1/meVerifica tu API key y devuelve tu empresaCualquiera
GET/api/v1/webhooks/event-typesLista los eventos de webhook que existenCualquiera
POST/api/v1/webhooksDa de alta un webhook (REST Hook)webhooks:manage + lectura del evento
GET/api/v1/webhooksLista los webhooks dados de alta por la APIwebhooks:manage
DELETE/api/v1/webhooks/:idDa de baja un webhook dado de alta por la APIwebhooks:manage
GET/api/v1/webhooks/samplesEjemplos de un evento con datos de tu cuentaLectura del evento
GET/api/v1/contactsLista y busca contactos (también por teléfono o correo exactos)contacts:read
POST/api/v1/contactsCrea o actualiza un contacto por teléfono o correocontacts:write
GET/api/v1/contacts/:idConsulta un contactocontacts:read
PATCH/api/v1/contacts/:idActualiza nombre, correo o teléfonocontacts:write
GET/api/v1/conversationsLista conversaciones (por estado, canal o contacto)conversations:read
POST/api/v1/conversationsAbre (o reactiva) una conversación de WhatsAppconversations:write
GET/api/v1/conversations/:idConsulta una conversaciónconversations:read
PATCH/api/v1/conversations/:idCambia el estado (activa, en espera, resuelta)conversations:write
POST/api/v1/conversations/:id/stageMueve la conversación de etapa en el embudoconversations:write
GET/api/v1/pipelinesLista tus embudos con sus etapasconversations:read
GET/api/v1/conversations/:id/messagesLista los mensajes de una conversaciónconversations:read
POST/api/v1/conversations/:id/messagesEnvía un mensaje (texto o archivo)messages:send
GET/api/v1/templatesLista tus plantillas aprobadas de WhatsAppmessages:send_template
POST/api/v1/conversations/:id/messages/templateEnvía una plantillamessages:send_template
POST/api/v1/conversations/:id/botEnciende o pausa al agente IAbot: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:

Descargar yolani-api-v1.yaml

Próximos pasos

  1. Autenticación: crea tu API key y elige sus permisos.
  2. Mensajes: el endpoint más usado.
  3. Webhooks: entérate al momento de lo que pasa en tu cuenta.