API
Ctrl K
EnglishItalianoDeutschEspañolFrançais

Referencia de la API de Migasender

22 endpoints · 101 parámetros · 36 ejemplos prácticos

URL base https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/… ¿Dónde lo encuentro?

No se encontró nada. Prueba con el nombre de un endpoint, una ruta o un parámetro.

Tu token de registro

Cada ruta empieza por /p/<token de registro>/. El token le dice a Migasender para qué plataforma es la llamada. A un token incorrecto la API responde Unknown platform.; una ruta sin /p/…/ recibe HTTP 404.

Lo encuentras en tres sitios:

  • La dirección de tu panel. Con la sesión iniciada, el token es todo lo que va después de /p/ en la barra de direcciones, p. ej. https://dashboard.migasender.com/p/907a0888…c1f61b.
  • El antiguo backoffice de Siberian. Menú superior Manage → Modules → Migawhatsapp (página …/migawhatsapp/backoffice_migawhatsapp), sección Migration. En una fila con estado MIGRATED, la columna New endpoint muestra https://apidb.migasender.com/p/<token> (API) y https://dashboard.migasender.com/p/<token> (panel), cada una con un botón de copiar. Las apps que siguen en OFF solo muestran un guion.
  • El panel de administración de Migasender (administradores de plataforma): https://apidb.migasender.com/panel/ → Platforms → columna Registration Token.

No es lo mismo que los tokens enviados en security_token: el platform token (Line Management, Groups), el token de Send Message y el de Chat History. El manual de usuario lo explica paso a paso.

Atención

TOKEN DE PLATAFORMA: solicítalo al administrador de la plataforma. Las API de Gestión de líneas, Código QR, Instancias / Registro de líneas y Grupos necesitan el token de plataforma. No se muestra en el panel del cliente ni en el panel de endpoints de la API. Los administradores lo encuentran en Manage → Modules → Migawhatsapp, recuadro Platform Token for API (backoffice antiguo), o en https://apidb.migasender.com/panel/ → Settings → Platform Token for API. (consulta el manual de usuario).

Idioma de las respuestas

Las respuestas llegan en italiano de forma predeterminada. Añade lang=en — como parámetro de consulta o campo del cuerpo — para obtener inglés, que es el idioma en el que aparece cada mensaje de esta página.

Afecta a los campos error y message; los datos no cambian. La cabecera Accept-Language se ignora a propósito, de modo que el idioma del navegador nunca pueda cambiar en silencio lo que recibe tu integración.

bash 
curl -X POST 'https://apidb.migasender.com/p/YOUR_REGISTRATION_TOKEN/api_send/heartbeat?lang=en' \
  -H 'Content-Type: application/json' \
  -d '{ "app_id": 1, "security_token": "YOUR_SEND_MESSAGE_TOKEN" }'

7 endpoints

Gestión de líneas

Crear, listar, renombrar, cambiar la fecha y eliminar las líneas de WhatsApp desde las que envía una aplicación, y fijar su límite mensual.

Atención

TOKEN DE PLATAFORMA obligatorio — solicítalo al administrador de la plataforma. No se muestra en el panel del cliente. Dónde lo encuentran los administradores.

El token es un token de plataforma bajo un nombre de campo de app

Fácil de equivocarse

Estos endpoints se autentican con tu token de plataforma, pero el campo se llama security_token, no platform_token. Enviar aquí el token de Send Message o de Chat History falla con Security token mismatched.

Una «línea» es un par de filas de gateway, MASTER y SLAVE. Crear una crea ambas; eliminar una elimina ambas; una actualización escribe en las dos.

Lo que necesita todo endpoint de Gestión de líneas

security_token string Obligatorio
Tu token de plataforma, pese al nombre del campo.
app_id int Obligatorio
La aplicación a la que pertenece la línea.
Errores que puede devolver cualquier endpoint de Gestión de líneas5
Security token missing.
No se incluyó security_token.
Security token mismatched.
El valor no es el token de esta plataforma; un token de API de nivel de app fallará aquí.
App id missing.
No se incluyó app_id.
Invalid app id.
Ninguna aplicación coincide con ese app_id en esta plataforma.
This app is in read-only mode. Write operations are disabled.
Lo devuelven create, update, delete y el ajuste del límite mientras la aplicación está en solo lectura. Las lecturas siguen funcionando.
POST /p/{regToken}/api_line/getall

Listar todas las líneas

Atención

TOKEN DE PLATAFORMA obligatorio — solicítalo al administrador de la plataforma. No se muestra en el panel del cliente. Dónde lo encuentran los administradores.

Devuelve todas las líneas de la aplicación, indexadas por ID de línea.

Parámetros

Bastan los dos parámetros comunes.

POST /p/{regToken}/api_line/get

Obtener una línea

Atención

TOKEN DE PLATAFORMA obligatorio — solicítalo al administrador de la plataforma. No se muestra en el panel del cliente. Dónde lo encuentran los administradores.

Devuelve una sola línea, más los tokens de Chat History y Send Message de la aplicación.

Además de los parámetros comunes

line_id int Obligatorio
La línea que se va a leer.
Errores2
Line id missing.
No se incluyó line_id.
Invalid line id.
No hay ninguna línea con ese ID en esta aplicación.
POST /p/{regToken}/api_line/create

Crear una línea

Atención

TOKEN DE PLATAFORMA obligatorio — solicítalo al administrador de la plataforma. No se muestra en el panel del cliente. Dónde lo encuentran los administradores.

Añade una línea a la aplicación: una fila de gateway MASTER y otra SLAVE. Todos los campos más allá de los dos comunes son opcionales.

Además de los parámetros comunes

line_label string Opcional
Un nombre para la línea. Debe ser único dentro de la aplicación.
line_expiration_date string (date) Opcional
Y-m-d, y debe estar en el futuro. Déjalo vacío para UNLIMITED. Se ignora en plataformas YEARLY, que siempre reciben un año desde hoy.
max_messages_per_month int Opcional
El límite mensual de la aplicación. Mínimo 1.
Errores5
Maximum allowed lines reached.
El cupo de líneas de la aplicación está agotado. Un cupo de 0 significa ilimitado.
Line name already exists.
Otra línea de esta aplicación ya usa ese line_label.
Invalid date format for line_expiration_date. Expected format: Y-m-d.
La fecha no tiene el formato Y-m-d.
Invalid date for line_expiration_date. Date should be greater than the current date.
La fecha es hoy o está en el pasado.
Invalid max_messages_per_month value.
No es un número, o es menor que 1.
POST /p/{regToken}/api_line/update

