Opciones de conexión
Existen dos caminos principales para conectarte a la WhatsApp Business API. La elección depende de tu capacidad técnica y de las herramientas que necesitas:
Cloud API (recomendado)
Meta hostea toda la infraestructura. Tú solo consumes la API REST. Sin servidores que mantener, actualizaciones automáticas, y el setup más rápido.
A través de BSP (partners como Cliengo)
El proveedor maneja la conexión con Meta y te da su propia API, generalmente más simple. Incluye herramientas como bandeja, chatbot y analytics.
Embedded Signup
Embedded Signup es el proceso más rápido para dar de alta un número en la API. En vez de llenar formularios y esperar aprobaciones, el usuario completa todo en un popup de Meta en menos de 5 minutos:
El usuario hace clic en "Conectar WhatsApp"
Tu aplicación muestra un botón que inicia el flujo de Embedded Signup de Meta.
Se abre un popup de Meta para verificar
El usuario se autentica con su cuenta de Facebook/Meta y autoriza la conexión.
Elige o crea un Business Manager
Si ya tiene uno, lo selecciona. Si no, crea uno nuevo en el momento.
Verifica el número de teléfono
Recibe un código por SMS o llamada para verificar la titularidad del número.
Recibe un token de acceso
Listo: tu aplicación recibe el token y puede empezar a enviar y recibir mensajes.
Webhooks
Los webhooks son la forma en que tu servidor recibe eventos de WhatsApp en tiempo real. Meta envía un POST a tu endpoint cada vez que ocurre algo relevante. Es fundamental configurarlos correctamente para no perder mensajes ni eventos:
- Mensajes entrantes: Texto, media, ubicación, contactos y mensajes interactivos que tus usuarios envían.
- Status de mensajes: Confirmaciones de enviado, entregado y leído para cada mensaje que envías.
- Errores de envío: Fallos por número inválido, rate limiting, template rechazado u otros problemas.
- Cambios en la cuenta: Actualizaciones de quality rating, cambios en el business profile, y alertas del sistema.
Envío de mensajes
La API soporta múltiples tipos de mensaje para cubrir distintos casos de uso. Cada tipo tiene su propio formato de payload y restricciones:
Texto plano
Mensajes de texto simples con formato básico (negrita, cursiva, tachado).
Media
Imágenes, videos, documentos PDF y mensajes de audio.
Interactivos
Botones de respuesta rápida, listas desplegables y CTAs con links.
Templates HSM
Plantillas pre-aprobadas para iniciar conversaciones fuera de la ventana de 24h.
Productos
Mensajes de producto único o multi-producto con catálogo integrado.
Reactions y replies
Reacciones con emoji y respuestas citadas a mensajes específicos.
Autenticación
La API usa tokens de acceso para autenticar las requests. Elegir el tipo correcto de token es clave para la seguridad y estabilidad de tu integración:
- System User Token (recomendado): Para integraciones server-to-server. No expira, está vinculado a tu Business Manager y tiene los permisos que tú defines. Es el estándar para producción.
- User Token: Para testing y desarrollo. Expira en pocas horas y está vinculado a tu usuario personal de Facebook. Nunca lo uses en producción.
- Business Integration Token: Para BSPs que manejan múltiples clientes. Permite acceder a las cuentas de los clientes con los permisos otorgados.
Mejores prácticas técnicas
Seguir estas prácticas te ahorra horas de debugging y problemas en producción:
- Usa tokens de System User: No de usuario personal. Los System User tokens no expiran y son más seguros.
- Implementa retry logic: Backoff exponencial (1s, 2s, 4s, 8s) con un máximo de 5 reintentos. Guarda el estado para evitar mensajes duplicados.
- Almacena los message IDs: Cada mensaje tiene un ID único. Guardalo para correlacionar con webhooks de status y para soporte.
- Valida los webhooks: Verifica la firma de Meta en cada webhook recibido para prevenir ataques de spoofing.
- Implementa rate limiting: Protege tu endpoint de webhooks contra picos de tráfico. Procesa los mensajes de forma asíncrona.
- Loguea todo: Guarda logs de requests, responses y errores. Son invaluables para debugging en producción.
