Lista todas las instancias del tenant.

Detalle completo de una instancia.

Crea una nueva instancia y devuelve el QR de conexión.

Refresca el QR para conectar la instancia.

Estado actual (open / connecting / disconnected) + teléfono.

Reconectar la instancia (genera QR fresco).

Cierra la sesión de WhatsApp.

Reinicia el proceso de Evolution para esa instancia.

Elimina la instancia (también en Evolution).

Métricas: mensajes enviados/recibidos, conversaciones activas (periodos: 1h, 24h, 7d, 30d).

Envía un mensaje de texto. Body: {phone, message, instance_id?, instance_name?}.

Envía imagen, video, audio, documento o sticker. Body: {phone, media_url, media_type, caption?, filename?, mime_type?}. media_type admite image, video, audio, document y sticker (también los alias ptt, voice, gif, photo). En media_url puedes pasar una URL pública o el archivo en base64.

Envía un audio / nota de voz. Body: {phone, audio_url}.

Envía un documento (PDF, DOC, XLSX, etc.).

Envía ubicación geográfica. Body: {phone, latitude, longitude, name?, address?}.

Envía una tarjeta de contacto (vCard).

Envía una plantilla local con variables {{var}}.

Mensaje con botones de respuesta rápida. Body: {phone, body, buttons[], footer?, header?}. Funciona con los dos tipos de número.

En WhatsApp oficial (Meta): máximo 3 botones, título de 20 caracteres, cuerpo de 1024 y pie de 60. Si envías de más, se recortan a esos límites en lugar de fallar. Requiere la ventana de 24 horas abierta.

curl -X POST https://panel.smsenlinea.com/api/v1/messages/send-buttons \
  -H "Authorization: Bearer TU_API_KEY" -H "Content-Type: application/json" \
  -d '{"phone":"573001234567","body":"¿Confirmas tu cita?",
       "buttons":[{"id":"si","title":"Sí"},{"id":"no","title":"No"}]}'

Lista interactiva con secciones. Body: {phone, body, button_text, sections[], footer?, title?}. Funciona con los dos tipos de número.

En WhatsApp oficial (Meta): hasta 10 secciones y 10 filas en total entre todas; título de fila 24 caracteres y descripción 72. Lo que sobre se recorta. Requiere la ventana de 24 horas abierta.

Este endpoint hace dos cosas distintas según lo que envíes:

• template_name → plantilla aprobada de WhatsApp (Meta). Es la única forma de escribir fuera de la ventana de 24 horas, y admite encabezado, botones y carrusel.
• template_id → plantilla de texto guardada en tu panel, que se envía como mensaje normal.

Paso 1: consulta qué necesita la plantilla. GET /api/v1/instances/{id}/templates devuelve cada plantilla con un bloque requires:

{
  "name": "promo_agosto", "language": "es", "status": "APPROVED",
  "requires": {
    "header":    { "type": "IMAGE", "vars": 0, "needs_media": true },
    "body_vars": 2,
    "buttons": [
      { "index": 0, "type": "URL", "needs_value": true,
        "hint": "Parte final de la URL (se añade a https://tienda.com/)" },
      { "index": 1, "type": "QUICK_REPLY", "needs_value": false }
    ],
    "carousel": { "cards": 0 }
  }
}

Paso 2: envíala con esos datos.

curl -X POST https://panel.smsenlinea.com/api/v1/messages/send-template \
  -H "Authorization: Bearer TU_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "phone": "573001234567",
    "instance_id": 50,
    "template_name": "promo_agosto",
    "language": "es",
    "header": "https://midominio.com/banner.jpg",
    "variables": ["Ana", "20%"],
    "buttons": { "0": "oferta-agosto" }
  }'

Cómo se rellena cada parte:

Si falta algún dato, la API responde 422 diciendo exactamente qué falta, sin llegar a gastar el envío. Meta rechaza el mensaje entero cuando el número de parámetros no coincide, así que se comprueba antes.

Errores propios: template_not_approved (no existe o Meta no la aprobó), not_supported (intentaste una plantilla aprobada en un número por QR) y empty_template.

