Integrar WhatsApp con tu CRM o sistema: API, webhooks y n8n
Integrar WhatsApp con tu CRM o tu sistema significa que los datos viajen solos: que un formulario de tu web cree el contacto y le escriba, que tu software de facturación avise cuando sale una factura o que cada mensaje que llega quede registrado donde lo necesitas. Con Omniia se hace con su API REST, sus webhooks, las automatizaciones que se disparan desde otro sistema y n8n.
Primero: ¿necesitas integrar o te basta con un CRM para WhatsApp?
Si hoy tus clientes viven en un Excel o en la memoria del vendedor, quizás no necesitas integrar nada: un CRM para WhatsApp como Omniia ya trae contactos con campos propios, etiquetas, embudo de ventas por etapas e historial de cada cliente. Si estás en ese punto, lee CRM vs Excel.
Integrar tiene sentido cuando ya tienes un sistema que manda: un ERP, un programa de facturación, el software de una clínica o de un colegio, o una tienda en línea. Ahí el objetivo es que WhatsApp y ese sistema se hablen sin que nadie copie y pegue.
Las piezas de una integración
| Pieza | Dirección | Para qué sirve |
|---|---|---|
| API REST | De tu sistema hacia Omniia | Enviar mensajes y plantillas, crear o actualizar contactos, consultar y cerrar conversaciones |
| Webhooks | De Omniia hacia tu sistema | Avisarte al instante cuando llega un mensaje, se crea un contacto o se cierra una conversación |
| Automatización “Otro sistema lo pide” | De tu sistema hacia Omniia | Arrancar una secuencia de mensajes con un solo llamado |
| n8n | En los dos sentidos | Conectar sistemas armando flujos, sin programar todo desde cero |
| Consultas durante el chat | De Omniia hacia tu sistema | Que el bot o el agente de IA consulte un dato en vivo para responder |
La API REST de Omniia
La API se activa en Ajustes → API. Ahí creas una llave de acceso, que empieza por omn_live_ y se muestra una sola vez, y la mandas en cada llamada con el encabezado Authorization: Bearer. La misma pestaña trae la documentación completa, que también se descarga en PDF. Es la misma API para los canales conectados por QR y por la API oficial de WhatsApp.
Estos son algunos de los métodos disponibles:
| Método | Qué hace |
|---|---|
| GET /api/v1/channels | Lista tus canales, para saber por cuál enviar |
| POST /api/v1/messages | Envía un texto, un archivo o una plantilla. Si el contacto o la conversación no existen, los crea |
| GET /api/v1/templates | Lista las plantillas aprobadas de cada canal de la API oficial |
| POST /api/v1/contacts | Crea un contacto con sus campos personalizados |
| PATCH /api/v1/contacts/by-phone/:phone | Actualiza un contacto sabiendo solo su teléfono |
| GET /api/v1/conversations | Lista conversaciones |
| POST /api/v1/conversations/:id/close | Cierra una conversación |
| GET /api/v1/agents | Lista los asesores, para asignarle el chat a uno al enviar |
Tres detalles que ahorran problemas:
- La ventana de 24 horas también aplica. En un canal de la API oficial, si mandas un texto a alguien que no te ha escrito en las últimas 24 horas, la API responde con el error meta_window_expired. Para iniciar la conversación, envía una plantilla con su nombre, su idioma y sus variables.
- Evita envíos dobles. Si tu sistema reintenta por un corte de red, manda el encabezado Idempotency-Key con un identificador único: Omniia devuelve la respuesta original en vez de enviar el WhatsApp otra vez.
- Asigna el asesor desde tu sistema. Con el campo assignedUserId, la conversación queda fijada al vendedor que tu CRM ya tiene asignado a ese cliente.
Webhooks: que tu sistema se entere al instante
En la misma pestaña de Ajustes → API registras la dirección de tu sistema y eliges los eventos que quieres recibir. Puedes limitar cada suscripción a un canal. Entre los eventos disponibles están:
- message.received y message.sent: llegó o salió un mensaje.
- message.status: un mensaje enviado pasó a entregado, leído o fallido. Es la forma de enterarte de que una plantilla no llegó.
- conversation.created, conversation.assigned y conversation.closed.
- contact.created.
- csat.responded: el cliente calificó la atención del 1 al 5.
Cada envío va firmado: el encabezado X-Omniia-Signature lleva un HMAC-SHA256 calculado con el secreto de la suscripción sobre la marca de tiempo y el cuerpo, y X-Omniia-Timestamp trae la hora del envío. Verifica la firma antes de confiar en el contenido. Si tu servidor no responde con un código 2xx, Omniia reintenta al minuto, a los 5 minutos, a los 30 minutos y a las 2 horas, hasta 5 intentos, y deja el registro para reintentarlo a mano.
n8n: integrar sin programar todo
n8n es una herramienta para armar flujos de automatización entre aplicaciones, que también se puede instalar en tu propio servidor. Según su documentación, el nodo Webhook recibe datos de otras aplicaciones cuando ocurre un evento y el nodo HTTP Request llama a cualquier servicio con API REST. Con eso se conecta a Omniia de tres maneras:
- Webhook por canal. En la configuración de cada canal de Omniia hay un campo “n8n webhook”: cada mensaje que llega a ese canal se envía a esa dirección, con el remitente, el texto y los datos de la conversación.
- Webhooks firmados. El nodo Webhook de n8n recibe los eventos de Ajustes → API, como un cierre de conversación o una calificación.
- Llamadas a la API. El nodo HTTP Request de n8n llama a la API de Omniia para enviar una plantilla o actualizar un contacto.
Casos de uso
El formulario de tu sitio web
Alguien llena el formulario de cotización de tu página. Tu web, o n8n, llama a la URL de una automatización de Omniia con el disparador Otro sistema lo pide, enviando el teléfono, el nombre y los campos del formulario. Omniia crea el contacto si no existe y arranca la secuencia: una plantilla de bienvenida, una espera y una tarea para el vendedor, como en seguimiento automático de clientes. Si además quieres que el visitante te escriba directo, suma un botón de WhatsApp para tu página web.
El programa de facturación o el ERP
Cuando se emite una factura, tu sistema llama a POST /api/v1/messages con una plantilla de utilidad que lleva el PDF en el encabezado. El envío queda en la conversación del cliente, a la vista de tu equipo, y si responde con una duda, la atiende un asesor desde la bandeja.
El software de una clínica o un colegio
Cada vez que cambia algo importante del paciente o del estudiante, el software actualiza el contacto en Omniia con PATCH /api/v1/contacts/by-phone/:phone. Así el asesor que atiende el chat ve el dato al día sin abrir otro programa. Antes de mover datos sensibles, revisa tus autorizaciones de habeas data.
Reportes en tu propia base de datos
Con los eventos conversation.closed y csat.responded, n8n guarda en tu base de datos o en una hoja de cálculo cada atención cerrada con su calificación, para cruzarla con tus ventas.
El bot que consulta tu sistema
Durante el chat, el agente de IA puede consultar un sistema de tu empresa con una acción HTTP. Por ejemplo, en una cooperativa, el asociado pregunta por el estado de su solicitud, el agente le pide el número de documento, consulta tu sistema y responde con lo que devuelve. En los flujos, el bloque Consultar API hace lo mismo y guarda la respuesta en variables. Más ejemplos del sector en WhatsApp para financieras y cooperativas.
Cómo integrar WhatsApp con tu sistema, paso a paso
- 1Crea una llave en Ajustes → API y guárdala en un lugar seguro: solo se muestra una vez.
- 2Prueba la llave con GET /api/v1/me, que devuelve el nombre de tu espacio de trabajo.
- 3Consulta GET /api/v1/channels y anota el id del canal por el que vas a enviar.
- 4Envía un mensaje de prueba a tu propio número con POST /api/v1/messages.
- 5Registra un webhook con la dirección de tu sistema, elige los eventos y verifica la firma.
- 6Antes de pasar a producción, agrega Idempotency-Key a los envíos y respeta los límites por minuto que indica la documentación.
Preguntas frecuentes
¿Omniia tiene API?
Sí. Tiene una API REST con llaves de acceso para enviar mensajes y plantillas, gestionar contactos y consultar o cerrar conversaciones, y webhooks firmados para recibir eventos. La documentación está en Ajustes → API.
¿Puedo conectar Omniia con n8n?
Sí. Cada canal tiene un campo para enviar los mensajes que llegan a un webhook de n8n, y desde n8n puedes llamar a la API de Omniia o recibir sus webhooks firmados.
¿Necesito un programador para integrar WhatsApp con mi sistema?
Para la API y los webhooks conviene alguien que conozca tu sistema. Para casos simples, como arrancar una secuencia desde un formulario, basta con llamar a la URL de una automatización desde tu web o desde n8n.
¿La API sirve con WhatsApp por QR?
Sí. La misma API y la misma llave sirven para canales por QR y por la API oficial. La diferencia es que por QR no hay plantillas y se puede escribir en cualquier momento, mientras que por la API oficial, pasadas las 24 horas, solo se puede con plantilla.
Prueba Omniia gratis durante 1 semana
Sin tarjeta de crédito y con acompañamiento de nuestro equipo para dejarlo funcionando.
Crear mi cuenta gratis