WhatsApp API con Python: Tutorial de Integración [2026]

Si eres desarrollador y quieres conectar tu aplicación directamente con WhatsApp, la combinación de WhatsApp Cloud API + Python es el camino más directo. En este tutorial vas a entender cómo enviar mensajes, recibir notificaciones mediante webhooks, gestionar templates y construir un chatbot básico -- todo a través de la REST API oficial de Meta. No es copiar y pegar código: es entender la arquitectura para que puedas adaptarla a tu caso de uso. Necesitarás Python 3.9+, una cuenta de Meta Business verificada y acceso a la WhatsApp Business API. Si todavía no tienes claro qué es la API ni cómo encaja en el ecosistema, empieza por la guía completa de WhatsApp Business API.

Requisitos Previos

Antes de escribir una sola línea de código, necesitas tener preparado lo siguiente:

• Python 3.9 o superior instalado en tu entorno de desarrollo.
• Una cuenta de Meta Business verificada. Sin verificación empresarial no tendrás acceso a producción.
• Acceso a la WhatsApp Cloud API a través del panel de Meta Developer, o bien a través de un BSP (Business Solution Provider) que te proporcione credenciales.
• Tu access token generado desde el dashboard de Meta Developer. Es el token temporal para pruebas; para producción necesitarás un token de sistema permanente con autenticación OAuth.
• Un número de teléfono registrado en la WhatsApp Business API. Puede ser el número de pruebas que Meta proporciona en el sandbox o tu número empresarial verificado.
• Librerías de Python: requests para llamadas HTTP síncronas, flask para montar el servidor de webhook, y python-dotenv para gestionar variables de entorno de forma segura. Si prefieres trabajar en async, sustituye requests por httpx y flask por FastAPI.

Si necesitas una guía paso a paso para obtener estas credenciales y configurar tu cuenta de Meta, consulta cómo configurar la WhatsApp Business API. Aquí asumimos que ya tienes todo listo.

Enviar Mensajes con la Cloud API

El envío de mensajes se reduce a una llamada POST contra la REST API de Meta. El endpoint es https://graph.facebook.com/v18.0/{phone_number_id}/messages. Necesitas dos cabeceras: Authorization con tu access token en formato Bearer y Content-Type como application/json.

Para enviar un mensaje de texto plano, el cuerpo de la petición en JSON incluye cuatro campos: messaging_product siempre como "whatsapp", to con el número del destinatario en formato internacional (por ejemplo, 34612345678), type como "text" y un objeto text con el campo body que contiene el contenido del mensaje.

Para enviar un template aprobado -- obligatorio cuando inicias la conversación sin que el usuario haya escrito primero -- cambias el type a "template" e incluyes un objeto con el nombre del template, el idioma y los componentes dinámicos (variables de cabecera, cuerpo y botones). Los templates permiten personalización masiva: un solo formato aprobado puede servir para miles de envíos diferentes inyectando variables en tiempo de ejecución.

La respuesta de la API devuelve un message_id que usarás para hacer seguimiento del estado de entrega. Si hay error, recibes un código específico: 131047 indica que el número no es válido, 131026 que el usuario no tiene WhatsApp, 130429 que has superado el rate limit. Gestionar estos errores correctamente es lo que separa una integración de pruebas de una de producción.

Sobre rendimiento: Meta establece un rate limit de 80 mensajes por segundo para el tier estándar y hasta 1.000 para cuentas con mayor volumen. Si necesitas envío masivo, implementa una cola con reintentos exponenciales. Para llamadas síncronas usa la librería requests; para alto volumen donde necesitas concurrencia sin bloqueo, httpx con async es la opción adecuada. Si quieres entender más sobre cómo fluyen los mensajes por la arquitectura, revisa cómo funciona la WhatsApp Business API.

Recibir Mensajes con Webhooks

Enviar mensajes es la mitad de la ecuación. La otra mitad es recibirlos, y para eso necesitas un servidor de webhook. Un webhook es un endpoint HTTP en tu servidor al que Meta envía notificaciones POST cada vez que ocurre un evento: un cliente te escribe, un mensaje se entrega, se lee o falla.

