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}
Compatible con UltraMsg. Usa las mismas rutas, parámetros, respuestas y webhooks. Si tu sistema ya funciona con UltraMsg, solo cambia el dominio api.ultramsg.com por api.tudominio.com y pon el ID y el token de tu instancia.

Reglas generales

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

CampoDescripción
toDestino. Varios separados por coma (hasta 500); cada uno genera su propio mensaje y la respuesta trae también ids.
priorityOrden en la cola: menor sale antes. Por defecto 10. Para codigos OTP usa 1.
referenceIdTu propio identificador (hasta 255). Vuelve en GET /messages y en los webhooks.
msgIdPara responder citando un mensaje: el id que llego en el webhook.
mentionsTelefonos a mencionar, separados por coma (en grupos).

Rutas de envío

RutaCampos propios
POST /messages/chatbody (texto, hasta 65536)
POST /messages/imageimage (URL, base64 o archivo), caption
POST /messages/documentdocument, filename (obligatorio), caption
POST /messages/audioaudio
POST /messages/voiceaudio — llega como nota de voz
POST /messages/videovideo, caption
POST /messages/stickersticker (jpg, png, gif o webp; se convierte solo)
POST /messages/contactcontact: chatID(s) del contacto, separados por coma
POST /messages/vcardvcard: texto vCard completo (puedes armarlo en el panel)
POST /messages/locationaddress (1a linea = nombre del lugar), lat, lng
POST /messages/reactionmsgId, emoji (vacío = quitar la reacción)
POST /messages/deletemsgId — 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

EstadoQué significa
queueEn cola, esperando su turno o a que la instancia este conectada
sentEnviado a WhatsApp
unsentFalló al enviar después de los reintentos
invalidEl número no tiene WhatsApp (se verifica antes de enviar)
expiredPasó 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).

RutaQué hace
GET /messagesListado 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/statisticsCuantos hay en cada estado
POST /messages/resendByStatusstatus = unsent o expired: los vuelve a poner en cola
POST /messages/resendByIdid: reencola uno que no salio
POST /messages/clearstatus: 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

RutaQué hace
GET /instance/statusaccountStatus.status: authenticated, qr, loading, initialize o disconnected
GET /instance/qrImagen PNG del QR para vincular
GET /instance/qrCodeEl QR como texto ({"qrCode": "..."})
GET /instance/meDatos del número conectado: id, nombre, foto, si es empresa
GET /instance/settingsAjustes actuales
POST /instance/settingsCambia los ajustes (solo los campos que mandes, ver abajo)
POST /instance/restartReinicia la conexión con WhatsApp
POST /instance/logoutCierra la sesión de WhatsApp (hay que volver a escanear)
POST /instance/clearReset: cierra la sesión, borra todo el registro de mensajes y deja los ajustes de fábrica. El token no cambia
AjusteDescripción
sendDelaySegundos entre envíos cuando la cola tiene menos de 10 (por defecto 1)
sendDelayMaxSegundos entre envíos cuando la cola tiene 10 o más (por defecto 15)
webhook_urlAdonde se envían los webhooks; vacío = ninguno
webhook_retriesReintentos si tu sistema no responde 200 (0 a 10, por defecto 3)
webhook_message_receivedtrue/false: avisar mensajes recibidos
webhook_message_createAvisar mensajes enviados, incluidos los escritos desde el teléfono
webhook_message_ackAvisar cambios de ACK
webhook_message_download_mediaIncluir en el webhook la URL del archivo recibido
webhook_message_reactionAvisar reacciones

Chats, contactos, grupos y archivos

RutaQué hace
GET /chats · /chats/idsConversaciones del número
GET /chats/messageschatId, limit (por defecto 50): últimos mensajes de un chat
POST /chats/archive · unarchive · read · clearMessages · deletechatId
GET /contacts · /contacts/idsContactos conocidos
GET /contacts/contactchatId: datos de un contacto
GET /contacts/checkchatId, nocache: {"status":"valid"} si el número tiene WhatsApp, invalid si no
GET /contacts/imagechatId: URL de la foto de perfil
GET /contacts/blocked · /contacts/invalidBloqueados · números a los que se intentó enviar sin WhatsApp
POST /contacts/block · /contacts/unblockchatId
GET /groups · /groups/idsGrupos en los que está el número
GET /groups/groupgroupId: datos y participantes
POST /media/uploadfile (multipart, URL o base64, hasta 30 MB): devuelve una URL para usar en los envíos
POST /media/deleteurl de un archivo subido
POST /media/deleteByDatedate = 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_typeCuando
message_receivedLlega un mensaje de otra persona
message_createSe envía un mensaje desde la instancia o desde el teléfono (fromMe: true)
message_ackCambia el ack de un mensaje enviado; id y referenceId de la raíz son los de tu envío
message_reactionAlguien reacciona; data.reaction trae emoji y msgId

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>.

