API externa

Envía eventos de tus sistemas a la bandeja

Una petición HTTP deja un mensaje de texto en su propio hilo, junto a los chats de WhatsApp. No se envía por WhatsApp y no se mezcla con la conversación de un cliente.

Empezar prueba gratisVer precios

Después de iniciar sesión, crea un token en Ajustes. El secreto se muestra una sola vez.

Qué hace la API

Entrada, no salida

Envía un mensaje de texto a una sesión de WhatsApp que ya conectaste. Chato lo guarda y lo muestra en vivo en el panel. No envía un mensaje de WhatsApp y no hay un canal de respuesta hacia tu sistema.

Un hilo por origen

El sourceId shopify cae siempre en el mismo chat, ext:shopify@external. Un segundo origen, como website, es otro hilo en esa misma sesión.

Fuera de los chats de clientes

El hilo se etiqueta como externo y el compositor es de solo lectura. Avisos de pedidos y formularios quedan al lado de la bandeja, no dentro del historial de un cliente.

Dónde lo usan los equipos

Cualquier cosa que deba estar junto a WhatsApp, sin convertirse en un mensaje de WhatsApp.

Pedidos y pagos

Pedido nuevo, pagado, reembolsado. La sesión de esa tienda muestra un hilo de Shopify en lugar de un chat de cliente falso.

Formularios web

Un formulario de contacto o de reserva publica el envío. El equipo lo lee en el mismo panel que WhatsApp.

CRM y soporte

Cambios de oportunidad, escalados de tickets o notas de asignación. Dale a cada herramienta su propio source id para que los hilos no se mezclen.

Herramientas internas

Inventario, monitorización o un script de operaciones. Un token de la cuenta puede publicar en cualquier sesión de esa cuenta.

Cómo enviar el primer mensaje

  1. 01

    Crea un token

    Abre Ajustes y luego API externa. Ponle el nombre de la integración, por ejemplo Shopify. Copia el secreto al momento. Chato guarda solo un hash y el token completo no vuelve a mostrarse. Revócalo ahí cuando rotes o pares una integración.

  2. 02

    Copia el id de sesión

    En el panel, abre el menú del número de WhatsApp que debe recibir el hilo y elige Copiar ID de sesión. Esa sesión tiene que pertenecer a la misma cuenta que el token.

  3. 03

    Envía el mensaje

    Manda JSON a POST /api/external/messages con Authorization: Bearer y tu token. sourceId elige el hilo. externalMessageId permite reintentar sin crear un duplicado.

  4. 04

    Abre el hilo

    El origen aparece en la lista de chats de esa sesión con el nombre del origen. Enviar otra vez el mismo externalMessageId devuelve el mensaje original y no añade una segunda burbuja.

Endpoints

Las llamadas de mensajes usan el token de API. Crear, listar y revocar tokens usa tu sesión iniciada en Chato, igual que Ajustes.

MétodoRutaAuthQué hace
POST/api/external/messagesToken de APIGuarda un mensaje de texto en una sesión. 201 si es nuevo, 200 si ese externalMessageId ya existía.
GET/api/external/meToken de APIComprueba que el token es válido. Devuelve authenticated y el id de la cuenta. No lista sesiones.
GET/api/external/tokensSesión iniciadaLista los tokens activos: nombre, prefijo, fecha de creación y último uso. No incluye secretos.
POST/api/external/tokensSesión iniciadaCrea un token. El cuerpo es { "name": "Shopify" }. El secreto viene en la respuesta una sola vez.
DELETE/api/external/tokens?id=TOKEN_IDSesión iniciadaRevoca un token. Las llamadas posteriores con ese secreto devuelven 401.

URL base: https://chato.pro. Si no entras en chato.pro, usa el host con el que inicias sesión.

Campos del mensaje

Cuerpo JSON de POST /api/external/messages.

CampoObligatorioQué hace
sessionIdObligatorioLa sesión de WhatsApp que debe mostrar el hilo. Cópiala desde el panel. 404 si no está en esta cuenta.
sourceIdObligatorioClave del hilo. De 2 a 64 caracteres: letras, números, guiones y guiones bajos. Los espacios pasan a guiones y el valor se pone en minúsculas. El id del chat es ext:<sourceId>@external.
messageObligatorioEl texto que se muestra en el hilo. No puede estar vacío y tiene como máximo 4096 caracteres.
sourceNameOpcionalNombre visible, por ejemplo Pedidos de Shopify. Si se omite, el source id se muestra en mayúsculas de título.
externalMessageIdOpcionalTu id para este evento. Enviarlo otra vez para la misma sesión y origen devuelve el mensaje original y no emite otra actualización en vivo.
metadataOpcionalObjeto JSON extra guardado con el mensaje. No se muestra como texto del chat.

Ejemplo de petición

Sustituye YOUR_TOKEN y el id de sesión. Un mensaje nuevo responde con created: true y el chat ext:shopify@external.

Ejemplo de respuesta

created es false, con HTTP 200, cuando externalMessageId ya estaba guardado.

curl -X POST https://chato.pro/api/external/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "your-session-id",
    "sourceId": "shopify",
    "sourceName": "Shopify Orders",
    "message": "New order #1234",
    "externalMessageId": "order-1234"
  }'
{
  "success": true,
  "created": true,
  "messageId": "ext_shopify_order-1234",
  "chatId": "ext:shopify@external",
  "sourceId": "shopify",
  "timestamp": 1710000000
}

Autenticación

Envía el token en cada llamada de mensaje. Prefiere la cabecera Authorization para que el secreto no quede en una URL o en el registro de un proxy.

  • Authorization: Bearer <token>
  • X-Api-Key: <token>
  • ?key=<token>

Un token es una credencial de la cuenta. Cualquier token activo puede publicar en cualquier sesión de esa cuenta. Revocarlo en Ajustes lo detiene al momento. Cada llamada correcta actualiza el último uso. El secreto tiene la forma chato_ seguido de 48 caracteres hexadecimales. Ajustes después muestra solo el inicio del token.

Después de una llamada correcta

  • El mensaje se guarda con origen external. WhatsApp no se contacta.
  • Un panel abierto de esa sesión recibe el mensaje nuevo en vivo.
  • El id del hilo es ext:<sourceId>@external.
  • Repetir externalMessageId devuelve HTTP 200 y created: false.
  • El no leído es local de Chato. Abrir el hilo no envía un acuse de lectura de WhatsApp.
  • Borrar un mensaje externo lo quita solo de Chato.

Qué no hace

  • No envía mensajes, archivos ni plantillas de WhatsApp.
  • No puedes responder desde el hilo hacia el sistema externo.
  • No es la API en la nube de Meta ni la API oficial de WhatsApp Business.
  • Solo acepta texto. Este endpoint no sube archivos.
  • Un token no puede escribir en sesiones de otra cuenta.
  • Chato no llama a tu servidor cuando alguien lee el hilo.

Respuestas

  • 201 — Mensaje guardado.
  • 200 — Ese externalMessageId ya existía. Se devuelve el mensaje existente.
  • 400 — Falta sessionId, sourceId no es válido, o el mensaje está vacío o es demasiado largo.
  • 401 — Token ausente, desconocido o revocado.
  • 404 — sessionId no pertenece a esta cuenta.
  • 405 — Método HTTP incorrecto.

Genera un token, apunta un sistema a una sesión y deja esos eventos en su propio hilo.

Empezar prueba gratis