Integrar una aplicación propia al Webchat (modo API)
Ruta: ¡Hola! Store → Webchat → Acceder → registro del canal → Integrar aplicación propia
Visión general
El modo API del Webchat te permite usar ¡Hola! Suite como central de atención del chat de la aplicación de tu empresa, sin la ventana de chat del sitio web. Así, el cliente sigue dentro de tu app, y el equipo atiende por ¡Hola! Suite, con historial y métricas como en cualquier otro canal.
La integración funciona por webhook en las dos direcciones: tu aplicación envía los mensajes del usuario a ¡Hola! Suite por HTTP, y ¡Hola! Suite envía a una URL de tu aplicación todo lo que se responde en la atención, ya sea por un agente, por el agente virtual o por el flujo de comunicación. No hay consulta periódica (polling).
Este artículo está dirigido a quien desarrolla la integración. Para instalar el chat en el sitio web, consulta Instalar el Webchat en el sitio web.
Requisitos previos
- Webchat instalado en ¡Hola! Suite, con licencia activa y un Agente virtual responsable. Consulta Instalar el Webchat en el sitio web.
- Permiso para visualizar ¡Hola! Store en tu grupo de permisos.
- Una URL en tu aplicación lista para recibir solicitudes
POSTcon JSON. Es a ella que ¡Hola! Suite envía las respuestas de la atención. Recomendamos que sea HTTPS. - Quien desarrolla la aplicación, con acceso para implementar las llamadas descritas aquí.
Paso a paso
Activar el modo API en el canal
- Accede a ¡Hola! Store → Webchat → Acceder y abre el registro del canal.
- En la sección Integrar aplicación propia, haz clic en Editar información.
- Activa Integrar aplicación propia.
- En API de envío de mensajes, informa la URL de tu aplicación que recibirá las respuestas de la atención (ej.:
https://app.suaempresa.com.br/opa/webhook). El campo es obligatorio y debe ser una URL válida. - Haz clic en Guardar.
Copiar los datos de la integración
Después de guardar, la sección muestra tres datos generados por ¡Hola! Suite, cada uno con un botón para copiar:
| Campo en la pantalla | Para qué sirve |
|---|---|
| Token de autenticación | Llega en el encabezado X-Signature de cada solicitud que ¡Hola! Suite envía a tu aplicación. Sirve para confirmar el origen. |
| API de recepción de mensajes | Dirección base para que tu aplicación envíe los mensajes del usuario. |
| Token de autenticación de Hola | Va en el encabezado Authorization cuando tu aplicación llama a la API de recepción. |
- Copia los tres datos y guárdalos en el servidor de tu aplicación.
- Anota el ID del Canal. Aparece en la dirección del navegador, en la pantalla del canal (
.../web-chat/list/ID-DO-CANAL/adjustments), y en la parte superior de la pantalla cuando Mostrar IDs en los formularios está activo en Configuraciones → Empresa.
Para enviar mensajes, usa https://SEU-DOMINIO/api/v1/webchat/ID-DO-CANAL/message. El campo API de recepción de mensajes muestra la dirección sin el ID del canal: incluye el ID antes de /message. Sin él, la API responde UNAUTHORIZED.
Al desactivar Integrar aplicación propia y guardar, los tokens se borran. Si la activas de nuevo, ¡Hola! Suite genera tokens diferentes, y tu aplicación debe actualizarse.
Implementar y probar
- Implementa el envío de los mensajes del usuario, según Enviar mensajes del usuario a ¡Hola! Suite.
- Implementa la recepción de las respuestas, según Recibir los mensajes de la atención.
- Envía un mensaje de prueba por la aplicación.
- Verifica si la atención aparece en ¡Hola! Suite y si la respuesta llega a la URL configurada.
Resultado esperado
Cada mensaje enviado por tu aplicación abre o continúa una atención en ¡Hola! Suite, que sigue el agente virtual y el flujo de comunicación del canal. Cada mensaje enviado en esa atención por el agente, por el agente virtual o por el flujo se entrega a la URL informada en API de envío de mensajes.
Enviar mensajes del usuario a ¡Hola! Suite
| Ítem | Valor |
|---|---|
| Método | POST |
| URL | https://SEU-DOMINIO/api/v1/webchat/ID-DO-CANAL/message |
| Encabezado de autenticación | Authorization: Bearer TOKEN-DE-AUTENTICACAO-DO-OPA |
| Tipo de contenido | Content-Type: application/json |
El token debe ser exactamente el Token de autenticación de Hola de ese canal. No es el token de un usuario de ¡Hola! Suite.
Mensaje de texto
{
"user": {
"id": "usuario-externo-123",
"email": "joao@exemplo.com",
"username": "João Silva",
"avatar": "https://exemplo.com/avatar.png"
},
"message": {
"type": "text",
"text": "Olá, preciso de ajuda"
}
}Mensaje con archivo (por URL)
{
"user": { "id": "usuario-externo-123" },
"message": {
"type": "media",
"media": {
"mediaType": "image/png",
"url": "https://exemplo.com/comprovante.png",
"filename": "comprovante.png",
"caption": "Segue o comprovante"
}
}
}Para enviar el archivo dentro de la propia solicitud, cambia url por data, con el contenido del archivo en base64.
Campos
| Campo | Obligatorio | Regla |
|---|---|---|
user.id | Sí | Texto no vacío. Identifica el contacto y la conversación (consulta Identidad del contacto). |
user.email, user.username, user.avatar | No | Texto. Completan o actualizan el nombre, el correo electrónico y la foto del contacto en ¡Hola! Suite. En avatar, informa la URL de la imagen. |
message.type | Sí | "text" o "media". |
message.text | Sí, si type es text | Texto no vacío. |
message.media.mediaType | Sí, si type es media | Tipo MIME válido (ej.: image/png, application/pdf). |
message.media.url | Uno de los dos | URL HTTPS válida del archivo. |
message.media.data | Uno de los dos | Contenido del archivo en base64 válido. |
message.media.filename, message.media.caption | No | Nombre del archivo y leyenda. |
En media, informa url o data, nunca los dos.
Ejemplo con curl
curl -X POST "https://SEU-DOMINIO/api/v1/webchat/ID-DO-CANAL/message" \
-H "Authorization: Bearer TOKEN-DE-AUTENTICACAO-DO-OPA" \
-H "Content-Type: application/json" \
-d '{"user":{"id":"usuario-123"},"message":{"type":"text","text":"Olá"}}'Identidad del contacto y continuidad de la conversación
- El
user.ididentifica el contacto. Mientras tu aplicación envíe el mismouser.id, ¡Hola! Suite reconoce el mismo contacto y mantiene la continuidad entre sesiones. - En el modo API, quien crea y guarda ese identificador es tu aplicación. Genera un valor fijo por usuario (por ejemplo, un UUID) y guárdalo de tu lado. Un
user.idnuevo crea un contacto nuevo. - Los campos
email,usernameyavataractualizan el registro del contacto siempre que se envían.
Límites de adjuntos
- Se acepta cualquier tipo MIME válido en
mediaType, como imágenes (image/*) y PDF (application/pdf). - Cuando el archivo va por URL, ¡Hola! Suite descarga el archivo y verifica si el tipo devuelto por el servidor es de la misma familia del
mediaTypeinformado (ej.:image/*conimage/*). Si no lo es, el mensaje se rechaza conFailed to process message media. - Límite por URL: 40 MB por archivo. Los archivos más grandes o vacíos se rechazan.
- Límite por base64: la solicitud completa puede tener como máximo 20 MB. Como el base64 aumenta el tamaño del archivo, prefiere enviar por URL los archivos más grandes.
Recibir los mensajes de la atención
Todo mensaje enviado en la atención por un agente, por el agente virtual o por el flujo de comunicación genera un POST a la URL de API de envío de mensajes.
| Ítem | Valor |
|---|---|
| Método | POST |
| URL | La URL informada en API de envío de mensajes |
| Encabezados | X-Signature: TOKEN-DE-SEGURANCA y Content-Type: application/json |
| Cuerpo | Objeto con customerService (datos de la atención) y message (el mensaje) |
Valida el origen: antes de aceptar la solicitud, verifica si el valor de X-Signature es igual al Token de autenticación del canal. Si es diferente, descártala.
Datos de la atención (customerService)
| Campo | Significado |
|---|---|
_id | Identificador de la atención en ¡Hola! Suite. |
protocolo | Protocolo de la atención. |
canal_cliente | Identificador del contacto en el canal, es decir, el user.id que envió tu aplicación. Úsalo para saber a qué usuario entregar el mensaje. |
id_user | Identificador del contacto en ¡Hola! Suite. |
Mensaje (message)
| Campo | Significado |
|---|---|
_id | Identificador del mensaje. |
id_rota | Identificador de la atención. |
id_atend | Quién envió del lado de ¡Hola! Suite. |
id_assistant | Se completa cuando el mensaje fue generado por un asistente de IA. |
tipo | Tipo del contenido, como texto, midia, localizacao o menuInterativo. |
mensagem | Contenido del mensaje. |
objeto | Adjunto, cuando lo hay, con nome, tipo, size, descricao y url para descarga. |
data | Fecha y hora del mensaje. |
Respuestas y errores
| Situación | Status HTTP | Cuerpo de la respuesta |
|---|---|---|
| Mensaje recibido | 200 | { "success": true } |
Sin el encabezado Authorization | 401 | { "error": "UNAUTHORIZED" } |
| Canal inactivo, URL sin el ID del canal, modo API desactivado o token de otro canal | 401 | { "error": "UNAUTHORIZED" } |
| Campo inválido o faltante | 200 | { "error": "ARGUMENT_VALUE_ERROR", "message": "detalhe do campo" } |
| Canal no inicializado en el momento del envío | 200 | { "error": "NOT_FOUND_ERROR", "message": "Web chat channel not initialized" } |
| No fue posible descargar o validar el archivo | 200 | { "error": "BAD_REQUEST_ERROR", "message": "Failed to process message media" } |
| No fue posible guardar el mensaje | 200 | { "error": "BAD_REQUEST_ERROR", "message": "Failed to persist message media" } |
| Error inesperado en el servidor | 500 | Error genérico |
Los errores de validación y de procesamiento vuelven con status 200 y el detalle en el campo error del cuerpo. Solo las fallas de autenticación y los errores inesperados usan status de error. Verifica siempre si el cuerpo tiene "success": true.
Limitaciones del modo API
- "Escribiendo" y confirmación de lectura: no se envían a tu aplicación, y la API no recibe esos eventos del usuario. La entrada acepta solo mensajes de texto y de archivo.
- Posición en la fila y disponibilidad de agentes: no hay consulta de esa información por la API. Para avisar al contacto sobre la posición en la fila, usa la opción Avisar posición en la fila en las configuraciones del departamento.
- Límite de solicitudes: ¡Hola! Suite no define un límite de solicitudes para esta API.
- Confirmación de recepción: los mensajes recibidos entran en una fila de procesamiento. El
{ "success": true }confirma que el mensaje fue aceptado, no que ya apareció para el agente.
Problemas comunes
| Síntoma | Qué verificar |
|---|---|
La API responde UNAUTHORIZED | Verifica si la URL tiene el ID del canal antes de /message, si el encabezado es Authorization: Bearer seguido del Token de autenticación de Hola del mismo canal, si Integrar aplicación propia está activo y si el canal está Activo. |
La API responde NOT_FOUND_ERROR | El canal no estaba disponible en el momento del envío. Verifica el Estado del Webchat e inténtalo de nuevo. |
| Las respuestas del agente no llegan a la aplicación | Verifica la URL en API de envío de mensajes, si acepta POST con JSON y si tu aplicación no está rechazando la solicitud en la validación del X-Signature. |
| Cada mensaje crea un contacto nuevo | El user.id está cambiando. Usa siempre el mismo identificador para el mismo usuario. |
Buenas prácticas
- Guarda los tokens en el servidor de tu aplicación, nunca en el código que se ejecuta en el celular o en el navegador del usuario.
- Valida siempre el
X-Signatureantes de procesar un mensaje recibido. - Usa un
user.idestable. - Prefiere enviar archivos por URL HTTPS.