Configurar get.chat: guía de la API REST y de varios webhooks

Q: ¿Qué pasa si envío un mensaje fuera de la ventana de atención al cliente?

La API devuelve 453 con el motivo "Customer care messaging window expired." y no se entrega nada. Envía una plantilla aprobada, que abre una nueva ventana.

Tabla de Contenidos

Para configurar get.chat, conéctate con la clave de API de tu canal, envía un primer mensaje y registra un webhook para cada sistema que necesite tus eventos de WhatsApp. get.chat es la capa tecnológica detrás de 360Dialog Inbox, y su Inbox API agrega una API REST, la distribución a varios webhooks y una interfaz de bandeja de entrada integrable sobre la WhatsApp Business API oficial.[1] Está incluida en el plan PREMIUM por EUR 99 por número al mes.[2] Esta guía va desde tu clave de API hasta un webhook entrante verificado.

Puntos clave

Necesitas un número de WhatsApp en el plan PREMIUM de 360Dialog con el Inbox activado.
El primer mensaje a un cliente que nunca te escribió debe ser una plantilla aprobada, un formato de mensaje que Meta aprueba por adelantado.
Para empezar solo necesitas tu clave de API actual, y cada sistema que agregues después recibe su propio acceso a la API.
Elige qué eventos recibe cada webhook al crearlo, empezando por los mensajes que te envían tus clientes.

Qué necesitas antes de empezar

Necesitas cinco cosas a mano antes de la primera llamada a la API:

Una cuenta de 360Dialog con tu número de WhatsApp conectado y activo.
El Inbox activado en ese número. Viene con el plan PREMIUM; actívalo en tu canal desde el 360Dialog Hub.[3]
La URL de tu Inbox, con el formato https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/. Abre el Inbox desde el 360Dialog Hub y copia la dirección del navegador. Cada número tiene su propio Inbox con su propia URL.[4]
La clave de API de tu canal, que obtienes en el Hub: es el secreto que identifica tu número cuando llamas a la API de WhatsApp. Generar una clave nueva revoca la anterior, así que reutiliza la clave actual si otra integración depende de ella.[5]
Una dirección HTTPS de acceso público para cada sistema al que quieras enviar eventos.[6]

Todos los puntos de conexión de esta guía están bajo /api/v1/ en la dirección de tu Inbox.

Si conectas tu número por primera vez, puedes obtener acceso a la API y elegir el plan PREMIUM para que el Inbox y su API vengan incluidos.

Cómo autenticarte con tu clave de API y los tokens de servicio

La Inbox API acepta la clave de API de tu canal para la configuración y las pruebas, y un token por servicio en producción. Comprueba la conexión enviando la clave en el encabezado D360-Api-Key:

curl -H "D360-Api-Key: YOUR_API_KEY" \
  https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/api/v1/users/current/

La respuesta muestra el usuario administrador del Inbox, que es la cuenta con la que la clave de API inicia sesión. Una clave de otro canal devuelve 403.

Crea un usuario y un token para cada servicio

Cada sistema que se comunica con el Inbox necesita su propio usuario, porque los webhooks, el conteo de mensajes nuevos, los permisos y los registros de auditoría pertenecen a un usuario. Crea uno con el rol app, que solo tiene acceso a la API:

curl -X POST \
  https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/api/v1/users/ \
  -H "D360-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "crm-sync", "profile": {"role": "app"}}'

La respuesta contiene una activation_url que se devuelve una sola vez. Llámala para obtener el token del servicio:

curl "ACTIVATION_URL"

{"token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"}

Guarda el token en los secretos del servicio, ya que la URL de activación funciona una sola vez. El servicio lo envía con el prefijo Token:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Cómo enviar tu primer mensaje

Lo que puedes enviar depende de la ventana de atención al cliente, el período en el que WhatsApp permite a una empresa enviar mensajes de formato libre. La ventana se abre cuando el cliente te escribe y dura 24 horas desde su último mensaje, o 72 horas en las conversaciones iniciadas desde un anuncio de clic a WhatsApp o desde el botón de llamada a la acción de una página de Facebook o de Instagram.[7] Consulta el vencimiento en contact.messaging_window_expires_at del chat, ya que la duración depende de cómo empezó la conversación.[8]

Estado de la conversación	Lo que puedes enviar
El cliente nunca te escribió	Solo plantillas
El cliente te escribió dentro de la ventana	Texto, multimedia, mensajes interactivos o plantillas
La ventana venció	Solo plantillas

Enviar una plantilla abre una nueva ventana.

Envía texto libre dentro de una ventana abierta