Actualizar una línea

Atención

TOKEN DE PLATAFORMA obligatorio — solicítalo al administrador de la plataforma. No se muestra en el panel del cliente. Dónde lo encuentran los administradores.

Cambia la etiqueta, la caducidad o el estado de una línea. El cambio se escribe en sus dos filas de gateway.

Además de los parámetros comunes

Debes enviar al menos line_expiration_date o line_status; de lo contrario la llamada se rechaza. line_label por sí solo no basta.

line_id int Obligatorio
La línea que se va a modificar.
line_label string Opcional
Un nombre nuevo. Debe seguir siendo único dentro de la aplicación.
line_expiration_date string (date) Opcional
Y-m-d, en el futuro.
line_status string Opcional
Uno de CONFIGURED, NOT_CONFIGURED, EXPIRED, DISABLED.
enable_instance_status_webhook int Opcional
Activa para la línea el webhook de estado de instancia.
instance_status_webhook_url string Condicional
Obligatorio siempre que el webhook esté activado.
Errores7
No data posted for update.
No se envió ni line_expiration_date ni line_status.
Line id missing.
No se incluyó line_id.
Invalid line id.
No hay ninguna línea con ese ID en esta aplicación.
Line status missing.
El campo de estado estaba presente pero vacío.
Invalid line status.
No es uno de los cuatro valores aceptados.
Line name already exists.
Otra línea ya usa esa etiqueta.
Instance Status Webhook URL is required when webhook is enabled.
enable_instance_status_webhook está activo pero falta la URL.
POST /p/{regToken}/api_line/setmaxmessagespermonth

Fijar el límite mensual de mensajes

Atención

TOKEN DE PLATAFORMA obligatorio — solicítalo al administrador de la plataforma. No se muestra en el panel del cliente. Dónde lo encuentran los administradores.

Fija cuántos mensajes puede enviar la aplicación al mes. Es el mismo límite que, al enviar, produce «You have reached the maximum limit of messages for this month.»

Además de los parámetros comunes

max_messages_per_month int Obligatorio
El nuevo límite. Mínimo 1.
Errores2
Value for max_messages_per_month is missing.
No se envió el campo.
Invalid max_messages_per_month value.
No es un número, o es menor que 1.
POST /p/{regToken}/api_line/delete

Eliminar una línea

Atención

TOKEN DE PLATAFORMA obligatorio — solicítalo al administrador de la plataforma. No se muestra en el panel del cliente. Dónde lo encuentran los administradores.

Elimina la línea, es decir, sus dos filas de gateway MASTER y SLAVE.

Además de los parámetros comunes

line_id int Obligatorio
La línea que se va a eliminar.
Errores2
Line id missing.
No se incluyó line_id.
Invalid line id.
No hay ninguna línea con ese ID en esta aplicación.
No se puede deshacer

La eliminación quita las dos filas de gateway de la línea. Todo lo que enviaba por esa línea se detiene, y la conexión debe rehacerse escaneando un QR.

POST /p/{regToken}/api_line/heartbeat

Heartbeat

Atención

TOKEN DE PLATAFORMA obligatorio — solicítalo al administrador de la plataforma. No se muestra en el panel del cliente. Dónde lo encuentran los administradores.

Comprobación de disponibilidad que además devuelve los tokens de API de la aplicación. En la primera llamada se generan para la app los tokens de Chat History y Send Message.

Parámetros

Bastan los dos parámetros comunes.

5 endpoints

Envío de mensajes

Envío de mensajes de WhatsApp: texto, multimedia, voz, grupos, líneas rotativas y plantillas de Meta Cloud API.

Cómo se enruta un envío

Todo envío intenta primero WA API MASTER y recurre a WA API SLAVE solo si el intento en el master falla.

  • Cada gateway recibe exactamente un intento por petición. No hay bucle interno de reintentos ni filtrado previo según el estado almacenado.
  • Un intento fallido marca de inmediato ese gateway como PROBABLY_DISCONNECTED, actualiza last_status_checked y recalcula la salud de la línea antes de probar el siguiente gateway.
  • Se registra telemetría de cada intento: tipo de gateway, estado, tiempos y un detalle clasificado de éxito o fallo.
  • El primer intento que tiene éxito devuelve éxito de inmediato. Si fallan los dos, recibes una respuesta de error que tiene en cuenta la salud.

Cuando fallan los dos gateways

La respuesta incluye success: false y un error_code que refleja la salud global de la línea:

error_codeCuándoMensaje
gateways_probably_disconnectedLa salud de la línea es PROBABLY_OFFLINE, o una mezcla de estados no conectados“GATEWAYS ARE PROBABLY DISCONNECTED, WE ARE CHECKING THE REAL STATUS, TRY AGAIN IN ABOUT 10 MINUTES.”
gateways_disconnectedLa salud de la línea es OFFLINE, o todos los gateways están DISCONNECTED“GATEWAYS ARE DISCONNECTED. PLEASE RECONNECT BY SCANNING THE QR CODE, THEN TRY AGAIN.”

Junto a ello vuelven line_id y app_id. La respuesta se devuelve después de que cada intento fallido haya marcado su gateway y disparado el recálculo de la salud.

Por qué línea sale el mensaje

line_idroundbin_idComportamiento
indicado—Envía por esa línea concreta.
—indicadoEl sistema elige del roundbin la línea conectada usada hace más tiempo.
indicadoindicadogana roundbin_id: se ignora line_id.
——Recurre a la línea conectada de la aplicación. Si no hay ninguna conectada: no active/connected gateway for this app — connect a line first
Nota

send_via=cloud_api se salta por completo el enrutado por línea y por roundbin: no interviene ninguna línea de WhatsApp. Antes de la llamada a Meta solo se comprueban app_id, security_token y phone.

Fallback a Meta Cloud API

Un mensaje puede salir por Meta Cloud API en lugar de la línea WhatsApp, como plantilla aprobada. Entonces el texto de message no se entrega: lo sustituye la plantilla. Ocurre en dos casos.

