API de Whaticket: guía completa para integrar tus sistemas

La API de Whaticket conecta tu cuenta con otros sistemas, como CRM, e-commerce, ERP, planillas y plataformas de automatización como n8n, Make y Zapier. Con ella envías mensajes, gestionas chats y contactos, mueves chats en el Kanban, consultas informes y mantienes la base de conocimiento de Wäbot sin abrir la plataforma.

Este artículo reúne en un solo lugar cómo funciona la API, qué hace y qué no hace, cuánto cuesta, cómo crear el token, cómo probar cada ruta en la documentación y cómo usar la IA para armar tus integraciones más rápido.

Qué cambia en tu operación

Tu CRM, e-commerce o ERP envía mensajes y crea contactos en Whaticket sin que nadie copie y pegue datos.
Los chats llegan al agente, al departamento y a la etapa del Kanban correctos desde el primer mensaje.
Lees chats, informes y la base de conocimiento de Wäbot en tus propios paneles y herramientas.
Con la ayuda de la IA, armas y pruebas una integración en minutos, aunque no programes todos los días.

Cómo funciona la API

Servidor base: https://api.whaticket.com/api/v1. Cada ruta va al final de la dirección, por ejemplo https://api.whaticket.com/api/v1/messages.
Autenticación: cada solicitud lleva el encabezado Authorization con el valor Bearer, un espacio y la clave del token.
Permisos: el token usa los permisos de un perfil, que se verifican en cada solicitud. Si editas el perfil, el token cambia al instante, sin generar otro. Cada ruta de la documentación indica los permisos que exige.
Límite: hasta 600 solicitudes por minuto por empresa, sumando todas las rutas, tokens y apps conectadas. Si pasas el límite, espera unos segundos y vuelve a intentarlo.
Formato: los datos se envían y se reciben en JSON.

Para conectar un agente de IA, como Claude o ChatGPT, no necesitas token: usa el servidor MCP de la pestaña Apps conectadas. El paso a paso está en MCP: Integra Claude, ChatGPT y otras IAs en Whaticket.

Qué puedes hacer con la API

Mensajes y campañas

Enviar texto, archivos y plantillas a uno o varios contactos, hasta 999 por solicitud (POST /messages).
Subir imágenes, videos, audios y documentos para usar en los envíos (POST /medias).
En el mismo envío, crear o actualizar el contacto, asignar el chat a un agente, departamento o etapa del Kanban y dejar a Wäbot respondiendo.

Chats

Listar chats y leer el historial de mensajes (GET /tickets y GET /tickets/{ticketId}/messages).
Responder un chat existente con texto, archivo, nota interna o plantilla, y programar la respuesta para más tarde (POST /tickets/{ticketId}/messages).
Resolver, posponer, transferir, aceptar un chat en espera y cambiar el departamento.
Poner el chat en una etapa del Kanban y listar los tableros (POST /tickets/{ticketId}/set-kanban-column y GET /kanbans).
Listar y cancelar mensajes programados.

Contactos

Listar, crear y crear o actualizar contactos con correo, campos personalizados y etiquetas (POST /contacts/create-or-update).

Configuración de la cuenta

Listar las conexiones de todos los canales, editar nombre, saludo, despedida y departamentos del menú, y reiniciar una conexión WhatsApp QR Code desconectada.
Crear, editar y eliminar departamentos, con agentes y conexiones, y leer o reemplazar el menú del chatbot.
Listar usuarios y crear, editar y eliminar respuestas rápidas.

Wäbot e informes

Crear, editar y eliminar artículos de la base de conocimiento y tratar las lagunas de Wäbot.
Consultar el informe de conversaciones, con los mismos números de la pantalla Informes (hasta 90 días por consulta), y los períodos de ausencia de los agentes.

Consulta de la propia API

GET /me muestra el nombre, la empresa y los permisos del token. Úsala para confirmar que la clave funciona.
GET /openapi.json devuelve la definición completa de la API, sin token. Es la dirección que le pasas a la IA, como mostramos más abajo.

