Cómo usar la documentación de la API Send de Whaticket para enviar mensajes

La API Send de Whaticket permite enviar mensajes desde otros sistemas por tus conexiones de WhatsApp, API oficial de WhatsApp y Web Chat. Cada solicitud se autentica con un token Bearer, que se crea en la pantalla Integraciones.

En este artículo encuentras los IDs necesarios, creas el token, haces el primer envío desde la documentación interactiva y consultas ejemplos listos.

Qué cambia en tu operación

Tu CRM, e-commerce o automatización envía mensajes por Whaticket sin que nadie tenga que abrir la plataforma.
Puedes dirigir el chat creado a un departamento o usuario específico.
Los datos del contacto, como nombre, correo y campos personalizados, se completan en el mismo envío.

Antes de empezar

Tu perfil necesita los permisos Ver y Crear del grupo Tokens de API.
El token usa los permisos de un perfil. Para enviar mensajes, ese perfil necesita los permisos Crear e Iniciar del grupo Campañas.
Solo puedes vincular al token un perfil con permisos que tú también tienes.
Servidor base de la API: https://api.whaticket.com/api/v1.

Paso a paso:

Copia el ID de la conexión

En el menú de la izquierda, haz clic en Conexiones.
En el menú de acciones de la conexión que enviará los mensajes, haz clic en Editar.
En la ventana Edita Conexión, haz clic en el ícono de copiar junto al título para copiar el ID.

Usa ese ID en el campo connectionId.

Copia el ID del departamento

En el menú de la izquierda, haz clic en Departamentos & Chatbots. Si no aparece, búscalo en Más.
Haz clic en el departamento o, en su menú de acciones, en Editar.
Haz clic en el ícono Copiar identificación junto al título.

Usa ese ID en el campo queueId cuando quieras que el chat llegue a un departamento específico.

Copia el ID del usuario

En el menú de la izquierda, haz clic en Equipo.
Haz clic en el usuario o, en su menú de acciones, en Editar.
Haz clic en el ícono Copiar identificación junto al título.

Usa ese ID en el campo userId cuando quieras asignar el chat a un agente.

Copia el ID de la plantilla de mensaje

En el menú de la izquierda, haz clic en Plantillas y Flows. El ítem solo aparece cuando la empresa tiene una conexión de la API oficial de WhatsApp.
Abre la plantilla que quieres enviar.
Haz clic en el ícono de copiar junto al nombre de la plantilla.

Usa ese ID en el campo templateId. Es obligatorio para conexiones de la API oficial de WhatsApp.

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 del token.
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, usa Regenerar en el token para generar una clave nueva.

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 en el campo y haz clic en Authorize.
Cierra la ventana. Cuando el candado del botón Authorize aparece cerrado, la documentación está lista para probar.

Envía tu primer mensaje

En la documentación, abre la sección Messages y haz clic en la ruta POST /messages para expandirla.
Haz clic en Try it out.
En Examples, elige un ejemplo y cambia los IDs y el número por los tuyos.
Haz clic en Execute para enviar.

Ejemplo de envío simple:

{
  "connectionId": "ID_DE_LA_CONEXION",
  "messages": [
    {
      "number": "5513991113966",
      "name": "Test Contact",
      "body": "This is a test message body..."
    }
  ]
}

Ejemplos de envío con la API

Enviar el mismo mensaje a varios contactos

{
  "connectionId": "ID_DE_LA_CONEXION",
  "globalBody": "Hi, im here to talk about...!",
  "messages": [
    { "number": "5513991113966" },
    { "number": "5513991113967" },
    { "number": "5513991113968" }
  ]
}

Enviar el mismo archivo a varios contactos

Antes, sube el archivo con la ruta POST /medias y usa la clave que devuelve en globalMediaKey.

{
  "connectionId": "ID_DE_LA_CONEXION",
  "globalMediaKey": "mstile150x150_88e21cba92da4f1ca4cfbeef453b1fbe.png",
  "globalMediaType": "image",
  "messages": [
    { "number": "5513991113966" },
    { "number": "5513991113967" }
  ]
}

Enviar y asignar el chat a un usuario y departamento

{
  "connectionId": "ID_DE_LA_CONEXION",
  "messages": [
    {
      "number": "5513991113966",
      "name": "Test Contact",
      "body": "This is a test message body...",
      "ticketData": {
        "status": "open",
        "userId": "ID_DEL_USUARIO",
        "queueId": "ID_DEL_DEPARTAMENTO",
        "force": true
      }
    }
  ]
}

Enviar y mantener el chat con el usuario hasta una fecha

Con keepAssigned, los próximos mensajes del contacto vuelven al mismo usuario, sin pasar por el chatbot. La fecha de keepAssignedUntil debe ser futura, en el formato AAAA-MM-DD.