CasoCuándoQué plantilla
Umbral diarioLa línea ya ha enviado hoy tantos mensajes como marca su umbral diario.La de la llamada (fallback_template_*); si no, la de la línea. La de la línea se usa si Fallback Enabled está activo.
La línea no puede enviarLa línea no existe, no está conectada, está marcada DISCONNECTED o rechaza el envío (por ejemplo un número bloqueado o desconectado). También un roundbin con todas sus líneas caídas.Solo la de la llamada. Sin ella recibes el error de siempre.
  • El umbral se cuenta por línea, no por contacto, y el contador vuelve a cero a las 00:00 UTC. Solo cuentan los mensajes que pasan por el control del umbral: el fallback debe estar activo para ese mensaje (Fallback Enabled en la línea, o un fallback_template_* en la llamada) y, en modo standard, un contacto que escribió en los últimos 7 días se salta y no cuenta. Con umbral 1, el primer mensaje contado del día sale por la línea y el siguiente por Meta. El lado master y el lado slave de una línea llevan contadores separados.
  • Si falla también el envío de la plantilla, la URL Failure Webhook de la línea recibe {"event":"waba_send_failed", "app_id", "line_id", "phone", "template_name", "error", "fallback_reason", "reference", "timestamp"}. fallback_reason es null en un envío directo send_via=cloud_api, y reference es el valor que pasaste en la llamada.
  • Un número sin cuenta de WhatsApp no recibe nada: ni envío por la línea ni plantilla, porque Meta Cloud API tampoco puede alcanzarlo. La llamada devuelve el error The phone number does not exist on WhatsApp. y la URL Failure Webhook de la línea recibe el mismo evento con fallback_reason: "number_not_on_whatsapp" y template_name: null. El envío aparece en la página de Logs como fallido, no cuenta para el límite mensual, y api_send/status con su reference responde state: not_sent, status: failed. Si la comprobación no se puede hacer, el mensaje se envía como siempre. Un número cuya cuenta sigue existiendo, pero con el teléfono apagado o perdido, no se detecta.
  • El modo de umbral standard (por defecto) deja fuera a los contactos que han escrito a la aplicación en los últimos 7 días, hoy excluido: reciben siempre el mensaje normal y no se cuentan. strict cuenta cada mensaje.
  • Si la línea no responde a tiempo, no se reenvía nada por Meta. Puede que el mensaje ya haya salido, y un segundo envío lo entregaría dos veces. Envía un reference y pregunta a api_send/status antes de reintentar: te dice si el mensaje salió.
  • La respuesta indica qué camino se tomó. via vale migasender para la línea y cloud_api_fallback para un fallback, que además trae fallback_reason (threshold, line_not_found, line_disconnected, send_refused, all_lines_down) y el message_id de Meta.
  • Los estados de entrega de un fallback llegan al webhook de entrega de la línea, como en cualquier otro envío, con channel: "waba".

Lo que necesita todo endpoint de Envío de mensajes

app_id int Obligatorio
El ID de tu aplicación, arriba a la izquierda en el panel del módulo.
security_token string Obligatorio
El token de la API Send Message, generado en Ajustes → Ajustes de API con la etiqueta Send Message API Token. La API debe estar habilitada en ese mismo sitio.
Errores que puede devolver cualquier endpoint de Envío de mensajes2
Security token mismatched.
Una sola respuesta cubre cuatro casos: falta security_token, security_token incorrecto, falta app_id o app_id inexistente. Comprueba ambos en Ajustes → Ajustes de API.
Send Message API is disabled.
La API Send Message está desactivada para esta aplicación. Actívala en los ajustes de API.
POST /p/{regToken}/api_send/message

Enviar un mensaje

Envía un mensaje de WhatsApp: texto, multimedia, nota de voz, mensaje de grupo o plantilla de Meta. Los parámetros son campos del cuerpo POST, en JSON o form-data.

Autenticación

app_id int Obligatorio
El ID de tu aplicación, arriba a la izquierda en el panel del módulo.
security_token string Obligatorio
El token de la API Send Message, generado en Ajustes → Ajustes de API con la etiqueta Send Message API Token. Allí mismo debe estar habilitada la API Send Message.

Destinatario y contenido

phone string Condicional
10–14 dígitos con + inicial y prefijo de país. Opcional si envías email de un usuario registrado que tenga un teléfono válido en su perfil; en caso contrario, obligatorio. No se usa en los envíos a grupos. Si el número ya existe en la base de datos, también recibes sib_user_id.
email string Condicional
Una dirección válida que exista en la base de datos, con un número de teléfono asociado a esa cuenta. Opcional si envías phone en su lugar. Cuando envías ambos, la API comprueba que la pareja existe antes de enviar nada.
message string Condicional
El texto que se va a enviar. Opcional cuando hay file_url, ya que un archivo puede enviarse solo.
name string Opcional
Nombre: solo si además quieres registrar al usuario.
surname string Opcional
Apellido: solo si además quieres registrar al usuario.
file_url url Opcional
Cualquier URL de archivo accesible públicamente que WhatsApp admita. Máximo 25 MB. Los archivos de audio solo funcionan mientras el gateway MASTER esté activo.
is_link_preview_enabled int Opcional
1 muestra la vista previa del enlace (predeterminado), 0 la oculta.

Texto a voz

tts_enabled int Opcional
1 convierte el texto del mensaje en audio y lo envía como nota de voz en lugar de texto; 0 es el valor predeterminado. Solo gateway MASTER, y el TTS debe estar habilitado para la aplicación.
tts_voice string Opcional
OpenAI: alloy (predeterminada), echo, fable, onyx, nova, shimmer. ElevenLabs: el voice_id que aparece bajo el reproductor de la voz elegida. El proveedor se selecciona en Ajustes → Configuración de OpenAI → Servicio TTS.
tts_speed float Opcional
OpenAI: 0.25–4.0, predeterminado 1.0. ElevenLabs: 0.1–1.2. Por debajo de 1.0 el habla se ralentiza; por encima, se acelera.

Enrutado