La lista completa de rutas, con los campos y los permisos de cada una, está en la pestaña Documentación, en Integraciones.

Qué ruta usar en cada caso

Hablar con alguien que todavía no escribió, o con muchos contactos: POST /messages. Crea una campaña y, en WhatsApp QR Code, consume créditos.
Responder un chat que ya existe: POST /tickets/{ticketId}/messages. No crea campaña y nunca consume créditos. Encuentra el ticketId con GET /tickets?searchParam= y el número del contacto.
Guardar un contacto sin enviar mensaje: POST /contacts/create-or-update. No consume créditos.
Pasar el chat a una persona: /transfer cuando el chat ya está con alguien; /assign cuando está en espera, como el botón Aceptar.
Organizar el embudo: POST /tickets/{ticketId}/set-kanban-column, o el campo kanbanColumnId en el envío.
Avisar a otro sistema cuando algo pasa en Whaticket: no es por la API. Usa la acción Enviar webhook en Flujos, como explicamos en Cómo integrar Whaticket con n8n, Make y Zapier.
Dejar que una IA opere Whaticket por ti: conecta el agente por MCP, sin token.

Qué no hace la API

No avisa a otros sistemas por sí sola: la API responde a lo que tu sistema le pide. Para que Whaticket envíe datos hacia afuera cuando llega un mensaje, un contacto recibe una etiqueta, un chat cambia de etapa o se resuelve, usa Flujos con la acción Enviar webhook, o Llamar webhook en una etapa del chatbot.
No responde fuera de la ventana de conversación: para responder un chat, el contacto tiene que haber escrito en los últimos 7 días. En la API oficial de WhatsApp, Facebook e Instagram rige además la ventana de 24 horas de Meta, salvo para plantillas. Fuera de esas ventanas, usa POST /messages.
No hace nada fuera de la documentación: lo que no aparece en la pestaña Documentación no está disponible por la API.
No incluye implementación por parte del soporte: el equipo de soporte resuelve dudas puntuales, pero no programa ni implementa la integración.

Cuánto cuesta usar la API

En conexiones WhatsApp QR Code, cada mensaje enviado por POST /messages consume un crédito de campaña.
En conexiones WhatsApp API Cloud y WhatsApp API Coexistencia, Meta cobra cada plantilla directamente en tu cuenta.
Responder un chat por POST /tickets/{ticketId}/messages no consume créditos. Las demás rutas, como crear contactos o consultar informes, tampoco.
Durante el período de prueba, los envíos por cualquier conexión consumen créditos.
Cuando se acaban los créditos, la campaña de la API queda suspendida y los mensajes restantes solo se envían después de que agregues créditos.

Para comprar créditos, consulta Cómo comprar créditos de campaña.

Antes de empezar

Usar la API requiere conocimientos técnicos, o la ayuda de un profesional de TI o de una IA, como mostramos en este artículo.
Para crear tokens, tu perfil necesita los permisos Ver y Crear en el grupo Tokens de API.
El perfil elegido para el token necesita los permisos de cada ruta. Para enviar mensajes: Crear e Iniciar en Campañas. Para leer y responder chats: Ver y Ver todos en Chats. Para el Kanban: Ver todos los Kanbans.
Solo puedes vincular al token un perfil con permisos que tú también tienes.

Consejo: crea un perfil exclusivo para cada integración, solo con lo que necesita. Te explicamos cómo en Cómo crear perfiles y permisos personalizados.

Paso a paso:

Crea el token

En el menú de la izquierda, haz clic en Integraciones y quédate en la pestaña Tokens.
Haz clic en Nuevo token.
Completa el Nombre y, en Perfil, elige el perfil cuyos permisos usará el token. La lista Permisos de este perfil muestra lo que habilita.
Haz clic en Guardar.
En la ventana Copia la clave del token, copia la Clave y haz clic en Listo.

Guarda la clave en un lugar seguro: no vuelve a aparecer después de cerrar la ventana. Si la pierdes, haz clic en Regenerar en el token. La clave anterior deja de funcionar de inmediato.