La configuración tiene dos fases. Primero, la verificación: cuando registras la URL de tu webhook en el panel de Meta, este envía una petición GET con un parámetro hub.verify_token que tú defines y un hub.challenge que debes devolver. Es un handshake para confirmar que el endpoint es tuyo. Con Flask o FastAPI montas esta ruta en minutos.

Segundo, la recepción de eventos: cada mensaje entrante llega como un POST con un payload JSON estructurado en entry[].changes[].value.messages[]. De cada mensaje extraes el número del remitente (from), el tipo (text, image, document, interactive, location) y el contenido. Un mensaje de texto trae el campo body; una imagen trae un id que debes descargar con otra llamada a la API.

Seguridad: Meta firma cada notificación con una cabecera X-Hub-Signature-256. Debes verificar esta firma usando el secret de tu aplicación para confirmar que la petición viene realmente de Meta y no de un atacante. En Python, esto se resuelve con hmac y hashlib comparando el hash SHA-256 del payload.

La regla de oro del webhook: responde con un HTTP 200 inmediatamente. Procesa la lógica de negocio de forma asíncrona -- en un hilo secundario, una tarea de Celery o una cola interna. Si tardas más de 20 segundos en responder, Meta considera que tu servidor ha fallado y reintenta, provocando mensajes duplicados y problemas de estado.

Crear un Chatbot Básico

Con el envío y la recepción funcionando, construir un chatbot es conectar ambos flujos con lógica intermedia. El patrón es el siguiente:

1. Recibes un mensaje a través del webhook.
2. Analizas la intención del usuario. En su versión más simple, coincidencia de palabras clave: si el mensaje contiene "pedido", consultas el estado del pedido; si contiene "horario", devuelves horarios. Para algo más sofisticado, integras un modelo de lenguaje como GPT-4o de OpenAI o Claude de Anthropic a través de su API, enviando el contexto de la conversación y recibiendo una respuesta generada.
3. Consultas tus datos internos: base de datos, CRM, sistema de pedidos, calendario.
4. Compones la respuesta y la envías de vuelta a través de la Cloud API.

Para un chatbot potenciado con IA, el flujo añade una llamada intermedia al modelo de lenguaje. Envías el historial de la conversación como contexto, recibes la respuesta generada, la formateas y la envías por WhatsApp. Esto convierte un chatbot de flujos rígidos en un agente IA conversacional capaz de entender lenguaje natural, manejar ambigüedad y resolver consultas complejas. Si quieres automatizar esta arquitectura con herramientas no-code, consulta cómo hacerlo con n8n y agentes IA.

Para producción real -- con gestión de memoria conversacional, herramientas conectadas, escalado a humanos y analítica -- una plataforma como GuruSup resuelve en minutos lo que desarrollar desde cero lleva semanas.

Limitaciones del Enfoque DIY

Construir la integración desde cero con Python es ideal para aprender y prototipar. Pero para producción implica mantener un servidor de webhook 24/7, gestionar errores y reintentos, almacenar estado de conversación, implementar analítica, construir bandeja multi-agente y diseñar escalado a humanos. Todo eso es código que tú mantienes.

Para conectores específicos, la aproximación directa tiene sentido. Para atención al cliente a escala, un proveedor BSP con plataforma completa ahorra meses de desarrollo.

Conclusión

Python + WhatsApp Cloud API te dan control total sobre el envío de mensajes, la recepción por webhook y la construcción de chatbots -- desde flujos simples hasta agentes IA avanzados. Es la base técnica sobre la que cualquier integración seria se construye. Para el panorama completo del ecosistema, vuelve a la guía de WhatsApp Business API.

GuruSup convierte toda esta arquitectura en una plataforma lista para producción: agentes IA en WhatsApp, integraciones con tu CRM, bandeja multi-agente y analítica. Sin montar servidores, sin gestionar webhooks. Empieza con GuruSup.