Aprende a usar la API de WS Gateway

Con la API, tus propios programas (un sistema en Visual FoxPro, una página web, Excel, un script) pueden hacer lo mismo que haces con clics en el panel: consultar chats, enviar mensajes de WhatsApp y enterarse de lo que llega. Elige por dónde quieres empezar:

Es mi primera vez con una API Te explico cada palabra y lo hacemos juntos, paso a paso, con botones que funcionan de verdad. Ya he usado APIs Dirección base, autenticación, formato de respuesta, endpoints más usados y ejemplos para copiar. Busco un endpoint concreto Todos los endpoints con sus campos, y la opción de probarlos aquí mismo.

Antes de empezar: ¿qué es una API?

Dos minutos de lectura y no se te vuelve a mezclar nada

Una API es una forma de pedirle cosas a WS Gateway desde otro programa, sin abrir el panel. Piensa en un restaurante: tú (tu programa) le haces un pedido al mesero (la API), y él te trae lo que salió de la cocina (WS Gateway). Ese pedido se llama petición y lo que te traen, respuesta.

Las 4 piezas de una petición

1Dirección (URL)

A dónde vas. Por ejemplo /api/accounts (la lista de tus instancias).

2Método

Qué quieres hacer: GET leer, POST crear o enviar, PATCH cambiar, DELETE borrar.

3Encabezados

Datos de contexto. Los dos que verás siempre: quién eres (Authorization) y en qué formato hablas (Content-Type: application/json).

4Cuerpo

Los datos que mandas (a quién y qué mensaje), escritos en JSON. Solo se usa con POST y PATCH.

La respuesta también trae dos cosas: un código de tres cifras (200 significa «todo bien»; los que empiezan con 4 son «hiciste algo mal»; con 5, «falló el servidor») y un JSON con lo que pediste o con el motivo del error.

No necesitas instalar nada para seguir esta guía: cada paso tiene un botón que hace la petición por ti y, debajo, el mismo código listo para copiar en tu lenguaje (curl, JavaScript, Python, PHP o Visual FoxPro).

Tu llave de acceso

Cómo le demuestras a WS Gateway quién eres

Cada petición debe llevar una llave que dice quién eres. Se llama token de sesión (técnicamente, un JWT) y la consigues iniciando sesión: le mandas tu correo y tu contraseña a POST /api/auth/login y te devuelve el token. Dura 7 días; cuando venza (recibirás un 401) vuelves a iniciar sesión.

Lo que pasa ahora mismo

Ya iniciaste sesión en el panel, por eso esta página ya tiene tu llave y puede hacer peticiones en tu nombre.

Trátalo como una contraseña: quien lo tenga puede actuar como tú. No lo pegues en chats ni lo publiques.

Así se pide en tu programa (con tu correo y contraseña reales):

Elige tu instancia

La línea de WhatsApp con la que vas a trabajar

Una instancia es una línea de WhatsApp vinculada a WS Gateway. Casi todas las peticiones dicen con cuál trabajar, poniendo su token de instancia en la dirección: /api/accounts/TOKEN/send.

Ojo, son dos «tokens» distintos. El token de sesión (paso 1) eres tú y vence a los 7 días. El token de instancia (este paso) es la identidad de la línea de WhatsApp y no vence nunca. Se usan juntos: el primero va en el encabezado, el segundo en la dirección.

Tus instancias

La petición que acabas de ver hacer, para tu programa:

Lee información

Tu primera petición GET: solo mira, no cambia nada

Las peticiones GET son las más seguras: solo leen. Prueba con la lista de chats de tu instancia. Verás la respuesta tal como la recibiría tu programa: primero el código y después el JSON.

Primero elige una instancia en el paso 2.

¿Cómo leo un JSON? Son pares "nombre": valor entre llaves { }; las listas van entre corchetes [ ]. Aquí success: true dice que salió bien y chats es la lista. Cada chat trae su id: lo usarás para pedir sus mensajes.

Envía tu primer mensaje

Una petición POST: esta sí hace algo de verdad

Con POST mandas datos en el cuerpo. Para enviar un mensaje necesitas dos: a quién (destino) y qué (mensaje). El código de abajo se actualiza mientras escribes.

Esto envía un WhatsApp real. Para probar, mándatelo a ti mismo o a alguien que sepa que lo recibirás. Nunca envíes en ráfagas: WhatsApp puede restringir un número que manda muchos mensajes seguidos.

