WhatsApp Cloud API
el transporte
El WhatsApp real. El mensaje del cliente llega crudo: texto, foto, voz, PDF y el ctwa_clid de anuncios. La pregunta es quién es dueño de este número.
Documento técnico · arquitectura
Agente IA
El cerebro · tu integración
Un robot que atiende WhatsApp solo con IA. Nuestro cerebro es agnóstico al transporte: se conecta al CRM y a la integración que ustedes ya tienen. Solo necesitamos una puerta de entrada al mensaje y una de salida.
● Motor en producción
Ref: Servicare · +57 311 396 4169
Preparado para Clez
Punto de partida
Ustedes ya tienen su casa. Nosotros traemos el cerebro.
Clez no usa Kommo: tienen su propio módulo de CRM y su propia integración con Meta. Perfecto — nuestro sistema no impone plataforma. Kommo es solo la implementación con la que ya probamos todo esto de punta a punta (Servicare). Lo único que define cómo nos enchufamos es una pregunta: ¿pueden entregarnos el mensaje crudo, o nos dan un canal para espejar? (§ Cómo nos conectamos).
La composición
Las tres piezas.
Meta transporta, nuestro Worker piensa, y el CRM de ustedes es la sala de control. El cerebro se sienta en el medio, sin casarse con ninguna plataforma.
Cloudflare
cerebro + manos
Serverless en el edge. Razona con Gemini, responde por WhatsApp y sincroniza con el CRM. Aquí vive «la automatización», y es lo único que ponemos nosotros.
Su CRM + inbox
la sala de control
El módulo propio de Clez. Sus agentes ven la conversación, cambian de etapa y retoman el chat. Sigue siendo su fuente de verdad; nosotros solo agregamos el cerebro.
La decisión · lo que hay que confirmar mañana
Cómo nos conectamos: dos modos.
Todo depende de quién es dueño del número de WhatsApp y de qué puede exponernos la plataforma de Clez. Son dos caminos, y solo necesitamos saber cuál aplica.
▲ Las dos preguntas para Clez: (1) ¿Son BSP y pueden pasarnos una API que entregue el payload crudo del mensaje de WhatsApp? — (2) Si no, ¿pueden entregarnos un canal personalizado para que nosotros espejemos hacia su CRM?
Modo 1 · ideal — Clez nos da la entrada
Payload crudo por API
Si Clez es BSP / dueño de la integración y puede exponernos un webhook o API que nos entregue el mensaje crudo (texto y media), nuestro Worker es el cerebro completo: multimodal intacto (OCR de fotos, notas de voz) y devolvemos la respuesta por su API de envío. Su CRM sigue mandando; nosotros solo agregamos IA.
→ El mejor escenario. Necesitamos: webhook con el payload + endpoint de envío.
Modo 2 · fallback — nosotros espejamos
Canal personalizado para espejar
Si no pueden entregarnos el payload crudo, entonces nosotros somos dueños del número (WABA propio) y corremos todo el cerebro. Clez nos entrega un canal personalizado (endpoint de entrada/salida hacia su inbox) y nosotros espejamos la conversación hacia su CRM y traemos de vuelta las respuestas de sus agentes.
→ Es exactamente lo que ya probamos con Kommo (su «canal de chat» + amojo).
Solve · el recorrido
Un mensaje, de punta a punta.
Así corre hoy en producción (Servicare, sobre Kommo). Para Clez el diagrama es idéntico — solo cambia la caja de la derecha por su CRM. Todo el ciclo ocurre en menos de 8 segundos.
Cliente
Escribe por WhatsApp
Texto · foto de comparendo · nota de voz · PDF
webhook / API con el payload crudo↓
Meta Cloud API
Entrega el mensaje crudo
multimodal + ctwa_clid intactos↓
Cloudflare Worker — instancia Clez
El cerebro IA (lo que ponemos nosotros)
1 · normaliza → 2 · resuelve el DO → 3 · lee la etapa (¿bot o humano?) → 4 · Gemini responde → 5 · envía por WhatsApp → 6 · espeja + actualiza el CRM
DO Conversation
Gemini 3 Flash
Stage-gating
AgendaBook
Alarmas · nudge 23h
↕Canal de mensajería
espeja la conversación
espeja la conversación
↕API del CRM
mueve etapa · tarea · nota
mueve etapa · tarea · nota
CRM de Clez — inbox de agentes
Sus agentes ven todo y toman el control
El agente responde → nos llega → el Worker lo relaya a WhatsApp. Mueve la etapa a «Atiende humano» → el bot se calla.
Coagula · el motor
El Worker por dentro.
El truco de escala es el Durable Object: cada cliente tiene su propio objeto con memoria persistente. Miles de conversaciones = miles de objetos aislados, cada uno con su estado. Esto no cambia según el CRM.
- Entrada.
El mensaje entra por
/webhook(Meta directo, o la API de Clez). El Worker responde 200 en <2s (o reintentan) y hace fire-and-forget hacia el DO de esa conversación (idFromName(teléfono)). - Batching con una sola alarma.
El DO acumula los mensajes ~8s y procesa el lote de una: si el cliente manda 3 mensajes seguidos, el bot responde una vez coherente, no tres. Esa misma alarma está multiplexada: también dispara el «nudge» de retoma a las 23h.
- Stage-gating (el interruptor).
Antes de contestar, lee la etapa del lead en el CRM (cacheada ~30s). Si está en Atiende humano → se calla y solo espeja. Si está en la etapa bot → procede.
- Slot-filling + multimodal.
Extrae datos del cliente (nombre, teléfono, producto) de texto y notas de voz. Si llega una foto, Gemini hace OCR y saca los datos. Todo queda en el estado del DO. Esto solo funciona si recibimos el payload crudo (Modo 1 o número propio).
- Gemini 3 Flash genera la respuesta.
Con el prompt del turno = persona + FAQ + datos conocidos + fotos disponibles. Voz y texto nativos, ~$0.02–0.03 por conversación.
- Señales de control.
Gemini emite marcas invisibles que el Worker parsea y limpia antes de enviar: [[GANADA]] mueve el lead a «Ganado» + crea tarea; [[HUMANO]] hace handoff; [[FOTOS]] envía imágenes del catálogo.
- Salida + espejo.
Envía por WhatsApp y, en paralelo, espeja entrante y saliente al CRM. El espejo es fail-open: si el CRM falla, el cliente igual recibe respuesta — el bot nunca se traba por la copia.
El acople
Siempre necesitamos dos puertas.
No importa la plataforma: nuestro cerebro solo pide una puerta para los mensajes y otra para los datos del CRM. Así lo resolvimos con Kommo — sirve de plantilla de lo que pediríamos a Clez.
Puerta 1 — Mensajería entrada + salida del chat
Técnico
Un canal de mensajería de entrada/salida. En Kommo es la Chats API «amojo»: connect → create-chat → import messages, firmando cada request con X-Signature = HMAC-SHA1(channel_secret, …). En Clez sería su API equivalente (webhook de entrada + endpoint de envío).
Sencillo
Por aquí entran y salen los mensajes. O nos dan el mensaje crudo (mejor), o nos dan un canal para espejar. Con un sello de firma para que confíen que somos nosotros.
Puerta 2 — Datos del CRM etapa · tarea · nota · contacto
Técnico
Una API REST para operar la ficha. En Kommo es la REST v4 con Authorization: Bearer {token}: PATCH /leads/{id} (etapa), POST /tasks, POST /notes. En Clez sería su API de CRM propia — leer etapa (para el gating) y escribir tarea/nota.
Sencillo
Por aquí movemos la ficha del cliente: cambiarlo de etapa, crear tarea, dejar nota. Los datos del negocio, no los mensajes.
Las llaves · ejemplo Kommo
Cómo se protege cada puerta.
Así funciona la seguridad en nuestra referencia (Kommo). Es el patrón estándar que replicaríamos con la API de Clez. Firma cuando el canal es de mensajería; Bearer cuando son operaciones sobre datos.
| Puerta | Cómo se autentica | El secreto… |
|---|---|---|
| Mensajería (amojo) | Firma HMAC-SHA1 por request con el channel_secret | nunca viaja — solo viaja la firma que resulta de él |
| CRM (REST v4) | Authorization: Bearer {long-lived token} (un JWT) | viaja entero en cada request → HTTPS obligatorio |
| OAuth2 | access_token de 24h + refresh_token | rota cada 24h |
Coexistencia
El interruptor bot ⇄ humano.
Sin comandos raros ni código: el control es la etapa del embudo en el CRM de ustedes.
Técnico
El stage-gating lee la etapa real del lead. La etapa Atiende humano pone el DO en paused; el bot deja de responder pero sigue espejando entrantes. Volver a la etapa bot lo reactiva.
Sencillo
Para apagar el robot en un chat, el agente mueve la tarjeta a «Atiende humano». El robot se calla al instante pero sigue mostrándole todo. Cuando termina, la devuelve y el robot retoma.
Aurum · lo medible
Números, límites y seguridad.
| Tema | Dato |
|---|---|
| Costo por conversación | ~$0.02–0.03 USD (Gemini 3 Flash). Respuestas dentro de 24h en WhatsApp = gratis; solo se pagan templates fuera de ventana. |
| Latencia | Respuesta al cliente en <8 s, con memoria de contexto. |
| Seguridad | Cada request va firmado (HMAC-SHA1) o con Bearer. El webhook de entrada se verifica. Nada entra sin credencial. |
| Multimodal | Depende del Modo 1 (payload crudo) o de que el número sea propio. Sin acceso al mensaje crudo, no hay OCR ni voz. |
| Aislamiento | Cada cliente = instancia/deployment separado (DOs y secrets propios). Las conversaciones no se mezclan. |
| Lo que necesitamos de Clez | Definir el modo (1 o 2) y entregar: el webhook/API del mensaje, el endpoint de envío, y la API del CRM (leer etapa + escribir tarea/nota) con sus credenciales. |
Anticipando
Lo que preguntará el fundador.
¿Nos obligan a cambiar de CRM o de plataforma?
No. Nuestro cerebro es agnóstico al transporte: se conecta a su CRM y su integración actuales. Kommo es solo donde ya lo probamos; a ustedes nos acoplamos por API. Ustedes no migran nada.
¿Qué necesitan exactamente de nuestra integración?
Idealmente (Modo 1): que como BSP nos pasen una API/webhook con el payload crudo del mensaje de WhatsApp + un endpoint para enviar la respuesta. Si eso no es posible (Modo 2): un canal personalizado para que nosotros —con nuestro número— espejemos la conversación hacia su CRM.
¿Por qué es tan importante el «payload crudo»?
Porque ahí vienen las fotos y las notas de voz. Sin acceso al mensaje crudo, el bot no puede leer imágenes ni oír audios (adiós OCR y multimodal). Muchas plataformas cerradas no exponen la media entrante — por eso es la primera pregunta.
¿Qué pasa si su CRM se cae un momento?
El cliente igual recibe respuesta. El espejo al CRM es
fail-open: envuelto en try/catch, un fallo de copia nunca rompe el flujo de WhatsApp. Cuando el CRM vuelve, se reanuda el espejo.¿El bot y un agente pueden pisarse en el mismo chat?
No. Mientras la tarjeta esté en «Atiende humano», el bot está en
paused y solo escucha. El agente tiene control exclusivo hasta que devuelve la tarjeta a la etapa del bot.Quod est superius est sicut quod inferius. El bot abajo, el humano arriba — un mismo hilo, coherente.