Documentación de la API
Dos formas de integrar: la API por instancia (compatible con UltraMsg, la más simple) y la API nativa.
API por instancia
Es la forma más simple de integrar. Cada número conectado es una instancia con su número y su token propios, que ves en el panel (/app → Instancias → Gestionar).
https://api.tudominio.com/instance{ID}/{ruta}?token={TOKEN}
api.ultramsg.com por api.tudominio.com y pon el ID y el token de tu instancia.Reglas generales
- El
tokenva en la URL (?token=) o en el cuerpo del POST. - El cuerpo de un POST puede ir como
application/x-www-form-urlencoded,application/jsonomultipart/form-data(este último permite subir el archivo directo en vez de una URL). - Los teléfonos van en formato internacional:
+51977700001o51977700001. También se acepta un chatID:[email protected]o un grupo[email protected]. - Los errores responden
{"error": "..."}con HTTP 200, salvo instancia inexistente (404) y token inválido (401). Revisa el cuerpo, no solo el código HTTP. - Los envíos no salen en el acto: entran a una cola que respeta el retraso configurado en la instancia
(evita que WhatsApp bloquee el número). La respuesta te da el
idpara seguirlo.
Enviar mensajes
curl -X POST "https://api.tudominio.com/instance1001/messages/chat" \
--data-urlencode "token=TU_TOKEN" \
--data-urlencode "to=+51977700001" \
--data-urlencode "body=Hola desde la API"
Respuesta:
{ "sent": "true", "message": "ok", "id": 45 }
Campos comunes a todos los envíos
| Campo | Descripción |
|---|---|
to | Destino. Varios separados por coma (hasta 500); cada uno genera su propio mensaje y la respuesta trae también ids. |
priority | Orden en la cola: menor sale antes. Por defecto 10. Para codigos OTP usa 1. |
referenceId | Tu propio identificador (hasta 255). Vuelve en GET /messages y en los webhooks. |
msgId | Para responder citando un mensaje: el id que llego en el webhook. |
mentions | Telefonos a mencionar, separados por coma (en grupos). |
Rutas de envío
| Ruta | Campos propios |
|---|---|
POST /messages/chat | body (texto, hasta 65536) |
POST /messages/image | image (URL, base64 o archivo), caption |
POST /messages/document | document, filename (obligatorio), caption |
POST /messages/audio | audio |
POST /messages/voice | audio — llega como nota de voz |
POST /messages/video | video, caption |
POST /messages/sticker | sticker (jpg, png, gif o webp; se convierte solo) |
POST /messages/contact | contact: chatID(s) del contacto, separados por coma |
POST /messages/vcard | vcard: texto vCard completo (puedes armarlo en el panel) |
POST /messages/location | address (1a linea = nombre del lugar), lat, lng |
POST /messages/reaction | msgId, emoji (vacío = quitar la reacción) |
POST /messages/delete | msgId — borra para todos un mensaje propio |
La media puede ser una URL pública, un base64 (con o sin prefijo data:) o el archivo en
multipart/form-data. Hasta 30 MB.
Cola y estado de los mensajes
| Estado | Qué significa |
|---|---|
queue | En cola, esperando su turno o a que la instancia este conectada |
sent | Enviado a WhatsApp |
unsent | Falló al enviar después de los reintentos |
invalid | El número no tiene WhatsApp (se verifica antes de enviar) |
expired | Pasó más de 24 h en cola sin poder salir |
El ack dice hasta donde llego un mensaje enviado: pending, server
(salio), device (entregado), read (leido) o played (audio escuchado).
| Ruta | Qué hace |
|---|---|
GET /messages | Listado de enviados. Filtros: page, limit (max 100), status (all o uno de arriba), sort (asc/desc), id, referenceId, to, ack, msgId, start_date y end_date (epoch en segundos) |
GET /messages/statistics | Cuantos hay en cada estado |
POST /messages/resendByStatus | status = unsent o expired: los vuelve a poner en cola |
POST /messages/resendById | id: reencola uno que no salio |
POST /messages/clear | status: borra del registro los mensajes de ese estado |
{
"total": 1, "pages": 1, "limit": 100, "page": 1,
"messages": [{
"id": 45, "referenceId": "pedido-881",
"from": "[email protected]", "to": "[email protected]",
"body": "Hola desde la API", "priority": 10,
"status": "sent", "failed_reason": "", "ack": "device", "type": "chat",
"created_at": 1790000000, "sent_at": 1790000002, "metadata": {}
}]
}
Instancia y ajustes
| Ruta | Qué hace |
|---|---|
GET /instance/status | accountStatus.status: authenticated, qr, loading, initialize o disconnected |
GET /instance/qr | Imagen PNG del QR para vincular |
GET /instance/qrCode | El QR como texto ({"qrCode": "..."}) |
GET /instance/me | Datos del número conectado: id, nombre, foto, si es empresa |
GET /instance/settings | Ajustes actuales |
POST /instance/settings | Cambia los ajustes (solo los campos que mandes, ver abajo) |
POST /instance/restart | Reinicia la conexión con WhatsApp |
POST /instance/logout | Cierra la sesión de WhatsApp (hay que volver a escanear) |
POST /instance/clear | Reset: cierra la sesión, borra todo el registro de mensajes y deja los ajustes de fábrica. El token no cambia |
| Ajuste | Descripción |
|---|---|
sendDelay | Segundos entre envíos cuando la cola tiene menos de 10 (por defecto 1) |
sendDelayMax | Segundos entre envíos cuando la cola tiene 10 o más (por defecto 15) |
webhook_url | Adonde se envían los webhooks; vacío = ninguno |
webhook_retries | Reintentos si tu sistema no responde 200 (0 a 10, por defecto 3) |
webhook_message_received | true/false: avisar mensajes recibidos |
webhook_message_create | Avisar mensajes enviados, incluidos los escritos desde el teléfono |
webhook_message_ack | Avisar cambios de ACK |
webhook_message_download_media | Incluir en el webhook la URL del archivo recibido |
webhook_message_reaction | Avisar reacciones |
Chats, contactos, grupos y archivos
| Ruta | Qué hace |
|---|---|
GET /chats · /chats/ids | Conversaciones del número |
GET /chats/messages | chatId, limit (por defecto 50): últimos mensajes de un chat |
POST /chats/archive · unarchive · read · clearMessages · delete | chatId |
GET /contacts · /contacts/ids | Contactos conocidos |
GET /contacts/contact | chatId: datos de un contacto |
GET /contacts/check | chatId, nocache: {"status":"valid"} si el número tiene WhatsApp, invalid si no |
GET /contacts/image | chatId: URL de la foto de perfil |
GET /contacts/blocked · /contacts/invalid | Bloqueados · números a los que se intentó enviar sin WhatsApp |
POST /contacts/block · /contacts/unblock | chatId |
GET /groups · /groups/ids | Grupos en los que está el número |
GET /groups/group | groupId: datos y participantes |
POST /media/upload | file (multipart, URL o base64, hasta 30 MB): devuelve una URL para usar en los envíos |
POST /media/delete | url de un archivo subido |
POST /media/deleteByDate | date = mes-anio (ej. 1-2026): borra los subidos ese mes |
Webhooks
Se activan por instancia (panel o POST /instance/settings). Cada evento llega por POST en JSON:
{
"event_type": "message_received",
"instanceId": "1001",
"id": "",
"referenceId": "",
"hash": "0b6c1f0e-...",
"data": {
"id": "[email protected]_3EB02E5EB89CE03FB034",
"from": "[email protected]",
"to": "[email protected]",
"author": "",
"pushname": "Ana",
"ack": "",
"type": "chat",
"body": "Hola",
"media": "",
"fromMe": false,
"isForwarded": false,
"isMentioned": false,
"quotedMsg": {},
"mentionedIds": [],
"time": 1790000000
}
}
| event_type | Cuando |
|---|---|
message_received | Llega un mensaje de otra persona |
message_create | Se envía un mensaje desde la instancia o desde el teléfono (fromMe: true) |
message_ack | Cambia el ack de un mensaje enviado; id y referenceId de la raíz son los de tu envío |
message_reaction | Alguien reacciona; data.reaction trae emoji y msgId |
- Para responder citando, usa
data.idcomomsgId. Para contestar, usadata.fromcomoto. - En grupos,
fromes el grupo yauthorquien escribio. hashes único por evento: si un reintento te llega dos veces, descártalo por ese valor.- Responde HTTP 200 rápido. Si no, se reintenta según
webhook_retries.
Menú de bot
Sin programar nada, desde el panel (Instancias → Menú de bot) puedes configurar un mensaje de
bienvenida, respuestas automáticas por comando (texto, imagen, audio, nota de voz, video, documento, enlace,
contacto, ubicación o vCard) y un mensaje para cuando el comando no existe. Las respuestas pasan por la misma
cola y aparecen en GET /messages con referenceId = "bot".
API nativa
Una sola API key para todos tus números, con respuestas y errores en formato REST. Base de las llamadas:
https://api.tudominio.com
Autenticación
Toda petición lleva tu API key en la cabecera Authorization:
Authorization: Bearer wsk_tu_api_key
También se acepta X-API-Key: wsk_... o ?api_key=wsk_... en la URL.
La variante en la URL existe para poder poner un archivo de media directamente en un <img src>.
Limite: 120 peticiones por minuto por cuenta (ampliable en el plan Pro).
Errores
Los errores siempre devuelven este formato:
{
"error": {
"code": "session_not_connected",
"message": "La sesion 1f2e... no esta conectada (estado actual: qr)",
"details": null
}
}
| HTTP | code | Qué significa |
|---|---|---|
| 401 | unauthorized | API key ausente, inválida o revocada |
| 404 | not_found | El recurso no existe o no es de tu cuenta |
| 409 | session_not_started | La sesión no está iniciada; llama a /connect |
| 409 | session_not_connected | La sesión existe pero el número no está vinculado |
| 422 | validation_error | Cuerpo inválido; details dice qué campo |
| 429 | rate_limited | Superaste el limite de peticiones |
| 502 | whatsapp_error | WhatsApp rechazó la operación |
Crear y conectar una sesión
Una sesión equivale a un número de WhatsApp vinculado.
POST /v1/sessions
{
"name": "ventas",
"webhookUrl": "https://tusistema.com/webhooks/whatsapp",
"webhookEvents": ["*"],
"connect": true
}
Con "connect": true la respuesta ya trae el QR listo para mostrar:
{
"id": "3f9c1a2e-...",
"name": "ventas",
"status": "qr",
"qrImage": "data:image/png;base64,iVBORw0...",
"webhookSecret": "a1b2c3..."
}
webhookSecret: es con lo que verificas que los webhooks vienen de nosotros.Obtener el QR
GET /v1/sessions/{id}/qr — devuelve el QR vigente. Caduca cada ~60 segundos y se renueva solo.
GET /v1/sessions/{id}/qr/stream — stream SSE para un panel web: el QR se refresca solo y avisa cuando conecta.
const es = new EventSource(`/v1/sessions/${id}/qr/stream?api_key=${key}`);
es.addEventListener('qr', e => img.src = JSON.parse(e.data).qrImage);
es.addEventListener('connected', e => { es.close(); location.reload(); });
POST /v1/sessions/{id}/pairing-code — alternativa sin QR: envías {"phone":"51977700001"} y WhatsApp pide un código de 8 dígitos.
Estado y control
| Método | Ruta | Qué hace |
|---|---|---|
| GET | /v1/sessions | Lista tus sesiones |
| GET | /v1/sessions/{id} | Detalle y estado |
| PATCH | /v1/sessions/{id} | Cambia nombre, webhook o eventos |
| POST | /v1/sessions/{id}/connect | Inicia la conexión |
| POST | /v1/sessions/{id}/disconnect | Cierra el socket, conserva la vinculación |
| POST | /v1/sessions/{id}/logout | Desvincula el número (habrá QR nuevo) |
| POST | /v1/sessions/{id}/restart | Reinicia la sesión |
| DELETE | /v1/sessions/{id} | Elimina la sesión y su historial |
Estados posibles: created → connecting → qr → connected, y disconnected / logged_out / banned.
Enviar mensajes
curl -X POST https://api.tudominio.com/v1/sessions/{id}/messages/text \
-H "Authorization: Bearer TU_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to":"51977700001","text":"Tu pedido #1234 ya salio 🚚"}'
Respuesta 202: el mensaje entra a la cola y se envía respetando el espaciado que protege tu número.
{ "id":"8b2...", "waMessageId":null, "status":"pending", "to":"[email protected]" }
Campos comunes a todos los envíos
| Campo | Tipo | Para que sirve |
|---|---|---|
to | texto | Número en formato internacional sin + (51977700001) o el id de un grupo |
wait | bool | true espera hasta 15 s la confirmación y devuelve el waMessageId real |
delaySeconds | entero | Programa el envío para más tarde |
quotedMessageId | texto | Responde citando ese mensaje |
Tipos de mensaje
Todas cuelgan de /v1/sessions/{id}/messages/. En las de archivo se manda url o base64.
| Ruta | Campos propios |
|---|---|
/text | text, mentions[], linkPreview |
/image | url|base64, caption |
/video | url|base64, caption, gifPlayback |
/audio | url|base64, ptt (nota de voz) |
/document | url|base64, filename, caption |
/sticker | url|base64 — debe ser .webp |
/location | latitude, longitude, name, address |
/contact | contacts[] con fullName, phone |
/reaction | messageId, emoji (vacío = quitar) |
/poll | name, options[], selectableCount |
Historial y media
| Método | Ruta | Qué hace |
|---|---|---|
| GET | /v1/sessions/{id}/messages | Historial. Filtros: chat, direction, status, limit |
| GET | /v1/sessions/{id}/messages/{msgId} | Detalle de un mensaje |
| GET | /v1/sessions/{id}/media/{msgId} | Descarga el archivo adjunto |
Chats
| Método | Ruta | Cuerpo |
|---|---|---|
| POST | /chats/typing | to, state, durationSeconds |
| POST | /chats/read | to, messageIds[] |
| DELETE | /chats/messages/{msgId} | Elimina para todos |
| POST | /chats/archive | to, archive |
| POST | /chats/mute | to, durationSeconds |
Contactos
| Método | Ruta | Qué hace |
|---|---|---|
| GET | /contacts | Contactos conocidos por la sesión |
| GET | /contacts/{phone}/exists | ¿Tiene WhatsApp? Usalo antes de cualquier campana |
| POST | /contacts/check | Hasta 100 números de una vez |
| GET | /contacts/{phone}/picture | Foto de perfil |
| POST | /contacts/block | Bloquear o desbloquear |
Grupos
| Método | Ruta | Qué hace |
|---|---|---|
| GET | /groups | Grupos donde participa el número |
| POST | /groups | Crear grupo: subject, participants[] |
| POST | /groups/{id}/participants | action: add, remove, promote, demote |
| PATCH | /groups/{id}/subject | Cambiar el nombre |
| GET | /groups/{id}/invite-code | Enlace de invitación |
| POST | /groups/join | Unirse con un código o enlace |
Webhooks
Cada sesión apunta a una URL tuya. Hacemos POST con:
{
"event": "messages.received",
"sessionId": "3f9c1a2e-...",
"sessionName": "ventas",
"timestamp": "2026-07-30T10:00:00.000Z",
"data": {
"id": "3EB0C1...",
"from": "[email protected]",
"fromPhone": "51977700001",
"pushName": "Juan Perez",
"type": "text",
"body": "Hola, quiero informacion",
"mediaUrl": null
}
}
Eventos
| Evento | Cuando llega |
|---|---|
messages.received | Mensaje entrante |
messages.created | Mensaje escrito desde el propio teléfono (no los enviados por la API) |
messages.ack | Cambio a enviado / entregado / leido |
messages.sent | Un mensaje de la cola salio |
messages.reaction | Alguien reacciono |
messages.deleted | Mensaje eliminado para todos |
session.status | La sesión cambió de estado |
session.qr | Hay un QR nuevo |
groups.participants | Alguien entro o salio de un grupo |
call.received | Llamada entrante |
Verificar la firma
Cada envío lleva X-Webhook-Signature: sha256=<hex>, que es el HMAC-SHA256 del cuerpo crudo con tu webhookSecret. Comprobarlo evita que alguien te inyecte mensajes falsos.
const crypto = require('crypto');
app.post('/webhooks/whatsapp', express.raw({type:'application/json'}), (req, res) => {
const esperada = 'sha256=' + crypto
.createHmac('sha256', process.env.WEBHOOK_SECRET)
.update(req.body) // el cuerpo CRUDO, antes de JSON.parse
.digest('hex');
if (req.get('X-Webhook-Signature') !== esperada) return res.sendStatus(401);
res.sendStatus(200); // responde rapido...
procesar(JSON.parse(req.body)); // ...y procesa despues
});
2xx en 10 segundos, reintentamos con espera creciente
(10 s, 30 s, 90 s, 4.5 min, 13 min) hasta 6 veces. Responde rápido y procesa en segundo plano.