curl -X POST \
  https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/api/v1/messages/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"wa_id": "525512345678", "type": "text", "text": {"body": "Hola desde la Inbox API"}}'

El campo wa_id identifica al destinatario: un número de teléfono en formato internacional sin el signo más, o un ID de usuario a nivel de empresa (BSUID) cuando WhatsApp no comparte el número de la persona. Úsalo exactamente como lo recibiste en el chat.

Para una primera prueba, abre la ventana tú mismo: escanea con tu celular personal el código QR que aparece en Open in WhatsApp en el Inbox y envía un mensaje.

Envía una plantilla para abrir una nueva ventana

Obtén tus plantillas aprobadas con GET /api/v1/templates/ y envía una por su nombre con el mismo formato que la API de WhatsApp:

{
  "wa_id": "525512345678",
  "type": "template",
  "template": {
    "name": "welcome_message",
    "language": {"code": "es_MX"}
  }
}

Interpreta los códigos de respuesta

Los estados enviado, entregado y leído llegan más tarde a tu webhook, y el error 470 para un destinatario sin WhatsApp también llega después.[9]

Código	Significado	Qué hacer
202	Aceptado y en cola para la entrega	Espera los eventos de estado en tu webhook
400	Hay un error en la solicitud	Lee el campo reason
403	No iniciaste sesión o no tienes permiso para este chat	Revisa el encabezado y los permisos de lectura y escritura del usuario
452	El destinatario no es un usuario válido de WhatsApp	Revisa el wa_id
453	La ventana de atención al cliente está cerrada	Envía una plantilla aprobada

Cómo configurar varios webhooks en un mismo número

Un webhook es la dirección a la que WhatsApp entrega los eventos de tu número, y cada número tiene un webhook principal. 360Dialog también puede asociar URL de webhook adicionales directamente a un número, aunque la entrega se vuelve más lenta a medida que se agregan más, y recomienda un solo webhook para las cuentas de alto volumen.[10] El Inbox recibe el webhook principal y llama al webhook de cada servicio que conectes con un HTTP POST, con un cuerpo JSON en el formato estándar de webhook de WhatsApp.[11]

Los webhooks pertenecen a los usuarios. El usuario cuyo token crea un webhook es su propietario, y los usuarios sin derechos de administrador solo ven los suyos.[12]

Crea un punto de conexión

curl -X POST \
  https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/api/v1/webhooks/waba/ \
  -H "Authorization: Token YOUR_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-backend.example.com/whatsapp", "on_incoming_message": true, "on_outgoing_message": true, "on_assigned": false, "headers": {"Authorization": "Bearer your-own-shared-secret"}}'

Configura los indicadores de eventos

Cada indicador activa o desactiva un tipo de evento, así que define todos los indicadores de forma explícita al crear un webhook.

Campo	Entrega
on_incoming_message	Cada mensaje que un cliente envía a tu número
on_outgoing_message	Cada mensaje enviado desde el Inbox, a través de la bandeja de entrada alojada o de la API, para los sistemas que guardan copias completas de las conversaciones
on_assigned	Un chat asignado al usuario de este webhook, o un mensaje nuevo en un chat que ya tiene asignado; actívalo cuando un bot atiende sus chats asignados
on_message_echo	Los mensajes enviados desde tu número a través de la Messaging API de 360Dialog fuera del Inbox, como la carga útil message_echoes de Meta
headers	Encabezados personalizados que se envían con cada entrega

Administra tus puntos de conexión

Llamada	Qué hace
GET /api/v1/webhooks/waba/	Lista los webhooks: los administradores ven los de todos los usuarios y los demás usuarios ven los suyos
POST /api/v1/webhooks/waba/	Crea uno, cuyo propietario es el usuario del token
GET /api/v1/webhooks/waba/{id}/	Muestra los detalles de uno
PUT /api/v1/webhooks/waba/{id}/	Actualiza uno: su dirección, sus eventos y sus encabezados
DELETE /api/v1/webhooks/waba/{id}/	Elimina uno
GET /api/v1/webhooks/waba/{id}/test/	Envía una entrega simulada de statuses a la dirección de destino

Los mismos ajustes están en WABA Webhooks, en la configuración de tu bandeja de entrada (WABA es la sigla de cuenta de WhatsApp Business). Un embudo de ventas en WhatsApp puede funcionar en su propio punto de conexión, independiente de los demás sistemas del número.

Si planeas conectar varios sistemas a un mismo número y quieres una segunda opinión sobre cómo organizar los usuarios y los tokens, habla con nosotros antes de construirlo.