Número de destinoCon código de país, sin «+», espacios ni guiones. Ecuador: 593 y el número sin el 0 inicial (0991234567 pasa a 593991234567). Mensaje

Primero elige una instancia en el paso 2.

¿Y si quiero mandar un archivo (PDF, imagen)?

El archivo viaja dentro del JSON, convertido a texto con un formato llamado base64. Es el mismo endpoint, con un campo más (archivo):

Cuando algo sale mal

Los errores son normales: aprende a leerlos

Un error no es un fallo tuyo ni de la API: es la respuesta diciéndote qué corregir. Siempre trae el mismo formato, con un message en español que puedes mostrarle a tu usuario final y un raw_message técnico para tus registros.

¿Por qué a veces message y raw_message dicen lo mismo?

401 El error lo detecta WS Gateway

Falta un dato, no existe el chat, no llevas el token… El mensaje ya nace en español y no hay otra versión técnica, así que los dos campos traen el mismo texto. Es lo más común.

"provider_code": null,
"message":     "Falta la autenticación (encabezado Authorization).",
"raw_message": "Falta la autenticación (encabezado Authorization)."

403 El error viene de WhatsApp

Cuando WhatsApp rechaza un envío, message trae una frase clara para tu usuario y raw_message lo que respondió WhatsApp, con su código en provider_code. Aquí sí son distintos.

"provider_code": "463",
"message":     "Tu cuenta de WhatsApp ha sido restringida temporalmente.",
"raw_message": "WhatsApp rechazó el envío (código 463): …"

La regla es una sola: muestra message a tu usuario y guarda raw_message y provider_code en tus registros. Que a veces coincidan es normal.

Código	Qué significa	Qué hacer
200	Todo salió bien.	Lee los datos de la respuesta.
400	La petición tiene datos incorrectos o le faltan campos.	Lee `message`: dice qué campo corregir.
401	No llevas token de sesión, ya venció, o (en el inicio de sesión) el correo o la contraseña no coinciden.	Vuelve a iniciar sesión (paso 1); si ya estabas en el login, revisa los datos.
403	No tienes permiso, tu cuenta aún no confirmó su WhatsApp, o el plan de la instancia no incluye esa función.	Revisa el plan; `message` lo dice.
404	No existe lo que pediste: un chat, una instancia, un número sin WhatsApp…	Revisa el identificador que mandaste.
429	Demasiados intentos seguidos.	Espera unos minutos y reintenta más despacio.
500	Algo falló dentro del servidor.	No es tu petición: avisa al administrador.

Provoca un error a propósito (es inofensivo)

Así ves cómo llega uno de verdad:

Entérate de lo nuevo sin preguntar

Webhooks: que WS Gateway te avise

Hasta aquí tú preguntas (¿hay algo nuevo?). Repetir esa pregunta cada pocos segundos es lento e ineficiente. Con un webhook pasa al revés: le das a WS Gateway una dirección tuya y él te avisa cuando llega un mensaje o cambia la conexión de la instancia.

Prepara una dirección pública en tu servidor que reciba POST (una dirección local como localhost se rechaza por seguridad).
Regístrala con PATCH /api/accounts/{token}/webhook. La respuesta trae un secreto: guárdalo. Puedes volver a consultarlo con GET /api/accounts/{token}/webhook, pero cada vez que guardas la dirección con PATCH se genera uno nuevo y el anterior deja de servir.
Cada aviso llega firmado en la cabecera X-WSGateway-Signature: compruébala con el secreto antes de confiar en él (ejemplo en la Guía rápida).

Disponible en instancias con plan Dedicado. Eventos: mensaje.nuevo, instancia.conectado e instancia.desconectado.

¡Ya sabes lo básico!

Qué sigue, según lo que necesites

Guía rápida — los endpoints más usados, límites y buenas prácticas.
Referencia completa — cada endpoint con todos sus campos, para probarlo aquí mismo.
Glosario — qué significa cada palabra técnica, en llano.

Guía rápida

Lo esencial para integrar WS Gateway en tu sistema. Si algo aquí te suena raro, la pestaña Empezar desde cero lo explica paso a paso.

Lo esencial