Autoriza la documentación con el token

En Integraciones, abre la pestaña Documentación.
Haz clic en el botón Authorize.
Pega la clave del token y haz clic en Authorize.
Cierra la ventana. Cuando el candado del botón aparece cerrado, la documentación está lista para probar.

Para confirmar que todo salió bien, abre la ruta GET /me, haz clic en Try it out y en Execute. La respuesta muestra el nombre del token, la empresa y los permisos del perfil.

Copia los IDs que vas a usar

Conexión (connectionId): en Conexiones, abre el menú de acciones de la conexión, haz clic en Editar y en el ícono de copiar junto al título.
Departamento (queueId): en Departamentos & Chatbots, edita el departamento y haz clic en Copiar identificación junto al título.
Usuario (userId): en Equipo, edita el usuario y haz clic en Copiar identificación junto al título.
Plantilla (templateId): en Plantillas y Flows, abre la plantilla y haz clic en el ícono de copiar junto al nombre. Es obligatorio para conexiones de la API oficial de WhatsApp.
Etapa del Kanban (kanbanColumnId): usa la ruta GET /kanbans o cópialo en la ventana de edición de la etapa, en el Kanban.

Consejo: con el token autorizado, las rutas GET /connections, GET /queues y GET /users devuelven todos los IDs de una vez.

Envía tu primer mensaje

En la documentación, abre la ruta POST /messages y haz clic en Try it out.
En Examples, elige un ejemplo y cambia los IDs y el número por los tuyos. El número lleva solo dígitos, con código de país y de área, sin el signo +.
Haz clic en Execute. La respuesta messages scheduled indica que el envío quedó programado.

{
  "connectionId": "ID_DE_LA_CONEXION",
  "messages": [
    {
      "number": "5491199999999",
      "name": "María López",
      "body": "¡Hola, María! Recibimos tu pedido."
    }
  ]
}

Cada mensaje puede tardar hasta 120 segundos en enviarse. Sigues los envíos en Campañas, en una campaña diaria llamada API seguida de la fecha, o con el nombre enviado en campaignName.

Ejemplos listos

El mismo texto para varios contactos: usa globalBody y deja en messages solo el number de cada contacto.

{
  "connectionId": "ID_DE_LA_CONEXION",
  "globalBody": "Nuestra tienda abre mañana a las 9.",
  "messages": [
    { "number": "5491199999999" },
    { "number": "5491188888888" }
  ]
}

Enviar y abrir el chat con un agente, departamento y etapa del Kanban: sin ticketData, el chat se crea en Resueltos. Usa force: true para aplicar los datos también a un chat que ya existe.

{
  "connectionId": "ID_DE_LA_CONEXION",
  "messages": [
    {
      "number": "5491199999999",
      "name": "María López",
      "body": "¡Hola, María! Voy a encargarme de tu atención.",
      "ticketData": {
        "status": "open",
        "userId": "ID_DEL_USUARIO",
        "queueId": "ID_DEL_DEPARTAMENTO",
        "kanbanColumnId": "ID_DE_LA_ETAPA",
        "force": true
      }
    }
  ]
}

Mantener el chat con el agente: dentro de ticketData, usa keepAssigned: true con el userId. Para un plazo, agrega keepAssignedUntil con una fecha futura en formato AAAA-MM-DD. Los próximos mensajes del contacto vuelven al mismo agente, sin pasar por el chatbot.

Dejar a Wäbot respondiendo: dentro de ticketData, usa aiHandling: true.

Actualizar los datos del contacto en el envío: usa contactData con name, email, customFields (cada uno con name y value), tagIds y force: true.

Enviar un archivo: sube el archivo en POST /medias, copia el mediaKey de la respuesta y envíalo con globalMediaKey y globalMediaType (image, video, audio o document).

Enviar una plantilla de la API oficial: indica el templateId. Si la plantilla tiene variables, envía variables con el nombre de la variable tal como aparece en la plantilla, por ejemplo {{1}}, y el valor.