Cómo proteger y procesar las entregas

Tu punto de conexión es una dirección pública que acepta escrituras, así que autentica cada entrega con uno de estos dos métodos:

Encabezados personalizados. El campo headers se envía con cada entrega, así que tu punto de conexión puede exigir su propio token de tipo bearer.
Un secreto compartido en la dirección, como https://your-backend.example.com/whatsapp?auth=SHARED_SECRET, para los sistemas que no pueden leer encabezados personalizados.

Cada entrega llega en el formato estándar de webhook de WhatsApp. En versión resumida, un mensaje entrante se ve así:

{
  "object": "whatsapp_business_account",
  "entry": [{
    "changes": [{
      "value": {
        "contacts": [{"profile": {"name": "Ana"}, "wa_id": "525512345678", "user_id": "MX.13491208655302741918"}],
        "messages": [{"from": "525512345678", "id": "wamid.ID", "type": "text", "text": {"body": "Hola"}}]
      }
    }]
  }]
}

El mensaje está en messages[] y el remitente en contacts[]. El BSUID de user_id siempre está presente, incluso cuando WhatsApp oculta el número de teléfono, así que úsalo primero para identificar a los clientes.

Responde 200 rápido y deja el trabajo lento para después. Los mensajes entregados a un webhook que responde 200 se marcan como recibidos para el usuario de ese webhook, y así el conteo de no leídos en GET /api/v1/chats/ se mantiene correcto.

Cómo integrar el Inbox en tu aplicación

La bandeja de entrada para agentes es una aplicación React de código abierto que puedes integrar en una herramienta existente con una sola etiqueta iframe.[13] Es una buena opción para los equipos que gestionan las conversaciones de WhatsApp en equipo dentro de una herramienta interna o un portal de clientes.

<iframe
  src="https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/?chat_only=1&hide_logo=1"
  allow="clipboard-write"
  width="420" height="700">
</iframe>

Sin allow=»clipboard-write», los navegadores bloquean las acciones de copiar dentro del marco.

Parámetro	Efecto
chat_only=1	Oculta la lista de chats y muestra una sola conversación
hide_logo=1	Quita el logo de get.chat de la pantalla de carga
lng=es	Define el idioma de la interfaz con un código ISO 639-1
bg_color=ff0000	Define el color de fondo como valor hexadecimal sin el signo #
maximize=1	Quita los márgenes del contenedor para que la bandeja de entrada ocupe todo el marco
cf_<filter>	Aplica un filtro de chats al cargar, con cualquier filtro que admita el punto de conexión de chats

Para usar tu propio logo, título de página, favicon y manifiesto de la aplicación, tienes que alojar tú mismo la interfaz de código abierto y definir en la compilación variables como REACT_APP_TITLE, REACT_APP_LOGO_URL y REACT_APP_FAVICON_URL.[14]

Lista de pruebas: verifica tu configuración de principio a fin

Ejecuta estas comprobaciones en orden, ya que una falla en cualquier paso ubica el problema en esa capa.

El Inbox funciona. GET /api/v1/status/health/ devuelve un estado por cada comprobación interna.
Las credenciales son válidas. GET /api/v1/users/current/ devuelve el usuario administrador si usas tu clave de API, o el propio usuario del servicio si usas un token de servicio.
La ventana está abierta. Escribe a tu número de empresa desde una cuenta personal de WhatsApp, o escanea el código QR de Open in WhatsApp en el Inbox.
El mensaje se envía. POST /api/v1/messages/ con un cuerpo de texto devuelve 202, y el mensaje llega al celular.
Los webhooks aparecen en la lista. GET /api/v1/webhooks/waba/ muestra cada punto de conexión y su valor de on_incoming_message.
El punto de conexión es accesible. GET /api/v1/webhooks/waba/{id}/test/ envía una carga útil de statuses simulada, sin ningún mensaje; tu servidor la registra y devuelve 200.
La distribución funciona. Un mensaje entrante desde el celular de prueba llega a cada punto de conexión registrado, y es el único paso que pone a prueba tus indicadores.
El Inbox muestra el chat. Abre el Inbox desde el 360Dialog Hub y revisa la conversación.

Si el evento de prueba nunca llega, revisa que la dirección HTTPS sea accesible, que la respuesta 200 sea rápida y cualquier lista de IP permitidas. Después revisa el punto de conexión en WABA Webhooks, en la configuración de tu bandeja de entrada.

Con la clave de API, los tokens de servicio, los indicadores de webhook y la lista de pruebas en orden, activa tu Inbox en el plan PREMIUM para usar esta configuración en tu propio número.