Dirección base
Formato	JSON en ambos sentidos (`Content-Type: application/json`), codificación UTF-8.
Autenticación	`Authorization: Bearer <JWT>` en todas las rutas salvo `/auth/register` y `/auth/login`. El JWT dura 7 días y no hay refresh: ante un `401`, vuelve a hacer login.
Instancia	El `{token}` de la ruta es el identificador de la instancia (no vence y no es el JWT). Sale de `GET /api/accounts`.
Éxito	`{ "success": true, "timestamp": "…", …datos }`
Error	`{ "success": false, "error_code": 404, "provider_code": null, "message": "…en español, para mostrar…", "raw_message": "…técnico…", "timestamp": "…" }`. `provider_code` trae el código de WhatsApp cuando el error viene de allí (p. ej. cuenta restringida).
Planes	El plan de la instancia (Básico, Estándar, Avanzado, Forense, Dedicado) decide qué funciones tiene. Si no alcanza, responde `403` con un `message` que lo explica. Enviar y recibir funciona en todos.

Los endpoints que más se usan

Método	Ruta	Para qué
POST	`/api/auth/login`	Iniciar sesión y obtener el JWT.
GET	`/api/accounts`	Listar tus instancias, su estado y su token.
GET	`/api/accounts/{token}/qr`	QR pendiente para vincular (o `POST …/pairing-code` para vincular con código).
POST	`/api/accounts/{token}/send`	Enviar texto, archivo o nota de voz (encuesta, ubicación y contacto: plan Dedicado).
GET	`/api/accounts/{token}/mensajes/no-leidos`	Todos los mensajes entrantes sin leer, de cualquier chat. Ideal para sistemas y bots.
POST	`/api/accounts/{token}/mensajes/marcar-leidos`	Marcar mensajes como leídos (también se lo avisa a WhatsApp).
GET	`/api/accounts/{token}/chats`	Listar chats (desde el plan Estándar).
GET	`/api/accounts/{token}/chats/{chatId}/mensajes`	Mensajes de un chat, con paginación.
PATCH	`/api/accounts/{token}/webhook`	Recibir avisos en vivo (plan Dedicado).
GET	`/api/openapi.json`	Esta documentación en formato OpenAPI.

Todos los demás están en la Referencia completa.

Ejemplos listos para copiar

Elige tu lenguaje una vez y cambia en todos. Si eliges una instancia en el paso 2 de Empezar desde cero, los ejemplos usan su token.

Rellenar los ejemplos con mi token de sesión real (no lo compartas)

Enviar un texto

Enviar un archivo

Leer lo que llegó sin leer

Marcar mensajes como leídos

Recibir avisos en vivo (webhook)

Registra tu dirección con PATCH /api/accounts/{token}/webhook y el cuerpo { "webhookUrl": "https://tu-servidor.com/hook" } (con null se desactiva). La respuesta trae webhookSecret; puedes volver a consultarlo con un GET a la misma dirección, pero cada PATCH con una dirección genera uno nuevo y el anterior deja de servir. Cada aviso es un POST con este cuerpo y estas cabeceras:

X-WSGateway-Signature: sha256=<firma>
X-WSGateway-Instance: wsg_xxxxxxxxxxxxx

{
  "evento": "mensaje.nuevo",
  "instancia": "wsg_xxxxxxxxxxxxx",
  "datos": {
    "chat": { "numero": "+593999999999", "nombreContacto": "…" },
    "mensaje": { "contenido": "Hola", "direccion": "entrante", … }
  },
  "timestamp": "2026-09-14T20:00:00.000Z"
}

La firma es un HMAC-SHA256 del cuerpo exacto (byte por byte) con tu secreto. Compruébala antes de confiar en el aviso:

Responde con un 2xx rápido. Si tu servidor no responde, se reintenta una vez a los 3 segundos.
La dirección debe ser pública: las direcciones locales o privadas se rechazan por seguridad.
Eventos actuales: mensaje.nuevo, instancia.conectado, instancia.desconectado.

Límites, tiempos y buenas prácticas

Envío: POST …/send espera hasta 8 segundos la confirmación real de WhatsApp. Si tarda más, responde igual y el estado final del mensaje lo ves después en su campo estado.
Nunca en ráfagas: WhatsApp restringe números que envían muchos mensajes seguidos o iguales a muchos destinos. Espacia los envíos y personaliza el texto.
Inicio de sesión: tras 8 intentos fallidos en 15 minutos, responde 429 hasta que pase la ventana.
Reconectar, renombrar o desvincular una instancia: hay 30 segundos de espera entre una acción y otra sobre la misma cuenta.
Códigos por WhatsApp (verificar cuenta, recuperar contraseña): se puede pedir uno por minuto.
Identificadores: chatId y mensajeId son números que tú guardas; el jid es cómo WhatsApp identifica a una persona (número@s.whatsapp.net).
Errores: muestra message a tu usuario y guarda raw_message en tus registros.