{
  "connectionId": "ID_DE_LA_CONEXION",
  "templateId": "ID_DE_LA_PLANTILLA",
  "messages": [
    {
      "number": "5491199999999",
      "variables": [
        { "name": "{{1}}", "value": "María" }
      ]
    }
  ]
}

Enviar por Web Chat: cambia number por externalId, el identificador del contacto en tu sitio.

Responder un chat que ya existe: envía a POST /tickets/{ticketId}/messages. Para programar la respuesta, agrega sendAt con fecha y hora. Para una nota interna, usa isNote: true.

{
  "body": "Tu pedido salió para entrega."
}

Usa la IA para armar tu integración

La API de Whaticket publica su propia definición en https://api.whaticket.com/api/v1/openapi.json, sin necesidad de token. Con esa dirección, una IA como ChatGPT, Claude o Gemini entiende todas las rutas, los campos y los permisos, y arma la solicitud por ti.

Pásale la definición a la IA: pídele que lea la dirección de arriba. Si la IA no puede abrir enlaces, abre la dirección en el navegador, guarda el archivo y adjúntalo en la conversación.
Describe el resultado, no la técnica: di qué debe pasar, con qué datos y en qué herramienta (n8n, Make, Zapier o código).
Pídele un comando cURL: n8n importa cURL directo en el nodo HTTP Request, y también lo pruebas en la terminal o en Postman.
Nunca pegues la clave del token en la conversación: pídele a la IA que use TU_TOKEN en su lugar y pega la clave tú mismo en la herramienta.
Muéstrale el error a la IA: si la solicitud falla, pega la respuesta de error (sin la clave) y pídele la corrección.

Ejemplo de pedido para la IA:

Lee la definición de la API de Whaticket en https://api.whaticket.com/api/v1/openapi.json.
Cuando entre un pedido nuevo en mi tienda, quiero enviar un WhatsApp de confirmación
al cliente por la conexión ID_DE_LA_CONEXION y dejar el chat abierto en el departamento
Ventas (ID_DEL_DEPARTAMENTO). Usa TU_TOKEN en lugar de la clave.
Arma la solicitud, dame el comando cURL y explícame cómo configurarlo en n8n, paso a paso.

Preguntas frecuentes

¿Cuál es el límite de uso de la API?
Hasta 600 solicitudes por minuto por empresa, sumando todas las rutas, tokens y apps conectadas. Cada mensaje enviado por POST /messages puede tardar hasta 120 segundos en salir.

¿Dónde veo los mensajes enviados por la API?
En Campañas. Los envíos por POST /messages quedan en una campaña por día y por conexión, llamada API seguida de la fecha, o con el nombre enviado en campaignName. Las respuestas por POST /tickets/{ticketId}/messages aparecen directo en el chat.

La solicitud dio error. ¿Qué reviso?
Lee el mensaje de error en la respuesta: indica el campo con problema. Revisa que el encabezado tenga Bearer, un espacio y la clave completa, que el número esté en formato internacional y que el perfil del token tenga el permiso de la ruta. La ruta GET /me muestra los permisos del token.

¿Por qué la lista de chats vuelve vacía?
El token no tiene usuario ni departamentos, así que solo ve chats con el permiso Ver todos en Chats. Para los chats en espera, también necesita Ver en espera.

¿Cómo respondo un chat en la API oficial de WhatsApp?
Por POST /messages, la API oficial siempre exige una plantilla. Para responder un chat abierto, usa POST /tickets/{ticketId}/messages: texto libre dentro de la ventana de 24 horas, o una plantilla aprobada en cualquier momento. La ruta GET /tickets/{ticketId}/templates lista las plantillas que puedes usar en el chat.

Perdí la clave del token. ¿Qué hago?
En la pestaña Tokens, haz clic en Regenerar. La clave anterior deja de funcionar de inmediato, así que actualiza los sistemas que la usan.

¿Qué pasa si cambio el perfil del token?
El token pasa a usar los nuevos permisos del perfil de inmediato, sin crear otro. Un perfil con token vinculado no se puede eliminar.