Preguntas frecuentes

¿Qué método de autenticación usa la API de get.chat?

La Inbox API acepta dos credenciales. La clave de API de tu canal, enviada en el encabezado D360-Api-Key, inicia sesión como administrador del Inbox y sirve para la configuración y las pruebas. En producción, cada servicio usa su propio usuario app y su propio token, que envía como Authorization: Token YOUR_TOKEN en cada llamada.

¿Puedo registrar varios puntos de conexión de webhook en un mismo número de WhatsApp?

Sí. El Inbox recibe el único webhook de WhatsApp y vuelve a entregar cada evento a todos los puntos de conexión registrados, cada uno con sus propios indicadores de eventos y encabezados. Los webhooks pertenecen a cada usuario, así que asigna a cada sistema consumidor su propio usuario y su propio token.

¿Por qué mi webhook no recibe mensajes entrantes?

Consulta el punto de conexión con GET /api/v1/webhooks/waba/{id}/ y comprueba que on_incoming_message sea true. Luego confirma que tu punto de conexión acepta solicitudes HTTPS POST y devuelve 200 rápido, y envía una entrega simulada con GET /api/v1/webhooks/waba/{id}/test/ para probar la conexión.

¿Qué pasa si envío un mensaje fuera de la ventana de atención al cliente?

La API devuelve 453 con el motivo «Customer care messaging window expired.» y no se entrega nada. Envía una plantilla aprobada, que abre una nueva ventana.

¿Para integrar el Inbox tengo que alojarlo yo mismo?

La integración funciona con tu Inbox alojado: apunta un iframe a la dirección del Inbox y ajústalo con parámetros de consulta. Solo necesitas alojar tú mismo la interfaz de código abierto para la marca que se define en la compilación, como tu propio logo, el título de la página y el favicon.

¿Una instancia de get.chat puede atender a varios números de WhatsApp?

Cada número tiene su propio Inbox, con su propia dirección, sus servidores, su base de datos y sus usuarios. Varios números implican varios Inbox, y tu servicio se conecta a cada uno por separado.

Fuentes

[1] 360Dialog Documentation, «Inbox API.» https://docs.360dialog.com/docs/inbox/inbox-api Accessed September 30, 2026.

[2] 360Dialog, «WhatsApp Business Platform Pricing.» https://360dialog.com/pricing Accessed September 25, 2026.

[3] 360Dialog Documentation, «Quickstart» (Hosted Inbox). https://docs.360dialog.com/docs/inbox/hosted-inbox/quickstart Accessed September 30, 2026.

[4] 360Dialog Documentation, «Quickstart» (Inbox API). https://docs.360dialog.com/docs/inbox/inbox-api/quickstart Accessed September 30, 2026.

[5] 360Dialog Documentation, «Authentication» (Inbox API). https://docs.360dialog.com/docs/inbox/inbox-api/authentication Accessed September 30, 2026.

[6] 360Dialog Documentation, «Making Requests» (Inbox API reference). https://docs.360dialog.com/docs/inbox/inbox-api/reference/making-requests Accessed September 30, 2026.

[7] 360Dialog Documentation, «The Customer Service Window.» https://docs.360dialog.com/docs/inbox/the-customer-service-window Accessed September 30, 2026.

[8] 360Dialog Documentation, «Sending Messages» (Inbox API). https://docs.360dialog.com/docs/inbox/inbox-api/sending-messages Accessed September 30, 2026.

[9] 360Dialog Documentation, «Messages» (Inbox API reference). https://docs.360dialog.com/docs/inbox/inbox-api/api-ref/messages Accessed September 30, 2026.

[10] 360Dialog Partner Documentation, «Set multiple webhooks for Phone Number.» https://docs.360dialog.com/partner/onboarding/webhook-events-and-setup/set-multiple-webhooks-for-phone-number Accessed September 28, 2026.

[11] 360Dialog Documentation, «Receiving Messages» (Inbox API). https://docs.360dialog.com/docs/inbox/inbox-api/receiving-messages Accessed September 30, 2026.

[12] 360Dialog Documentation, «Webhooks» (Inbox API reference). https://docs.360dialog.com/docs/inbox/inbox-api/api-ref/webhooks Accessed September 30, 2026.

[13] get.chat documentation, «Embed and White-Label the Inbox.» https://docs.getchat.360dialog.io/guides/2-embedding-the-inbox/ Accessed September 25, 2026.

[14] get.chat, «get.chat Web App» README. https://github.com/get-chat/web-app Accessed September 25, 2026.