Herramientas

Impórtala en Postman, Insomnia o un generador de código: crea todas las peticiones sola. Trae solo lo que tu cuenta puede usar.

Referencia completa

Cada endpoint con sus campos. Pulsa uno para abrirlo, luego Probar y Ejecutar: la petición se hace de verdad con tu sesión.

Instancia para las pruebas

Cómo leer esta página

GET lee · POST crea o envía · PATCH / PUT cambia · DELETE borra.
Los valores de ejemplo (wsg_AbCd…, 42) son de relleno. Si eliges una instancia arriba, las operaciones de lectura (GET) se rellenan solas con tu token real y tu primer chat. Las que modifican o borran datos nunca se rellenan solas: pega tú el valor a propósito.
El candado indica que la ruta pide sesión; la tuya ya está cargada.
Cada respuesta muestra el código, el JSON y el curl equivalente para copiar.

Glosario

Las palabras técnicas de esta ayuda, en cristiano. Escribe para filtrar.

API: Forma en que un programa le pide cosas a otro. La API de WS Gateway permite enviar mensajes, leer chats o consultar instancias sin usar el panel.
Petición y respuesta: La petición es lo que tu programa envía (dirección, método, encabezados y a veces datos). La respuesta es lo que WS Gateway devuelve: un código y un JSON.
Endpoint: Cada dirección concreta de la API que hace una cosa, por ejemplo POST /api/accounts/{token}/send envía un mensaje.
URL / dirección: El «domicilio» al que va la petición: https://servidor/api/accounts. Lo que va entre llaves, como {token}, lo sustituyes por tu dato.
Método HTTP: El verbo: GET leer, POST crear o enviar, PATCH o PUT modificar, DELETE borrar.
Encabezado (header): Dato de contexto que viaja con la petición, como Authorization (quién eres) o Content-Type (formato de los datos).
Cuerpo (body): Los datos que mandas en un POST o PATCH, normalmente en JSON: { "destino": "593…", "mensaje": "Hola" }.
JSON: Formato de texto para intercambiar datos: pares "nombre": valor entre llaves, y listas entre corchetes. Lo entienden todos los lenguajes.
Código de estado: Número de tres cifras de la respuesta: 200 bien, 4xx error tuyo (datos, permisos, no existe), 5xx error del servidor.
Token de sesión (JWT): La llave que consigues al iniciar sesión y que va en el encabezado Authorization: Bearer …. Dura 7 días. Es personal: trátala como una contraseña.
Token de instancia: Identificador permanente de una línea de WhatsApp de WS Gateway (empieza con wsg_). Va en la dirección. No es el token de sesión y no vence.
Instancia: Una línea de WhatsApp vinculada a WS Gateway. Un cliente puede tener varias y cada una tiene su estado (conectada, esperando vinculación…) y su plan.
Plan: Nivel de servicio de una instancia (Básico, Estándar, Avanzado, Forense, Dedicado). Decide qué funciones se pueden usar; enviar y recibir va en todos.
jid: Identificador de una persona o grupo en WhatsApp, por ejemplo 593999999999@s.whatsapp.net: el número con código de país más un sufijo. Tú casi siempre usas el número; el jid lo devuelve la API.
Base64: Manera de convertir un archivo en texto para viajar dentro de un JSON. Así se adjunta un PDF o una imagen al enviar un mensaje.
Webhook: Aviso automático: en vez de que tú preguntes si hay algo nuevo, WS Gateway hace una petición a una dirección tuya cuando ocurre algo (llega un mensaje, cambia la conexión).
Firma (HMAC): Código con el que compruebas que un webhook viene de verdad de WS Gateway y no de un tercero. Se calcula con tu secreto sobre el cuerpo exacto del aviso.
OpenAPI / Swagger: Estándar para describir una API. La pestaña «Referencia completa» está hecha con él, y puedes descargar el archivo para importarlo en Postman u otras herramientas.
curl: Programa de línea de comandos para hacer peticiones. Los ejemplos «curl» de esta ayuda se pegan en una terminal; en Windows usa curl.exe y escribe todo en una sola línea (cada ejemplo lo recuerda).