Redacta una plantilla con IA a partir de una descripción en lenguaje normal, respetando las reglas de Meta. Devuelve el borrador ya validado; no lo crea en Meta: lo revisas y después lo envías con POST /instances/{id}/templates.

curl -X POST https://panel.smsenlinea.com/api/v1/instances/50/templates/ai \\
  -H "Authorization: Bearer TU_API_KEY" -H "Content-Type: application/json" \\
  -d '{
    "descripcion": "Avisar al cliente que su equipo ya está reparado y puede pasar a recogerlo, con el número de orden y el horario",
    "negocio": "Compuservices JR",
    "con_botones": true
  }'

Respuesta:

{
  "template": {
    "name": "equipo_reparado_listo",
    "category": "UTILITY",
    "language": "es",
    "body": "Hola {{1}}, te informamos que tu equipo con orden {{2}} ya está reparado...",
    "body_examples": ["Carlos", "A-123"],
    "header_type": "TEXT", "header_text": "Tu equipo está listo",
    "footer": "Compuservices JR",
    "buttons": [],
    "explicacion": "Por qué eligió esa categoría y qué representa cada variable"
  },
  "ready": true,
  "errors": [],
  "warnings": [],
  "fixes": ["Ajusté el nombre a ..."]
}

Redacta con DeepSeek. Si tienes tu propia clave de DeepSeek en Ajustes → Inteligencia Artificial se usa esa; si no, la de la plataforma. Consume saldo de IA de tu cuenta.

Validación previa al crear plantillas

POST /instances/{id}/templates comprueba la plantilla antes de mandarla a Meta y responde 422 con la lista exacta de lo que falla. Meta tarda hasta 24 h en revisar, así que un fallo de forma que se detecta aquí te ahorra un día.

Reglas comprobadas contra la API de Meta:

Envía un formulario nativo de WhatsApp: el cliente lo rellena dentro del chat, sin abrir un navegador ni escribir sus datos en varios mensajes. Cuando lo envía, la respuesta llega a tu webhook como evento flow.response y aparece en el chat.

Solo en WhatsApp oficial (Meta). En números conectados por código QR no existe: usa /messages/send-buttons o /messages/send-list.

Paso 1: crea el formulario (o hazlo desde el panel, en Formularios de WhatsApp). Se crea como borrador.

curl -X POST https://panel.smsenlinea.com/api/v1/instances/50/flows \\
  -H "Authorization: Bearer TU_API_KEY" -H "Content-Type: application/json" \\
  -d '{ "preset": "cita" }'

Modelos listos: cita, cotizacion, soporte, encuesta, registro. O defínelo campo a campo:

{
  "name": "Agendar visita",
  "title": "Agendar visita",
  "submit_label": "Confirmar",
  "categories": ["APPOINTMENT_BOOKING"],
  "fields": [
    { "type": "text",   "name": "nombre",  "label": "Tu nombre", "required": true },
    { "type": "date",   "name": "fecha",   "label": "Fecha preferida", "required": true },
    { "type": "select", "name": "franja",  "label": "Franja horaria", "required": true,
      "options": [ {"id":"am","title":"Mañana"}, {"id":"pm","title":"Tarde"} ] }
  ]
}

Tipos de campo: text, textarea, email, phone, number, date, select, radio, checkbox, optin. Máximo 20 campos.

Paso 2: publicícalo. Un borrador no se puede enviar, y uno publicado ya no se puede modificar (se crea otro).

curl -X POST https://panel.smsenlinea.com/api/v1/instances/50/flows/FLOW_ID/publish \\
  -H "Authorization: Bearer TU_API_KEY"

Paso 3: envíalo.

curl -X POST https://panel.smsenlinea.com/api/v1/messages/send-flow \\
  -H "Authorization: Bearer TU_API_KEY" -H "Content-Type: application/json" \\
  -d '{
    "phone": "573001234567",
    "instance_id": 50,
    "flow_id": "1543663357804290",
    "body": "Agenda tu visita técnica en menos de un minuto.",
    "button_text": "Agendar visita"
  }'

Errores propios: flow_not_found, flow_not_published (sigue en borrador), missing_screen y not_supported (lo intentaste en un número por QR). Se comprueban antes de gastar el envío.

