{"id":711,"date":"2026-10-29T13:16:48","date_gmt":"2026-10-29T13:16:48","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/chatbot-ia-api-whatsapp\/"},"modified":"2026-10-29T13:17:07","modified_gmt":"2026-10-29T13:17:07","slug":"chatbot-ia-api-whatsapp","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/es\/chatbot-ia-api-whatsapp\/","title":{"rendered":"Chatbot con IA en la API oficial de WhatsApp: arquitectura y c\u00f3digo"},"content":{"rendered":"\n

Actualizado el 29\/10\/2026<\/em><\/p>\n\n\n\n

Para conectar un chatbot o agente de IA a WhatsApp por la API oficial, recibes cada mensaje por webhook, respondes 200 de inmediato, pones el evento en una cola y dejas que un worker arme el contexto, llame al modelo de lenguaje y env\u00ede la respuesta por la API. La respuesta libre del bot solo puede salir dentro de la ventana de 24 horas que abri\u00f3 el cliente, y la pol\u00edtica de Meta exige un camino claro hacia la atenci\u00f3n humana. Los t\u00e9rminos de Meta tambi\u00e9n proh\u00edben usar la plataforma para ofrecer asistentes de IA de uso general como producto principal, con excepciones en algunos pa\u00edses, entre ellos Brasil.<\/p>\n\n\n\n

Esta gu\u00eda muestra la arquitectura, las reglas que afectan al bot y un ejemplo funcional en Node.js con Vectalk, que transmite los mismos payloads y webhooks de Meta.<\/p>\n\n\n\n

Arquitectura: webhook, cola, LLM y respuesta<\/h2>\n\n\n\n
Cliente en WhatsApp\n      \u2502\n      \u25bc\nMeta \u2500\u2500POST\u2500\u2500\u25b6 Vectalk \u2500\u2500POST\u2500\u2500\u25b6 \/webhook (responde 200 y encola)\n                                     \u2502\n                                     \u25bc\n                                   Cola\n                                     \u2502\n                                     \u25bc\n                Worker: deduplica \u25b6 carga historial \u25b6 decide (bot o humano)\n                                     \u2502\n                         \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n                         \u25bc                       \u25bc\n                   LLM genera respuesta     Agente humano\n                         \u2502\n                         \u25bc\n             POST \/api\/messages (Vectalk) \u2500\u2500\u25b6 Meta \u2500\u2500\u25b6 Cliente<\/code><\/pre>\n\n\n\n
Cada pieza tiene una funci\u00f3n clara:<\/p>\n\n\n\n
Componente<\/th>Responsabilidad<\/th>Cuidado principal<\/th><\/tr><\/thead>
Webhook<\/td>Recibir el evento, validarlo y responder 200<\/td>No llamar al LLM dentro de la solicitud<\/td><\/tr>
Cola<\/td>Desacoplar la recepci\u00f3n del procesamiento<\/td>Garantizar un reintento si el worker se cae<\/td><\/tr>
Deduplicaci\u00f3n<\/td>Ignorar eventos repetidos por su ID wamid<\/code><\/td>Guardar los IDs procesados durante algunos d\u00edas<\/td><\/tr>
Historial<\/td>Armar el contexto de la conversaci\u00f3n por wa_id<\/code><\/td>Limitar el tama\u00f1o para controlar costo y latencia<\/td><\/tr>
Enrutador<\/td>Decidir si responde el bot o si la conversaci\u00f3n est\u00e1 con un humano<\/td>Respetar el estado de derivaci\u00f3n<\/td><\/tr>
LLM<\/td>Generar la respuesta dentro del alcance del negocio<\/td>Prompt con l\u00edmites claros y tiempo m\u00e1ximo de respuesta<\/td><\/tr>
Env\u00edo<\/td>Llamar a la API y guardar el ID del mensaje enviado<\/td>Manejar errores y revisar la ventana de 24 horas<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Por qu\u00e9 la cola es obligatoria<\/h3>\n\n\n\n
Un modelo de lenguaje puede tardar varios segundos en responder. Vectalk espera HTTP 200 en menos de 20 segundos y reenv\u00eda el evento si no lo recibe, seg\u00fan su documentaci\u00f3n de webhooks<\/a>. Si el endpoint espera al LLM, un pico de mensajes provoca reenv\u00edos, respuestas duplicadas y el doble de costo. Con la cola, el webhook solo guarda el evento y responde.<\/p>\n\n\n\n
El art\u00edculo sobre webhooks de la API de WhatsApp<\/a> cubre el formato de los eventos, la deduplicaci\u00f3n y el manejo de estados, y validar la firma del webhook<\/a> muestra c\u00f3mo revisar X-Hub-Signature-256<\/code> antes de encolar.<\/p>\n\n\n\n
Marcar como le\u00eddo y mostrar “escribiendo”<\/h3>\n\n\n\n
La Cloud API permite marcar el mensaje recibido como le\u00eddo y mostrar el indicador de escritura en la misma llamada. Seg\u00fan la documentaci\u00f3n de indicadores de escritura<\/a>, el indicador desaparece cuando respondes o despu\u00e9s de 25 segundos, lo que ocurra primero. Meta recomienda mostrarlo solo si realmente vas a responder.<\/p>\n\n\n\n
{\n  \"messaging_product\": \"whatsapp\",\n  \"status\": \"read\",\n  \"message_id\": \"wamid.HBgLNTUx...\",\n  \"typing_indicator\": { \"type\": \"text\" }\n}<\/code><\/pre>\n\n\n\n
En Vectalk, esta llamada va a POST \/api\/messages<\/code>, el mismo endpoint documentado para marcar como le\u00eddo.<\/p>\n\n\n\n
La ventana de 24 horas define lo que el bot puede enviar<\/h2>\n\n\n\n
Cuando el cliente env\u00eda un mensaje, se abre una ventana de atenci\u00f3n de 24 horas que se renueva con cada nuevo mensaje suyo. Dentro de ella, el bot puede responder con texto libre, multimedia y mensajes interactivos. Fuera de ella, solo con plantillas aprobadas (consulta la p\u00e1gina de Meta sobre mensajes de servicio y la ventana de atenci\u00f3n<\/a>).<\/p>\n\n\n\n
En la pr\u00e1ctica, eso cambia el dise\u00f1o del agente:<\/p>\n\n\n\n