{
  "connectionId": "ID_DE_LA_CONEXION",
  "messages": [
    {
      "number": "5513991113966",
      "name": "Test Contact",
      "body": "This is a test message body...",
      "ticketData": {
        "userId": "ID_DEL_USUARIO",
        "keepAssigned": true,
        "keepAssignedUntil": "2026-12-31",
        "force": true
      }
    }
  ]
}

Enviar y completar los datos del contacto

{
  "connectionId": "ID_DE_LA_CONEXION",
  "messages": [
    {
      "number": "5513991113966",
      "body": "This is a test message body...",
      "contactData": {
        "name": "New name for my contact",
        "email": "contacto@ejemplo.com",
        "force": true,
        "customFields": [
          { "name": "custom_id", "value": "11111" },
          { "name": "country", "value": "Brazil" }
        ]
      }
    }
  ]
}

Enviar plantilla de la API oficial de WhatsApp

{
  "connectionId": "ID_DE_LA_CONEXION",
  "templateId": "ID_DE_LA_PLANTILLA",
  "messages": [
    { "number": "5513991113966", "name": "Test Contact" }
  ]
}

Enviar plantilla con variables

En name, usa el nombre de la variable tal como aparece en la plantilla, es decir, el número de la variable entre llaves dobles. El ejemplo listo está en la pestaña Documentación, en Examples. La cantidad de variables debe ser la misma de la plantilla.

{
  "connectionId": "ID_DE_LA_CONEXION",
  "templateId": "ID_DE_LA_PLANTILLA",
  "messages": [
    {
      "number": "5513991113966",
      "name": "Test Contact",
      "variables": [
        { "name": "NOMBRE_DE_LA_VARIABLE_EN_LA_PLANTILLA", "value": "Maria" }
      ]
    }
  ]
}

Enviar plantilla con archivo

{
  "connectionId": "ID_DE_LA_CONEXION",
  "templateId": "ID_DE_LA_PLANTILLA",
  "globalMediaKey": "CLAVE_DEL_ARCHIVO",
  "globalMediaType": "image",
  "messages": [
    { "number": "5513991113966" },
    { "number": "5513991113967" }
  ]
}

Enviar mensaje por Web Chat

En Web Chat, el contacto se identifica con externalId en lugar de number.

{
  "connectionId": "ID_DE_LA_CONEXION_WEB_CHAT",
  "messages": [
    {
      "externalId": "user-abc-123",
      "name": "Web Chat User",
      "body": "Hello from the API via Web Chat channel"
    }
  ]
}

Campos de la solicitud

Campos generales

connectionId: ID de la conexión que envía los mensajes. El campo antiguo whatsappId todavía se acepta.
templateId: ID de la plantilla. Obligatorio en la API oficial de WhatsApp y prohibido en los otros canales.
campaignName: nombre de la campaña donde se agrupan los envíos.
globalBody: texto enviado a todos los contactos.
globalMediaKey y globalMediaType: clave y tipo del archivo enviado a todos los contactos.
globalVariables: variables de la plantilla aplicadas a todos los mensajes que no tengan las suyas.
fastMode: envía sin el intervalo estándar entre mensajes. Úsalo solo en envíos transaccionales.
messages: lista de mensajes, de 1 a 999 por solicitud.

Campos de cada mensaje

number: número del contacto con código de país y de área, solo dígitos y sin cero al inicio. Obligatorio en WhatsApp y en la API oficial.
externalId: identificador del contacto en Web Chat, en lugar de number.
name: nombre del contacto, con al menos 3 caracteres. Se usa al crear un contacto nuevo.
body: texto del mensaje.
mediaKey y mediaType: archivo solo de este mensaje.
variables: variables de la plantilla solo de este mensaje.

Datos del chat (ticketData)

status: open, pending o closed.
userId y queueId: usuario y departamento del chat.
keepAssigned y keepAssignedUntil: mantienen el chat con el usuario, opcionalmente hasta una fecha.
aiHandling: crea el chat con Wäbot respondiendo.
force: aplica estos datos también a un chat que ya existe.

Datos del contacto (contactData)

name, treatmentName (apodo o forma de trato) y email.
customFields: campos personalizados, cada uno con name y value.
tagIds: IDs de las etiquetas aplicadas al contacto.
force: actualiza un contacto que ya existe.

Preguntas frecuentes

¿El mensaje se envía en el momento?
La ruta POST /messages crea o reutiliza una campaña de tipo API y programa los envíos. Cada mensaje puede tardar hasta 120 segundos en salir, y puedes seguir los envíos en Campañas.

¿Cómo respondo un chat que ya existe en la API oficial de WhatsApp?
Por la ruta POST /messages, la API oficial siempre exige una plantilla. Para responder un chat abierto, usa la ruta POST /tickets/{ticketId}/messages, descrita en la misma documentación.

¿Hay límite de solicitudes?
Sí. La API acepta hasta 600 solicitudes por minuto por empresa.

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