> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.
# WhatsApp (Texto + Voz)
> Conecta la API de WhatsApp Business Cloud para chat y llamadas de voz de la plataforma
WhatsApp es un canal del espacio de trabajo en **Settings → Channels → WhatsApp**, que abarca chat de texto, llamadas de voz de la plataforma y plantillas de mensajes.
| Modo | Disponibilidad |
| --------------- | ------------------------------------------------------------- |
| Chat de texto | Incluido con acceso de mensajería de WhatsApp |
| Llamadas de voz | Incluido con acceso de voz de WhatsApp |
| Plantillas | Usa la misma cuenta de WhatsApp Business que el chat de texto |
**Incorporación preferida (solo en el dominio de la plataforma, p. ej. app.famulor.io):** [Registro integrado de WhatsApp](/es/channels/whatsapp-embedded-signup) (Conectar con Meta). En dominios personalizados de marca blanca, los espacios de trabajo usan únicamente el **pegado manual de credenciales**.
Los **números de Marketplace** (Settings → Numbers) son **PSTN/SIP** para voz telefónica. Ese mismo E.164 se convierte en número de WhatsApp solo después de que Meta lo verifique (OTP). La configuración de tu troncal SIP es independiente de la API de WhatsApp Cloud. Los helpers de SMS de la plataforma son solo SMS/MMS, no se usan para WhatsApp.
## Requisitos previos
Tu plan incluye WhatsApp de texto y/o WhatsApp de voz.
## Interfaz del producto
1. **Connect with Meta** (Embedded Signup) — elige el asistente, un número de Marketplace opcional, helper de OTP para SMS de Marketplace
2. O pega las credenciales manualmente (token, secreto de la app, token de verificación, ID de número de teléfono, ID de WABA)
3. Interruptores: texto / voz entrante / voz saliente
4. **Edit** una conexión → WhatsApp Sender Details: los asistentes de chat y de voz saliente, **AI Auto-Responses**, **Keep conversations unread**, la disponibilidad para llamadas (**Enable calling on Meta**), y el Business Profile (**About**, Description, Business Address, Business Category, logo, banner, sitios web y correos/teléfonos de contacto). **Sync** envía el perfil a Meta — el logo se convierte en la foto de perfil de tu WhatsApp.
5. Selecciona **Templates** junto a un remitente para abrir su página de plantillas dedicada. **Sync with Meta** recorre todas las páginas de resultados, importa las plantillas creadas en WhatsApp Manager y actualiza el estado de aprobación. **Add template** te permite crear un borrador personalizado o explorar la biblioteca oficial de plantillas por idioma con una vista previa de teléfono en vivo. Las variables deben numerarse de forma contigua (`{{1}}`, `{{2}}`, `{{3}}`) y mapearse a una variable de sistema, un atributo de lead, una variable de asistente o una clave personalizada. Los botones de URL y de número de teléfono deben configurarse antes de añadir una plantilla de la biblioteca.
6. Haz una llamada de prueba de WhatsApp desde el panel de la conexión
Para la configuración manual, copia la URL de webhook que aparece después de conectar (los dominios personalizados verificados se gestionan automáticamente) y suscríbete a **messages**, **calls** y **message template status updates**. Para voz, activa también las llamadas en el número de teléfono en **Edit → Enable calling on Meta**.
## La ventana de 24 horas y las plantillas
Meta solo permite respuestas libres dentro de una **ventana de servicio de 24 horas** que se abre cada vez que un cliente te escribe:
* **Dentro de la ventana** — tu asistente puede enviar cualquier mensaje, sin necesidad de plantilla.
* **Fuera de la ventana** — debes enviar una **plantilla aprobada**. Esto se aplica a iniciar una conversación nueva, reactivar a un cliente tras 24 horas de inactividad, y cualquier mensaje de notificación o marketing que inicies tú.
Meta clasifica las plantillas en tres categorías, cada una con un listón de aprobación distinto:
| Categoría | Para qué se usa | Tiempo de aprobación típico |
| ------------------ | ---------------------------------------------------------------------------------------------------- | ----------------------------- |
| **Utility** | Confirmaciones de pedido/cita, recordatorios, notificaciones de cuenta — nunca contenido promocional | De minutos a unas pocas horas |
| **Marketing** | Ofertas, anuncios, reactivación | Horas, hasta 24 horas |
| **Authentication** | Contraseñas de un solo uso, códigos de inicio de sesión/verificación | De minutos a unas pocas horas |
**Add template** crea plantillas Utility y Marketing, y la biblioteca oficial que explora es Utility. Las plantillas Authentication se crean en WhatsApp Manager y **Sync with Meta** las recoge como cualquier otra plantilla.
Una **solicitud de permiso de llamada** no es una categoría aparte — es un componente de botón `CALL_PERMISSION_REQUEST` añadido a una plantilla Utility o Marketing para pedirle a un cliente permiso para llamarlo por voz de WhatsApp. La aprobación de ese componente suele ser inmediata.
Meta rechaza plantillas que mezclan categorías — por ejemplo, lenguaje promocional dentro de una plantilla Utility. Otras causas habituales de rechazo: valores de ejemplo vagos para las variables `{{1}}`/`{{2}}` (usa muestras realistas, no "test"), lenguaje agresivo o de urgencia, acortadores de URL en lugar de tu propio dominio, y contenido restringido (alcohol, apuestas, contenido adulto, político o categorías prohibidas).
Una vez aprobada, una plantilla no se puede editar — crea una nueva en su lugar. Ten a mano un par de plantillas de respaldo para los casos de uso de mucho tráfico, para que un solo rechazo o desactivación no bloquee tu difusión.
## Calidad de los mensajes y límites de envío
Meta controla cuánto puede enviar un remitente mediante dos cosas independientes.
**Quality rating** — **High**, **Medium** o **Low**, según cómo reacciona la gente a tus mensajes: bloqueos, reportes de spam y si responden o no. Baja tras una racha de bloqueos o reportes, y se recupera a medida que envías contenido relevante y solicitado.
**Messaging limit** — cuántos clientes puedes empezar a contactar en un periodo móvil de 24 horas. Un remitente nuevo empieza en el nivel más bajo (normalmente 250 clientes) y Meta lo va subiendo un escalón cada vez — 1,000, luego 10,000, luego 100,000, luego ilimitado — a medida que envías más con una calificación de calidad saludable. Una calificación que se mantiene en Low puede congelar el nivel o hacerlo bajar de nuevo.
Las respuestas dentro de una ventana de 24 horas abierta no cuentan para el límite. Ambos valores vienen directamente de Meta y se muestran por remitente en **Edit → WhatsApp Sender Details** como **Quality Rating** y **Messaging Limit**, así que construye un historial de conversaciones de calidad antes de escalar el volumen.
## Campañas
Elige **WhatsApp** en el asistente de campañas para enviar la plantilla de texto aprobada de un remitente activo una vez por lead. Los enlaces de plantilla guardados se rellenan de antemano y pueden anularse por campaña. Los mapeos pueden usar campos de contacto canónicos, variables de canal/sistema de solo lectura, atributos de lead, variables de asistente o una clave de lead personalizada.
**WhatsApp Call (Beta)** requiere Beta Features, acceso a voz de WhatsApp, un remitente listo para salientes y una plantilla de permiso de llamada aprobada seleccionada para ese remitente. Las llamadas iniciadas por la empresa también dependen de la disponibilidad de Meta, la región y el permiso explícito del cliente. Las solicitudes de permiso y su estado visible **Awaiting permission** se gestionan automáticamente. Una concesión de permiso reanuda el lead solo mientras su campaña está en ejecución.
Las campañas de voz pueden usar una plantilla de WhatsApp aprobada, SMS o correo electrónico como su único seguimiento tras los reintentos. Las llamadas exitosas, los contactos suprimidos y las campañas pausadas manualmente nunca generan ese seguimiento. Los envíos de plantilla usan los mismos créditos de mensajería que el WhatsApp de sesión.
## Webhook de confirmaciones de lectura
En **WhatsApp Sender Details** puedes configurar un endpoint HTTPS que reciba confirmaciones de entrega y lectura. Cada callback se firma con HMAC-SHA256 sobre el cuerpo raw exacto de la solicitud. La firma se envía como `X-Signature-256: sha256=`.
Se genera un secreto de firma cuando guardas por primera vez la URL del webhook. Los secretos existentes no se pueden recuperar. Usa **Rotate signing secret** en la configuración del remitente, `POST /api/v1/whatsapp/connectors/{id}/profile` con `action=rotate_read_receipts_webhook_secret`, o la herramienta MCP `rotate_whatsapp_read_receipts_webhook_secret`. El nuevo `signing_secret` se muestra o devuelve una sola vez, y el secreto anterior deja de funcionar de inmediato. Guarda el nuevo valor antes de salir de la respuesta y actualiza tu receptor antes de enviar una solicitud de prueba.
## Historial
Toda conversación de WhatsApp llega a [Historial](/es/monitoring/history) junto a tus otros canales:
* Las conversaciones de texto aparecen con el canal **WhatsApp**.
* Las llamadas de voz aparecen con el canal **WhatsApp voice**.
Las conversaciones de texto completadas se pueden seguir respondiendo a mano mientras la ventana de servicio de 24 horas de Meta sigue abierta. Tras una respuesta manual, Historial te pregunta si prefieres mantener la conversación como completada o reabrirla con respuestas automáticas de IA. Reabrirla inicia un temporizador de inactividad nuevo sin extender la ventana de 24 horas de Meta.
Cuando un cliente envía una foto, tu asistente describe automáticamente lo que contiene y puede responder a ese contenido como parte de la conversación. Las notas de voz entrantes se transcriben automáticamente y se gestionan igual que un mensaje escrito. Tanto el archivo multimedia como la descripción o transcripción resultante son visibles en la conversación.
## Facturación
* Texto: se factura por mensaje a la tarifa **Messaging (sent)** / **Messaging (received)** de tu espacio de trabajo — la misma tarifa que usan [los demás canales de mensajería](/es/channels/messaging#facturación). Las tarifas actuales están en la [página Usage](https://app.famulor.io/usage).
* Voz: la reserva/liquidación de créditos por minuto de voz ya existente (igual que en las llamadas de teléfono/SIP)
* Precios de conversación de Meta: método de pago del cliente en WhatsApp Manager (Tech Provider)
## Solución de problemas
El indicador de estado de un remitente muestra **PENDING**, **CONNECTED** o **ERROR**.
Confirma que completaste todo el popup de registro de Meta y que creaste (no reutilizaste) una cuenta de WhatsApp Business durante la configuración, y luego actualiza la página tras unos minutos. Si sigue pendiente después de 30+ minutos: contacta con soporte indicando el ID del remitente.
Abre **Edit** y lee el último error. Los problemas de credenciales se solucionan volviendo a ejecutar el flujo de conexión; una suspensión por política o calidad debe resolverse (normalmente por un comportamiento de envío parecido al spam) y se apela a través de Meta.
Las causas de rechazo anteriores son los motivos habituales; una plantilla desactivada suele ser una señal de calidad. Crea una versión mejorada y acota a quién se la envías.
Las plantillas Marketing pueden tardar más; crea una plantilla alternativa si necesitas enviar antes.
Envía a números en formato E.164, confirma que el destinatario tiene WhatsApp, comprueba que el remitente esté CONNECTED, y confirma que no has alcanzado tu límite de mensajería.
Estás fuera de la ventana de 24 horas del cliente; envía una plantilla aprobada en su lugar.
Confirma que hay un asistente asignado al remitente y que **AI Auto-Responses** está activado, y luego revisa Historial para ver el estado de error de la conversación.
Revisa qué enviaste justo antes de la caída, ajusta mejor tu segmentación y reduce el volumen; tanto la calificación como el nivel se recuperan a medida que envías mensajes más relevantes y de mayor calidad.
Permite los popups para el sitio, borra cookies/caché, o vuelve a intentarlo en otro navegador; luego vuelve a ejecutar el flujo de conexión desde el principio.
## API pública
* Conectores de mensajería: `GET/POST /api/v1/messaging-connectors` con `platform=whatsapp`
* Plantillas: `GET/POST /api/v1/whatsapp/templates`; usa `source=library`, `language`, `limit` y el cursor `paging.after` devuelto para explorar la biblioteca oficial. `parameter_bindings` mapea posiciones como `1` o `header.1` a claves de variable. Incluye `library_template_name` y `library_button_values` cuando un preset tiene botones de URL o de número de teléfono. `action=update` edita borradores localmente o envía cambios de componentes para una plantilla de proveedor existente. Los clientes de API y MCP pueden crear la misma plantilla de permiso de llamada proporcionando un componente `BODY` y `CALL_PERMISSION_REQUEST`.
* Voz saliente: `POST /api/v1/calls/whatsapp-outbound`
* Reanudación de IA en Historial: `POST /api/v1/history/actions` con `action=resume_ai`, `kind=messaging` y el ID de conversación
* Gestión de llamadas: `GET /api/v1/whatsapp/calling` lee el estado de disponibilidad (ajustes de llamada de Meta, suscripción de webhook, calificación de calidad) del número de negocio de un conector; `POST /api/v1/whatsapp/calling` ejecuta `enable_calling`, `resubscribe` o `ensure_voice`.
* Recursos del remitente: `POST`/`DELETE /api/v1/whatsapp/connectors/{id}/assets` sube o elimina un logo/banner del Business Profile (URL o base64).
* Perfil del remitente y confirmaciones de lectura: `GET`/`PATCH`/`POST /api/v1/whatsapp/connectors/{id}/profile` gestiona el perfil del remitente, prueba el callback firmado y rota su secreto de firma.
* Messenger Connect también puede manejarse íntegramente a través de la API: `POST /api/v1/messenger/facebook-login/pages` lista las páginas de Facebook que un token de acceso de usuario puede gestionar, antes de `POST /api/v1/messenger/facebook-login`.
* MCP: herramientas de plantillas de WhatsApp + `start_whatsapp_outbound_call` + `get_whatsapp_calling_status` + `manage_whatsapp_calling` + `rotate_whatsapp_read_receipts_webhook_secret` + `upload_whatsapp_sender_asset` / `delete_whatsapp_sender_asset` + `list_messenger_facebook_pages`
La sesión de **OTP capture** de números de Marketplace (el paso de verificación del número de teléfono que convierte un número comprado en uno compatible con WhatsApp) sigue siendo exclusiva del panel — es un flujo de telefonía interactivo sin equivalente en REST/MCP.
Consulta también [Configuración del Registro integrado](/es/channels/whatsapp-embedded-signup), [Canales de mensajería](/es/channels/messaging), [WhatsApp Voice](/es/telephony/whatsapp-voice).