Cuídala. Con tu API key se puede enviar mensajes desde tus números. Guárdala en el servidor, nunca en el navegador ni en una app móvil. Si se filtra, pídenos una nueva y revocamos la anterior.

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
  }
}
HTTPcodeQué significa
401unauthorizedAPI key ausente, inválida o revocada
404not_foundEl recurso no existe o no es de tu cuenta
409session_not_startedLa sesión no está iniciada; llama a /connect
409session_not_connectedLa sesión existe pero el número no está vinculado
422validation_errorCuerpo inválido; details dice qué campo
429rate_limitedSuperaste el limite de peticiones
502whatsapp_errorWhatsApp 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..."
}
Guarda el 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étodoRutaQué hace
GET/v1/sessionsLista tus sesiones
GET/v1/sessions/{id}Detalle y estado
PATCH/v1/sessions/{id}Cambia nombre, webhook o eventos
POST/v1/sessions/{id}/connectInicia la conexión
POST/v1/sessions/{id}/disconnectCierra el socket, conserva la vinculación
POST/v1/sessions/{id}/logoutDesvincula el número (habrá QR nuevo)
POST/v1/sessions/{id}/restartReinicia 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

CampoTipoPara que sirve
totextoNúmero en formato internacional sin + (51977700001) o el id de un grupo
waitbooltrue espera hasta 15 s la confirmación y devuelve el waMessageId real
delaySecondsenteroPrograma el envío para más tarde
quotedMessageIdtextoResponde citando ese mensaje

Tipos de mensaje

Todas cuelgan de /v1/sessions/{id}/messages/. En las de archivo se manda url o base64.

RutaCampos propios
/texttext, mentions[], linkPreview
/imageurl|base64, caption
/videourl|base64, caption, gifPlayback
/audiourl|base64, ptt (nota de voz)
/documenturl|base64, filename, caption
/stickerurl|base64 — debe ser .webp
/locationlatitude, longitude, name, address
/contactcontacts[] con fullName, phone
/reactionmessageId, emoji (vacío = quitar)
/pollname, options[], selectableCount

Historial y media

MétodoRutaQué hace
GET/v1/sessions/{id}/messagesHistorial. 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
Los archivos recibidos se conservan 7 días. Si necesitas guardarlos, bájalos cuando llegue el webhook.

Chats

MétodoRutaCuerpo
POST/chats/typingto, state, durationSeconds
POST/chats/readto, messageIds[]
DELETE/chats/messages/{msgId}Elimina para todos
POST/chats/archiveto, archive
POST/chats/muteto, durationSeconds

Contactos

MétodoRutaQué hace
GET/contactsContactos conocidos por la sesión
GET/contacts/{phone}/exists¿Tiene WhatsApp? Usalo antes de cualquier campana
POST/contacts/checkHasta 100 números de una vez
GET/contacts/{phone}/pictureFoto de perfil
POST/contacts/blockBloquear o desbloquear

Grupos

MétodoRutaQué hace
GET/groupsGrupos donde participa el número
POST/groupsCrear grupo: subject, participants[]
POST/groups/{id}/participantsaction: add, remove, promote, demote
PATCH/groups/{id}/subjectCambiar el nombre
GET/groups/{id}/invite-codeEnlace de invitación
POST/groups/joinUnirse 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

EventoCuando llega
messages.receivedMensaje entrante
messages.createdMensaje escrito desde el propio teléfono (no los enviados por la API)
messages.ackCambio a enviado / entregado / leido
messages.sentUn mensaje de la cola salio
messages.reactionAlguien reacciono
messages.deletedMensaje eliminado para todos
session.statusLa sesión cambió de estado
session.qrHay un QR nuevo
groups.participantsAlguien entro o salio de un grupo
call.receivedLlamada 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
});
Si tu endpoint no responde 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.

← Volver al inicio