line_id int Opcional
La línea desde la que se envía. Debe ser válida; si no se envía, vale 1. Se encuentra en Ajustes de gateway → Gestión de líneas de WhatsApp, en la columna Line ID.
roundbin_id int Opcional
Un grupo roundbin. El sistema elige de él la siguiente línea conectada disponible (rotación por uso menos reciente) y prevalece sobre line_id. Si todas las líneas del grupo están desconectadas y el roundbin tiene configurada una plantilla de reserva, se envía esa plantilla mediante Meta Cloud API.

Envío a grupo

is_sent_to_group int Opcional
1 indica a la API que es un mensaje de grupo. 0 o no enviarlo significa envío normal.
group_id string Condicional
Obligatorio cuando is_sent_to_group=1; entonces phone deja de ser necesario. Formato: 1203630000000000@g.us. Obtén los ID en el endpoint Listar los grupos de más abajo.

Envío directo por Meta Cloud API

send_via string Opcional
Ponlo en cloud_api para saltarte la línea de WhatsApp por completo y enviar una plantilla de Meta. Predeterminado migasender.
template_name string Condicional
Obligatorio cuando send_via=cloud_api. El nombre exacto de la plantilla tal como aparece en Meta Business Manager, y debe estar APPROVED.
template_language string Opcional
Código BCP-47 correspondiente al idioma de la plantilla aprobada. Predeterminado en_US.
template_variables array | string Opcional
Valores ordenados para los marcadores {{1}}, {{2}} … del cuerpo de la plantilla. Acepta un array nativo o una cadena JSON. La cantidad debe coincidir exactamente con la plantilla.
template_buttons array | string Opcional
Payloads para botones de tipo URL: cada elemento es el sufijo dinámico de la URL o el código de cupón.

Plantilla de reserva por llamada

Solo se usan cuando el mensaje acaba en el fallback: en el umbral diario de la línea, o cuando la línea no puede enviar. Para esta única petición sustituyen la plantilla de fallback configurada en la línea. Ver Fallback a Meta Cloud API más arriba.