Lista tus formularios. Añade ?sync=1 para refrescarlos contra Meta (por si los creaste en WhatsApp Manager). El campo sendable te dice de un vistazo cuáles puedes enviar ya.

{
  "flow_id": "1543663357804290",
  "name": "Agendar cita",
  "status": "PUBLISHED",
  "initial_screen": "FORMULARIO",
  "responses_count": 42,
  "sendable": true,
  "preview_url": "https://business.facebook.com/wa/manage/flows/..."
}

Las respuestas que han enviado tus clientes. Filtra con flow_id, conversation_id o since.

{
  "id": 128,
  "flow_id": "1543663357804290",
  "flow_name": "Agendar cita",
  "flow_token": "ft_9a3c...",
  "conversation_id": 1126,
  "from": "573001234567",
  "answers": { "nombre": "María Ríos", "fecha": "1755734400000", "franja": "am" },
  "created_at": "2026-08-21 15:04:22"
}

Las respuestas van tal cual las manda WhatsApp: las fechas en milisegundos desde epoch y las listas por el id de la opción, no por su texto. Es a propósito, para no alterar el dato original. En el panel se muestran ya traducidas.

Borra el formulario si es un borrador. Si ya estaba publicado Meta no permite borrarlo: se retira de circulación y deja de poder enviarse.

Botón que abre un enlace. En vez de pegar la URL en el texto, el cliente ve un botón con la etiqueta que elijas. Body: {phone, body, url, button_text?, footer?, header?}.

curl -X POST https://panel.smsenlinea.com/api/v1/messages/send-cta \
  -H "Authorization: Bearer TU_API_KEY" -H "Content-Type: application/json" \
  -d '{"phone":"573001234567",
       "body":"Tu cotización COT-2026-0071 está lista.",
       "url":"https://panel.smsenlinea.com/q/abc123",
       "button_text":"Ver cotización"}'

Solo en WhatsApp oficial (Meta) y dentro de la ventana de 24 horas. La etiqueta del botón admite 20 caracteres. La URL debe empezar por http:// o https://; si no, responde 422 indicando el campo. En números por QR usa /messages/send con la URL en el texto.

Pide la ubicación con un botón: el cliente la comparte con un toque, sin explicarle cómo adjuntarla. Útil para visitas técnicas, entregas y órdenes de trabajo. Body: {phone, body}. Solo en WhatsApp oficial (Meta).

Encuesta de WhatsApp. Body: {phone, question, options[], multiple_answers?}. Solo en números conectados por QR: la API oficial de Meta no tiene encuestas y la llamada responde not_supported.

Reacciona con emoji a un mensaje existente. Body: {evolution_msg_id, emoji}.

Reenvía un mensaje a múltiples destinatarios.

Envío en lote (hasta 500 mensajes con delay configurable). Requiere tier ≥ Starter.

Lista mensajes con filtros: conversation_id, instance_id, direction, type, date_from, date_to, paginación.

Detalle completo de un mensaje.

Edita un mensaje enviado. Body: {evolution_msg_id, content}. Solo en números conectados por QR: la API oficial de Meta no permite editar mensajes.

Elimina un mensaje para todos (recall). Solo en números conectados por QR: la API oficial de Meta no permite eliminar mensajes ya enviados.

Marca un mensaje recibido como leído.

Verifica qué números tienen cuenta de WhatsApp. Body: {numbers: []}.

URL de foto de perfil de un contacto.

Lista conversaciones. Filtros: status, assigned_to (id o "unassigned"), instance_id, unread_only, search.

Detalle de una conversación con contact, instance, assigned_to.

Mensajes paginados de una conversación.

Inicia una conversación nueva. Body: {phone, instance_id?, initial_message?}.

Asigna a uno o varios asesores. Body: {conversation_id|phone, agent_id|agent_email|agent_ids[]}. Pasa null para desasignar.

Cambia estado: open, pending, resolved, archived.

Agrega nota interna a una conversación.

Lista todas las notas internas de la conversación.

Agrega una etiqueta. Body: {label_id}.

Quita una etiqueta.

Archiva o desarchiva. Body: {archived: true|false}.

