Skip to content

Integrar una aplicación propia al Webchat (modo API) ​

Acceso

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 POST con 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 ​

  1. Accede a ¡Hola! Store → Webchat → Acceder y abre el registro del canal.
  2. En la sección Integrar aplicación propia, haz clic en Editar información.
  3. Activa Integrar aplicación propia.
  4. 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.
  5. 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 pantallaPara qué sirve
Token de autenticaciónLlega 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 mensajesDirección base para que tu aplicación envíe los mensajes del usuario.
Token de autenticación de HolaVa en el encabezado Authorization cuando tu aplicación llama a la API de recepción.
  1. Copia los tres datos y guárdalos en el servidor de tu aplicación.
  2. 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.
El ID del canal forma parte de la URL

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.

Desactivar la integración genera tokens nuevos

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 ​

  1. Implementa el envío de los mensajes del usuario, según Enviar mensajes del usuario a ¡Hola! Suite.
  2. Implementa la recepción de las respuestas, según Recibir los mensajes de la atención.
  3. Envía un mensaje de prueba por la aplicación.
  4. 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 ​

ÍtemValor
MétodoPOST
URLhttps://SEU-DOMINIO/api/v1/webchat/ID-DO-CANAL/message
Encabezado de autenticaciónAuthorization: Bearer TOKEN-DE-AUTENTICACAO-DO-OPA
Tipo de contenidoContent-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

json
{
  "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)

json
{
  "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

CampoObligatorioRegla
user.idSíTexto no vacío. Identifica el contacto y la conversación (consulta Identidad del contacto).
user.email, user.username, user.avatarNoTexto. 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.typeSí"text" o "media".
message.textSí, si type es textTexto no vacío.
message.media.mediaTypeSí, si type es mediaTipo MIME válido (ej.: image/png, application/pdf).
message.media.urlUno de los dosURL HTTPS válida del archivo.
message.media.dataUno de los dosContenido del archivo en base64 válido.
message.media.filename, message.media.captionNoNombre del archivo y leyenda.

En media, informa url o data, nunca los dos.

Ejemplo con curl

bash
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.id identifica el contacto. Mientras tu aplicación envíe el mismo user.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.id nuevo crea un contacto nuevo.
  • Los campos email, username y avatar actualizan 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 mediaType informado (ej.: image/* con image/*). Si no lo es, el mensaje se rechaza con Failed 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.

ÍtemValor
MétodoPOST
URLLa URL informada en API de envío de mensajes
EncabezadosX-Signature: TOKEN-DE-SEGURANCA y Content-Type: application/json
CuerpoObjeto 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)

CampoSignificado
_idIdentificador de la atención en ¡Hola! Suite.
protocoloProtocolo de la atención.
canal_clienteIdentificador 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_userIdentificador del contacto en ¡Hola! Suite.

Mensaje (message)

CampoSignificado
_idIdentificador del mensaje.
id_rotaIdentificador de la atención.
id_atendQuién envió del lado de ¡Hola! Suite.
id_assistantSe completa cuando el mensaje fue generado por un asistente de IA.
tipoTipo del contenido, como texto, midia, localizacao o menuInterativo.
mensagemContenido del mensaje.
objetoAdjunto, cuando lo hay, con nome, tipo, size, descricao y url para descarga.
dataFecha y hora del mensaje.

Respuestas y errores ​

SituaciónStatus HTTPCuerpo de la respuesta
Mensaje recibido200{ "success": true }
Sin el encabezado Authorization401{ "error": "UNAUTHORIZED" }
Canal inactivo, URL sin el ID del canal, modo API desactivado o token de otro canal401{ "error": "UNAUTHORIZED" }
Campo inválido o faltante200{ "error": "ARGUMENT_VALUE_ERROR", "message": "detalhe do campo" }
Canal no inicializado en el momento del envío200{ "error": "NOT_FOUND_ERROR", "message": "Web chat channel not initialized" }
No fue posible descargar o validar el archivo200{ "error": "BAD_REQUEST_ERROR", "message": "Failed to process message media" }
No fue posible guardar el mensaje200{ "error": "BAD_REQUEST_ERROR", "message": "Failed to persist message media" }
Error inesperado en el servidor500Error genérico
Trata el campo error, no solo el status

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íntomaQué verificar
La API responde UNAUTHORIZEDVerifica 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_ERROREl 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ónVerifica 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 nuevoEl 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-Signature antes de procesar un mensaje recibido.
  • Usa un user.id estable.
  • Prefiere enviar archivos por URL HTTPS.

Contenidos relacionados ​