fallback_template_name string Opcional
Nombre de una plantilla APPROVED en el WABA de la aplicación. Enviarlo activa el fallback para este mensaje, aunque esté apagado en la línea. Si también envías fallback_template_id, gana el nombre.
reference string Opcional
Tu propio identificador para este envío, hasta 255 caracteres. Vuelve como reference en el failure webhook y, si el envío agota el tiempo, puedes preguntar con él a api_send/status si el mensaje salió de verdad. Funciona para envíos por la línea y por la Cloud API, fallbacks incluidos.
not_sent_after int Opcional
Segundos sin confirmación, tras un envío que agotó el tiempo, antes de que api_send/status responda not_sent para su reference. De 60 a 86400; por defecto 180 (3 minutos).
fallback_template_id int Opcional
El ID local de la plantilla (template_id). Útil cuando varias plantillas comparten nombre en distintos idiomas. Se ignora si también envías fallback_template_name.
fallback_template_language string Opcional
Normalmente se deduce del registro de la plantilla. Envía este campo solo para forzar otro valor.
fallback_template_variables array | string Opcional
Valores para la plantilla de reserva. La cantidad se valida contra la plantilla antes de enviar nada.
fallback_template_buttons array | string Opcional
Payloads de los botones de URL en la plantilla de reserva.
Errores40
Gateway settings do not exist.
No hay gateway activo para esa combinación de app_id y line_id.
GATEWAYS ARE PROBABLY DISCONNECTED… TRY AGAIN IN ABOUT 10 MINUTES.
Respuesta según el estado de salud, error_code: gateways_probably_disconnected.
GATEWAYS ARE DISCONNECTED. PLEASE RECONNECT BY SCANNING THE QR CODE…
Respuesta según el estado de salud, error_code: gateways_disconnected.
No eligible gateway available for retry.
Durante el envío no se encontró ningún gateway operativo.
message or media is required
No se proporcionó ni message ni file_url.
phone is required
No se proporcionó ni phone ni email.
Phone number is missing or invalid. Include country code, e.g. +39123456789.
phone mal formado: debe empezar por + e incluir el prefijo de país.
The phone number does not exist on WhatsApp.
El número no tiene cuenta de WhatsApp. No se envió nada y la URL Failure Webhook de la línea recibió fallback_reason: "number_not_on_whatsapp".
The email address is invalid.
email mal formado.
No such account exists with this email and phone pair.
Enviaste ambos y esa pareja no está en la base de datos: cuando se envían los dos, la API comprueba primero el usuario. Si además envías name y surname, se crea la cuenta y recibes sib_user_id.
The phone number associated with this account is not correct. …The current one is: API_SENT_PHONE_NUMBER
Envío solo con email; la cuenta existe pero el teléfono almacenado no es válido.
No phone number is associated with this account.
Envío solo con email; la cuenta existe pero no tiene teléfono asociado.
No such account exists with this email.
Envío solo con email; no hay ninguna cuenta con esa dirección.
We are sorry but this account is already linked to one of our customers.
Envío solo con email más name/surname; la dirección ya pertenece a otro cliente.
The file does not exist.
Se indicó file_url pero en esa URL no se sirve nada.
The file size is too large. The maximum file size allowed is 25 MB.
El archivo supera el límite de 25 MB.
The file type is not supported.
El archivo no está entre los tipos admitidos; consulta la nota bajo esta tabla.
The tts_voice value is not valid.
La voz no es una de las opciones aceptadas.
The tts_speed value must be between 0.25 and 4.0.
Fuera de rango para OpenAI.
The tts_speed value must be between 0.1 and 1.2 for ElevenLabs.
Fuera de rango para ElevenLabs.
Text to Speech is not enabled for this application.
tts_enabled=1 pero el TTS está desactivado o sin configurar para la app.
Service is temporarily unavailable, please try later.
tts_enabled=1 y ningún gateway está en CONNECTED.
no active/connected gateway for this app — connect a line first
El line_id no corresponde a ningún gateway utilizable. Es también lo que recibes cuando no hay ninguna línea conectada.
Roundbin not found.
No hay ningún roundbin con ese roundbin_id en esta aplicación.
You cannot send a message because your line status is EXPIRED|DISABLED|NOT_CONFIGURED.
La línea elegida no está en estado CONFIGURED.
All lines in this roundbin are disconnected and no fallback template is set.
Todas las líneas del roundbin están caídas y no hay plantilla de reserva. Reconecta una línea o configura una plantilla.
You have reached the maximum limit of messages for this month.
El límite mensual —10.000 por defecto— cuenta todos los mensajes salientes correctos. Es un límite de plataforma, no el umbral diario.
The is_link_preview_enabled value is not valid.
Un valor distinto de 0 o 1.
The phone number does not exist on WhatsApp.
El destinatario no tiene cuenta de WhatsApp.
Group id missing.
is_sent_to_group=1 pero falta group_id o está vacío.
Group not found.
group_id no es un grupo válido. Solo se produce en WA API MASTER: el gateway slave no admite grupos ni esta validación.
template_name is required for cloud_api send.
sin nombre de plantilla.
Template requires {N} variables, {M} provided.
La cantidad de template_variables no coincide con la definición de la plantilla.
Fallback template not found or not approved.
fallback_template_id no corresponde a ninguna plantilla APPROVED de esta aplicación. Vuelve a sincronizar las plantillas desde Meta.
Fallback template '{name}' requires {N} variables, {M} provided.
La cantidad de variables no coincide en la plantilla de reserva de esta llamada.
{line error} Fallback template send failed: {reason}
La línea no pudo enviar, y la plantilla de fallback también fue rechazada. No se entregó nada. La primera parte dice por qué falló la línea, la segunda por qué la rechazó Meta.
{line error} Fallback template not delivered: {reason}
La línea no pudo enviar. Meta aceptó la plantilla de fallback y después la notificó como no entregada.
(#190) Access token has expired
El token de acceso de Meta WABA ha caducado. Reconecta desde la página de configuración de WABA.
(#132000) Variable parameter count mismatch
Meta rechazó la llamada a la plantilla: la cantidad de variables no coincide con la definición del lado de Meta.
(#131005) …
Un error de límite o de permisos de Meta Cloud API. Comprueba el estado de la cuenta WABA en Meta Business Manager.
Tipos de archivo admitidos

Imágenes image/jpeg, image/jpg, image/png · Vídeo video/mp4, video/ogg, application/octet-stream · Audio audio/mpeg, audio/ogg · Documentos application/pdf, application/msword, tipos OpenXML de Word/Excel/PowerPoint, application/vnd.ms-excel, application/vnd.ms-powerpoint, text/plain, text/html, text/css, application/ics.

La reserva no es lo mismo que un envío directo por Cloud API

send_via=cloud_api pasa siempre por Meta, diga lo que diga el contador diario. Los parámetros fallback_template_* solo actúan sobre un envío por la línea (migasender): la plantilla sale cuando se alcanza el umbral diario de la línea, o cuando la línea no puede enviar. Un fallback por llamada sustituye al configurado en la línea solo para esa petición.

El idioma de la plantilla debe coincidir exactamente

Los códigos de idioma deben coincidir con la plantilla aprobada en Meta: it, en_US, en, pt_BR. Si no coinciden, Meta devuelve un error de plantilla no encontrada.

Una reserva por umbral que Meta también rechaza

Recibes HTTP 200 con el campo de error relleno y el mensaje real de Meta propagado, por ejemplo { "error": "(#190) Access token has expired", "data": null }. Se alcanzó el umbral diario de la línea y el envío a Meta falló, así que no se entregó nada.

POST /p/{regToken}/api_send/checkphone

Comprobar un número de teléfono

Responde si un número existe en WhatsApp. Solo tres parámetros. La misma comprobación se ejecuta dentro del endpoint de envío.

app_id int Obligatorio
El ID de tu aplicación.
security_token string Obligatorio
El token de la API Send Message.
phone string Obligatorio
10–14 dígitos con + inicial y prefijo de país.
Errores2
The service is currently unavailable due to an issue with the WA API Master. Please try again later.
El servidor MASTER está caído; este endpoint no tiene respaldo en el slave.
The phone number is not correct. Please add a phone between 10-14 digits with + international country code at the beginning.
phone mal formado.
POST /p/{regToken}/api_send/status

Consultar el estado de un mensaje enviado

Dice qué pasó con un mensaje después del envío: por el message_id que devolvió el envío, o por tu propio reference cuando el envío agotó el tiempo y no devolvió ningún id.

app_id int Obligatorio
El ID de tu aplicación.
security_token string Obligatorio
El token de la API Send Message.
message_id string Condicional
El message_id devuelto por el envío (un id de la línea o un wamid de la Cloud API). Envía este o reference.
reference string Condicional
El reference que pasaste en el envío: un envío por la línea, un envío directo send_via=cloud_api, o uno que el fallback pasó a la Cloud API. Úsalo cuando el envío agotó el tiempo y no devolvió un message_id: la respuesta dice si el mensaje salió de verdad.
Errores3
message_id is required.
No se envió ni message_id ni reference.
message_id not found.
No hay ningún mensaje con ese id en esta aplicación.
reference not found.
Ningún envío llevaba ese reference: el envío nunca llegó a una línea (rechazado o no válido), o el reference es incorrecto. Un envío rechazado porque el número no tiene WhatsApp sí tiene registro: responde not_sent.
POST /p/{regToken}/api_send/groups

Listar los grupos de una línea

Devuelve todos los grupos de WhatsApp a los que pertenece la línea, con los valores group_id que necesitas para un envío a grupo.

app_id int Obligatorio
El ID de tu aplicación.
security_token string Obligatorio
El token de la API Send Message.
line_id int Opcional
Si no se envía, vale 1.
POST /p/{regToken}/api_send/heartbeat

Heartbeat

Confirma que la API Send Message está accesible y que se aceptan tu token y tu app ID. Admite los mismos parámetros que el endpoint de envío, pero no envía nada.

Parámetros

Bastan los dos parámetros comunes.

Forma de la respuesta

El documento oficial no incluye un cuerpo de ejemplo para los endpoints heartbeat, así que aquí no se reproduce ninguno. Considera accesible una respuesta con error: null, y consulta la tabla de errores de arriba para los casos de fallo.

2 endpoints

Historial de chat

Lectura de las conversaciones almacenadas, con filtros por teléfono, email, fecha, línea, origen, destino y dirección.

Qué se devuelve

Los mensajes con multimedia aparecen en la misma clave message que el texto. Cuando un mensaje tiene ambos, el texto precede a la URL del archivo.

Cada registro lleva un campo in_out: IN para entrantes, OUT para salientes.

Importante

filter_start_time se compara con el reloj de tu servidor, así que la zona horaria de la aplicación o del servidor debe estar bien configurada para que signifique lo que esperas.

Lo que necesita todo endpoint de Historial de chat

app_id int Obligatorio
El ID de tu aplicación.
security_token string Obligatorio
El token de la API Chat History, generado en Ajustes → Ajustes de API con la etiqueta Chat History API Token. La API debe estar habilitada en ese mismo sitio.
Errores que pueden devolver ambos endpoints de Historial de chat2
Security token mismatched.
Una sola respuesta cubre cuatro casos: falta security_token, security_token incorrecto, falta app_id o app_id inexistente. Comprueba ambos en Ajustes → Ajustes de API.
Chat History API is disabled.
La API Chat History está desactivada para esta aplicación. Actívala en los ajustes de API.
GET /p/{regToken}/api_chathistory/history

Leer el historial de chat

Devuelve los mensajes almacenados de la aplicación. Todos los filtros son opcionales y se combinan entre sí.

Nota

La documentación más antigua presenta este endpoint como POST. Es un GET, y los filtros son parámetros de la cadena de consulta.

Autenticación

app_id int Obligatorio
El ID de tu aplicación.
security_token string Obligatorio
El token de la API Chat History, generado en Ajustes → Ajustes de API con la etiqueta Chat History API Token. Allí mismo debe estar habilitada la API Chat History.

Filtros

filter_history_id int Opcional
El ID de chat o de registro desde el que empezar: con 10 obtienes el historial a partir de 10.
filter_start_date string (date) Opcional
yyyy-mm-dd. Se compara con el created_at del registro; devuelve el historial a partir de esa fecha.
filter_start_time string (time) Opcional
HH:mm:ss. Solo válido junto con filter_start_date. Usa la zona horaria del servidor.
filter_phone_number string (phone) Opcional
10–14 dígitos con + inicial y prefijo de país.
filter_email string (email) Opcional
Filtra por el email de un cliente, si el cliente existe y tiene uno asignado.
filter_origin string Opcional
Uno de WA API MASTER, WA API SLAVE, MIGACHAT, API, WEBHOOK. Los mensajes enviados desde una línea con api_send/message solo se devuelven al filtrar por API.
filter_destination string Opcional
Uno de WA API MASTER, WA API SLAVE, MIGACHAT, WEBHOOK, WA_USER.
filter_line_id int Opcional
Se acepta pero no se aplica. La petición funciona y el valor se ignora, así que el resultado no queda limitado a esa línea. Por ahora, filtra por línea en tu lado.
filter_in_out string Opcional
Se acepta pero no se aplica. IN / OUT se ignoran; cada registro lleva su propio campo in_out, así que filtra por él después de leer.
Errores1
This app has not yet configured the gateway settings so you cannot get the history.
La app no tiene ningún gateway configurado.
Los filtros no se validan: un valor incorrecto se ignora, no se rechaza

Una fecha mal formada, un origen fuera de la lista, una dirección que no es ni IN ni OUT: nada de eso se rechaza. Sencillamente no se aplica el filtro y recibes el resultado sin filtrar con error: null. Valida los valores de los filtros antes de enviarlos y compara el número de filas con lo que esperabas, en lugar de suponer que un error vacío significa que el filtro se entendió.

GET /p/{regToken}/api_chathistory/heartbeat

Heartbeat

Confirma que la API Chat History está accesible y que se acepta tu token.

Nota

La documentación más antigua indica esta ruta como api_chat/heartbeat. La ruta actual es api_chathistory/heartbeat, y acepta tanto GET como POST.

Parámetros

Bastan los dos parámetros comunes.

Forma de la respuesta

El documento oficial no incluye un cuerpo de ejemplo para los endpoints heartbeat, así que aquí no se reproduce ninguno. Considera accesible una respuesta con error: null.

5 endpoints · v2.0.0

Código QR

Conectar un número de WhatsApp a una línea: obtener el código QR, seguir el escaneo y comprobar después el estado de la línea.

Atención

TOKEN DE PLATAFORMA obligatorio — solicítalo al administrador de la plataforma. No se muestra en el panel del cliente. Dónde lo encuentran los administradores.

Qué cambió en la v2.0.0

  • /get ahora reutiliza por defecto el mismo instance_id pendiente, de modo que las llamadas repetidas ya no acumulan sesiones duplicadas.
  • Envía action=RESET o reset=1 para forzar deliberadamente una instancia y un QR nuevos.
  • Las peticiones de QR tienen límite de frecuencia a nivel de línea, app y plataforma, configurable en el backoffice.
  • Los contadores de QR de una línea se reinician automáticamente cuando un escaneo tiene éxito.
  • Los errores de límite indican exactamente cuándo termina la espera.

Límites de frecuencia predeterminados

NivelIntervalo mínimoVentanaPeticiones máx.Espera
Línea30s600s51800s
App—600s201800s
Global—600s1001800s

Los nueve valores se pueden editar en el backoffice, en QR Code API Rate Limits.

Parámetros que necesita todo endpoint de QR

platform_token string Obligatorio
Token de toda la plataforma, desde el backoffice, sección Platform Token for API. También puede enviarse como cabecera X-Platform-Token.
app_id int Obligatorio
El ID de tu aplicación, arriba a la izquierda en el panel del módulo.
line_id int Obligatorio
La línea sobre la que quieres actuar.
whatsapp_gateway_type string Obligatorio
Qué gateway de la línea: WA API MASTER o WA API SLAVE.
action / reset string / int Opcional
Envía action=RESET o reset=1 para forzar una instancia y un QR nuevos. Sin eso, /get reutiliza el instance_id pendiente en lugar de abrir una sesión duplicada.
Errores que puede devolver cualquier endpoint de QR15
Platform token missing.
Ni platform_token ni cabecera X-Platform-Token.
Platform settings not found.
La plataforma no tiene ningún ajuste.
Platform token not found.
Los ajustes existen, pero no tienen guardado ningún token de plataforma.
Platform token mismatched.
El token enviado no es el de la plataforma.
App id missing.
No se envió app_id.
Invalid app id.
Ninguna aplicación coincide con ese app_id.
Line id missing.
No se envió line_id.
WhatsApp gateway type is missing.
Toda petición debe indicar qué gateway: WA API MASTER o WA API SLAVE.
WhatsApp gateway type is invalid.
El valor enviado no es ninguno de los dos aceptados.
Line settings do not exist.
La combinación de parámetros enviada no corresponde a ninguna línea.
Line status is EXPIRED | DISABLED.
Una línea en cualquiera de esos dos estados no se puede manipular.
Line QR rate limit reached (max X requests per Y seconds). Please wait until YYYY-MM-DD HH:MM:SS before trying again.
Límite por línea. El mensaje indica la hora exacta en que termina la espera.
App QR rate limit reached (max X requests per Y seconds). Please wait until YYYY-MM-DD HH:MM:SS before trying again.
Límite por aplicación.
Platform QR rate limit reached (max X requests per Y seconds). Please wait until YYYY-MM-DD HH:MM:SS before trying again.
Límite de toda la plataforma.
Please wait 25s before requesting a new QR code for this line. Next allowed at YYYY-MM-DD HH:MM:SS.
El intervalo mínimo entre dos peticiones de QR en la misma línea.
POST /p/{regToken}/api_qr/get

Obtener un código QR

Atención

TOKEN DE PLATAFORMA obligatorio — solicítalo al administrador de la plataforma. No se muestra en el panel del cliente. Dónde lo encuentran los administradores.

Devuelve un PNG en base64 para mostrarlo y escanearlo, más el instance_id que necesitarás para seguir el escaneo.

Además de los parámetros comunes

phone string Obligatorio
10–14 dígitos con + inicial y prefijo de país. Debe ser único por línea y debe ser el mismo número que escaneará el QR.
Errores4
Phone is missing.
No se envió phone, o está vacío.
The phone number is not correct. Please add a phone between 10-14 digits with + international country code at the beginning.
phone mal formado.
This phone number is already used.
Otra línea ya usa ese número.
This gateway for the line is already working. You cannot get the QR code for it.
El gateway ya está conectado: no hay nada que escanear.
El QR caduca en 30 segundos

Inserta la cadena base64 directamente en una etiqueta <img>. Si no se escanea en 30 segundos, caduca y puede dejar de funcionar. Guarda el instance_id: lo necesitan todas las llamadas siguientes.

Después, empieza a consultar

En cuanto el QR esté en pantalla, llama a check-scan-status cada 2000 ms con el instance_id (y el team_id en un gateway slave) hasta que informe de éxito.

POST /p/{regToken}/api_qr/check-scan-status

Comprobar el estado del escaneo

Atención

TOKEN DE PLATAFORMA obligatorio — solicítalo al administrador de la plataforma. No se muestra en el panel del cliente. Dónde lo encuentran los administradores.

Consulta este endpoint tras mostrar el QR para saber si ya se ha escaneado.

Además de los parámetros comunes

instance_id string Obligatorio
El ID de instancia que devolvió /get.
team_id int Condicional
Obligatorio solo en WA API SLAVE, donde /get lo devolvió. No se usa en MASTER.
Errores2
Instance ID is missing.
No se envió instance_id.
Team id is missing.
Una llamada a un gateway slave sin team_id.
Frecuencia de consulta

Llama cada 2000 ms mientras se muestre el QR. Detente en cuanto status sea success y message sea Success.

POST /p/{regToken}/api_qr/get-current-status

Obtener el estado actual

Atención

TOKEN DE PLATAFORMA obligatorio — solicítalo al administrador de la plataforma. No se muestra en el panel del cliente. Dónde lo encuentran los administradores.

Indica si una instancia guardada está funcionando ahora mismo. Guarda el instance_id en local después de /get y úsalo aquí siempre que necesites el estado real.

Además de los parámetros comunes

instance_id string Obligatorio
El ID de instancia devuelto por /get, guardado en tu propia base de datos.
Errores2
Instance ID is missing.
No se envió instance_id.
Instance ID mismatched.
Esa instancia no pertenece a los ajustes de gateway encontrados.
POST /p/{regToken}/api_qr/rescan

Volver a escanear

Atención

TOKEN DE PLATAFORMA obligatorio — solicítalo al administrador de la plataforma. No se muestra en el panel del cliente. Dónde lo encuentran los administradores.

Devuelve un QR nuevo para una instancia que ha dejado de funcionar, para poder reconectar el número.

Además de los parámetros comunes

instance_id string Obligatorio
El ID de la instancia que se va a reconectar. Solo tiene sentido cuando esa instancia está NOT_WORKING.
Errores5
Instance ID is missing.
No se envió instance_id.
Instance ID mismatched.
Esa instancia no pertenece a los ajustes de gateway encontrados.
Line status is NOT_CONFIGURED.
La línea nunca se configuró, así que no hay estado que recuperar.
This instance is not configured.
La línea está CONFIGURED pero no para esta instancia: una línea puede tener al menos dos.
This instance is already working.
No hay nada que volver a escanear.
Volver a escanear también tiene límite de frecuencia

Se aplican los mismos límites de línea, app y globales. Después consulta check-scan-status cada 2000 ms, igual que tras /get.

POST /p/{regToken}/api_qr/get-instance-info

Obtener información de la instancia

Atención

TOKEN DE PLATAFORMA obligatorio — solicítalo al administrador de la plataforma. No se muestra en el panel del cliente. Dónde lo encuentran los administradores.

Devuelve el token de acceso del gateway, el teléfono asociado y el estado tanto de la línea como de la instancia. Funciona solo con los parámetros comunes: cambia whatsapp_gateway_type para consultar el otro gateway.

Parámetros

Sin parámetros adicionales: bastan los cuatro comunes.

Errores1
Instance not found.
No existe esa instancia ni esa línea en el sistema.

2 endpoints · v1.0.0

Grupos

Crear grupos de WhatsApp desde un sistema externo y leer lo que se dijo en ellos.

Atención

TOKEN DE PLATAFORMA obligatorio — solicítalo al administrador de la plataforma. No se muestra en el panel del cliente. Dónde lo encuentran los administradores.

Antes de la primera llamada

Esta familia se autentica con un único token de plataforma, enviado como cabecera X-Platform-Token o como campo platform_token del cuerpo. La creación de grupos pasa por una línea de agente de IA dedicada, que hay que configurar antes.

En el backoffice, en AI Agent Settings, rellena los seis campos:

  • AI Agent Name
  • AI Agent Instance ID
  • AI Agent Access Token
  • AI Agent Phone — E.164, por ejemplo +391234567890
  • AI Agent Gateway API URL
  • AI Agent Gateway API Key

En esa misma pantalla están el Platform Token for API para copiar, los Group Creation Logs con los grupos creados y fallidos, y el visor Group Chat History con filtros, enlaces a multimedia y una insignia ADMIN en los mensajes del propio agente.

Todos los endpoints responden con la misma estructura: { "error": null | string, "data": object | null }.

Parámetro que necesita todo endpoint de Grupos

platform_token string Obligatorio
Token de toda la plataforma, desde el backoffice. Puede enviarse como cabecera X-Platform-Token en lugar de como campo del cuerpo.
POST /p/{regToken}/api_group/create

Crear un grupo

Atención

TOKEN DE PLATAFORMA obligatorio — solicítalo al administrador de la plataforma. No se muestra en el panel del cliente. Dónde lo encuentran los administradores.

Crea un grupo de WhatsApp con el agente de IA como creador y administrador. El cuerpo es JSON en bruto.

Además del token de plataforma

members array Obligatorio
Al menos 2 números de teléfono en formato E.164 con + inicial. El agente de IA se añade además, así que el grupo más pequeño posible es de 3 personas.
group_name string Opcional
El título del grupo. Si se omite, el gateway genera un nombre predeterminado.
description string Opcional
La descripción del grupo.
metadata object Opcional
Cualquier dato que quieras guardar junto al grupo: match_id, source, etcétera.
Errores6
Platform token missing.
Ningún token ni en la cabecera ni en el cuerpo.
Platform token mismatched.
El token enviado no es el de la plataforma.
At least 2 member phone numbers are required.
Menos de dos números válidos, y además deben existir en WhatsApp.
Invalid member phone number. Use +countrycode format.
Uno de los números no está en formato E.164.
Invalid date for line_expiration_date. Date should be greater than the current date.
line_expiration_date está en el pasado.
AI agent instance ID is missing in settings.
Los ajustes AI Agent Settings del backoffice están incompletos.
De dónde salen las credenciales del gateway

La Gateway API URL y la API Key usadas para la creación se leen de AI Agent Settings: nunca las envías en la llamada.

POST /p/{regToken}/api_group/history

Obtener el historial de chat del grupo

Atención

TOKEN DE PLATAFORMA obligatorio — solicítalo al administrador de la plataforma. No se muestra en el panel del cliente. Dónde lo encuentran los administradores.

Devuelve los mensajes del grupo paginados, junto con los filtros que aplicaste.

Nota

La documentación más antigua presenta este endpoint como GET con parámetros de consulta. Es un POST, y los filtros van en el cuerpo JSON.

Filtros: todos opcionales, pero envía al menos uno

group_id string Opcional
Filtrar por ID de grupo. Preferible al nombre.
group_name string Opcional
Filtrar por nombre de grupo, que se traduce a un ID de grupo.
member_phone string Opcional
Filtrar por remitente, en formato +123….
from_date string (date) Opcional
YYYY-MM-DD.
to_date string (date) Opcional
YYYY-MM-DD.
search string Opcional
Búsqueda libre dentro de los mensajes.
page int Opcional
Predeterminado 1.
limit int Opcional
Predeterminado 50, máximo 200.

1 endpoint

Configuración automática de Migachat

Aprovisionar el asistente de IA en una línea con una sola llamada: instancia, credenciales, prompt y todos los tokens que necesitarás después.

Qué hace un solo POST

Pensado para sistemas externos —paneles de facturación, CRM— para poner en marcha MigaChat dentro de una aplicación concreta y en una línea de WhatsApp concreta sin que nadie abra el backoffice. Una sola petición:

  • añade y activa la función MigaChat en la app,
  • guarda las credenciales de OpenAI (clave de API, ID de organización, modelo),
  • inserta el prompt de sistema del chatbot,
  • vincula la línea de WhatsApp con la instancia de MigaChat,
  • y devuelve los tokens de Bridge, Chat History y Send Message.
POST /p/{regToken}/api_migachat-setup/setup

Aprovisionar MigaChat en una línea

Crea y configura una instancia de MigaChat y la vincula a una línea de WhatsApp.

Nota

A este endpoint también se llega sin el prefijo /p/<token>/, en /api_migachat-setup/setup. Ambas rutas están activas; en la que lleva prefijo, el registration token puede venir de la ruta en lugar del cuerpo.

Obligatorios

app_id int Obligatorio
El ID de tu aplicación.
security_token string Obligatorio
El security token de tu plataforma.
line_id int Obligatorio
La línea de WhatsApp a la que vincular MigaChat.
openai_api_key string Obligatorio
Tu clave secreta de OpenAI. Se valida contra OpenAI antes de guardar nada.
organization_id string Obligatorio
El ID de tu organización de OpenAI.
gpt_model string Obligatorio
El modelo que se va a usar, por ejemplo gpt-4o-mini.
prompt string Obligatorio
El prompt de sistema: las instrucciones permanentes del chatbot.

Opcionales

chat_type string Opcional
chatgpt (predeterminado) o assistant.
enable_stt int Opcional
1 activa el reconocimiento de voz. Predeterminado 0.
enable_tts int Opcional
1 activa la síntesis de voz. Predeterminado 0.
overwrite int Opcional
1 sustituye una instancia de MigaChat ya existente en esta línea. Predeterminado 0, que en su lugar falla.
Errores5
MigaChat not installed
El módulo MigaChat no está instalado en este servidor.
Invalid Line ID
Ese line_id no pertenece a ese app_id.
Already configured
La línea ya tiene una instancia de MigaChat. Envía overwrite=1 para sustituirla.
Invalid OpenAI Key
No se pudo validar la clave con OpenAI.
missing required fields: app_id, line_id, openai_api_key, …
La respuesta enumera todos los campos obligatorios que faltaban o estaban vacíos.