Marca todos los mensajes entrantes como leídos y avisa a WhatsApp, de modo que el cliente ve los ✓✓ azules en su teléfono. La respuesta incluye whatsapp_notified: si es false, el marcado se hizo solo en tu panel (por ejemplo si la línea estaba desconectada).

Muestra “escribiendo…” al cliente. Cuerpo: {"state": "typing"} — valores admitidos typing, recording (grabando audio) y paused (dejar de mostrarlo).

curl -X POST https://panel.smsenlinea.com/api/v1/conversations/1234/typing \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state":"typing"}'

Diferencias por proveedor. En números conectados por QR el indicador se activa y se apaga cuando tú quieras. En WhatsApp oficial (Meta) el indicador se envía respondiendo al último mensaje del cliente, expira solo a los ~25 segundos o al enviar tu respuesta, y solo funciona dentro de la ventana de atención de 24 horas: por eso paused se acepta pero no hace nada, y si el cliente nunca te ha escrito la llamada responde no_inbound_message.

Devuelve las frases de inicio y los comandos configurados en el número.

Configura ambos. Son ajustes del número, no mensajes:

• Frases de inicio: hasta 4 sugerencias que se pueden tocar, visibles para quien abre el chat por primera vez. 80 caracteres, sin emojis.
• Comandos: hasta 30, se ofrecen cuando el cliente escribe «/». Nombre de 32 caracteres, descripción de 256, sin emojis.

curl -X POST https://panel.smsenlinea.com/api/v1/instances/50/automation \
  -H "Authorization: Bearer TU_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "prompts": ["Pedir una cotización", "Ver catálogo", "Hablar con un asesor"],
    "commands": [
      {"command_name":"cotizar","command_description":"Solicitar una cotización"},
      {"command_name":"soporte","command_description":"Hablar con un asesor"}
    ]
  }'

Lo que exceda los límites se recorta en lugar de fallar, porque Meta rechaza la configuración entera si algo se pasa. Solo en WhatsApp oficial (Meta).

Estado en línea de la línea completa (no de un chat). Cuerpo: {"state": "online"} u offline. Estar online es además lo que permite recibir la presencia de tus contactos. Solo aplica a conexiones por QR: en WhatsApp oficial no existe ese concepto y la respuesta llega con applied: false.

Activa o pausa el chatbot en esta conversación.

Elimina (soft-delete: archiva).

Encola un mensaje diferido. Body: {phone, message|media_url, instance_id?|instance_name?, send_after?, dedupe_key?}.

Estado del mensaje encolado.

Cancela un mensaje aún no enviado.

Lista los asesores del tenant (nombre, email, rol, estado).

Detalle de un asesor.

Métricas del asesor: conversaciones atendidas, mensajes, tiempos de respuesta.

Disponibilidad actual del asesor.

Conversaciones asignadas al asesor.

Lista departamentos. CRUD completo con POST/PUT/DELETE en /departments/{id} y gestión de miembros en /departments/{id}/agents.

Lista contactos con búsqueda y paginación.

Busca un contacto por teléfono.

Crea un contacto. También: POST /contacts/update (upsert por teléfono), POST /contacts/import, GET /contacts/export, block/unblock, y listas en /contact-lists.

Lista cotizaciones. Filtros: status (draft, sent, viewed, accepted, rejected, expired, cancelled), date_from, date_to, search (número/cliente), paginación. Cada fila incluye views_count, first_viewed_at, acceptance y public_url.

Detalle completo: ítems, opciones (good/better/best), aceptación (quién y cuándo) y events — el timeline completo (created, sent_wa, viewed, accepted...).

Funnel agregado: by_status, sent_count, viewed_count, accepted_count, view_rate, acceptance_rate, accepted_amount.

Lista facturas. Filtros: status (draft, sent, viewed, partial, paid, overdue, cancelled, void), date_from/date_to (fecha de emisión), search, overdue_only=1. Incluye amount_paid, balance_due, first_viewed_at y public_url.

Detalle completo: ítems, retenciones y payments (cada pago registrado con fecha, monto y método).

Resumen de cartera: by_status, viewed_count, overdue_count, total_invoiced, total_collected, total_outstanding.

Plantillas activas con su definición de campos (fields: key, label, type, required, options). Consúltalas antes de crear para saber qué datos enviar en custom_fields.

Lista tickets. Filtros: status, service_status (scheduled, en_route, in_progress, completed), priority, assigned_to, date_from/date_to, search.

Detalle: mensajes públicos, eventos, asignados y bloque work_order (estado de servicio, dirección, campos custom, firmado por/cuándo, work_order_url). Las notas internas y la imagen de la firma nunca se exponen.

Totales por estado + resumen de órdenes de trabajo por estado de servicio.

Crea un ticket. Body: {subject, description?, priority?, phone?, contact_name?, contact_email?, template_id?, custom_fields?, service_address?, service_date?, service_time?, service_end_time?, assignee_ids?, notify_customer?}. Con plantilla field_service genera la orden de trabajo, notifica al cliente, envía a cada empleado su enlace de ejecución y programa recordatorios automáticos (1 día antes y 2 horas antes, ajustados al horario hábil configurado por el negocio).

Cambia el estado. Body: {status} (open, in_progress, waiting_customer, resolved, closed) o {service_status} para órdenes (solo la siguiente transición válida; completed requiere la firma del cliente en el portal del empleado).

Responde al cliente (le notifica por WhatsApp/email) o registra nota interna con {private: true}.

Asigna asesores. Body: {assignee_ids: []}. En órdenes de trabajo re-notifica los enlaces de ejecución.

Lista tus planes. Filtro status (active, paused, finished) + paginación. Cada uno incluye next_run_at (UTC) y occurrences_sent.

Crea un plan. Body: {title, phone, display_name?, template_id?|body?, variables?, instance_id?, frequency, day_of_week?, day_of_month?, every_n_days?, send_time, timezone, skip_weekends?, starts_on, ends_on?, max_occurrences?}.

Detalle del plan.

Edita el plan (recalcula el próximo envío).

Pausar / reanudar (reanudar recalcula la próxima ocurrencia hacia el futuro).

Historial de ocurrencias con el estado real del envío (queued/sent/failed).

Elimina el plan.

Información del tenant (nombre, email, fecha de alta).

Plan vigente: nombre, límites (instancias, mensajes/mes, asesores) y features incluidas.

Estado de la suscripción y fecha de renovación/vencimiento.

Consumo del período: mensajes usados vs límite del plan, instancias activas.

Información de la API Key usada (nombre, scopes, último uso).

Límites de tasa vigentes y consumo actual.

Panorama general: mensajes, conversaciones, contactos nuevos, ventas.

Mensajes enviados y recibidos por día, con totales del rango.

Conversaciones nuevas/resueltas y tiempos de atención.

Actividad por instancia (útil con varias líneas de WhatsApp).

Desempeño por asesor.

Ventas del período (módulo e-commerce).

Productos más vendidos.

Uso de la propia API (llamadas por endpoint y por día).

CRUD de plantillas de mensaje (POST/PUT/DELETE en /templates/{id}; categorías en /templates/categories).

CRUD de respuestas rápidas.

CRUD de campañas + control: start, pause, resume, cancel, recipients, stats.

CRUD de etiquetas para clasificar conversaciones.

CRUD de productos + POST /products/{id}/images + POST /products/{id}/send-to-chat.

CRUD de categorías del catálogo.

Órdenes: listar, crear, cambiar estado/pago, refund, send-payment-link.

Valida un cupón; CRUD completo en /coupons.

Sube un archivo y devuelve la URL para usar en send-media/send-document. También GET /media/url, GET /media/download, GET /media/quota, DELETE /media.

CRUD de webhooks + POST /webhooks/{id}/test + GET /webhooks/{id}/deliveries + reintento de entregas. Catálogo de eventos en GET /webhooks/events.

Crea la campaña en estado draft. Body: {name, message_text, instance_ids[], recipients[], scheduled_at?, send_window_start?, send_window_end?, min_delay?, max_delay?, batch_size?, batch_interval?, rotation_type?}.

Pone la campaña en cola de envío. Exige al menos una instancia y un destinatario.

Enviados, entregados, leídos, fallidos y respuestas.