Mensajes salientes y plantillas

Resumen

Un agente solo puede enviar mensajes de WhatsApp de formato libre dentro de una conversación activa. Para contactar primero con un usuario —para notificaciones, reactivación o llamadas programadas— debes enviar una plantilla de mensaje aprobada por Meta. Esta página explica cómo crear plantillas, enviar mensajes y llamadas salientes y hacerlo a gran escala.

Crear plantillas en WhatsApp Manager

Las plantillas se crean y aprueban en WhatsApp Manager, no en ElevenLabs.

Al crear una plantilla:

• Elige una categoría: Utilidad para mensajes transaccionales, Marketing para mensajes promocionales o Autenticación para códigos de verificación. Meta aplica precios y límites de frecuencia distintos a cada categoría; consulta los precios de WhatsApp.
• Elige un formato de parámetros: posicional ({{1}}, {{2}}) o con nombre ({{customer_name}}). Los parámetros con nombre requieren un parameter_name en cada valor que envíes.
• Envíala para su aprobación. La aprobación suele tardar de minutos a horas. No se puede enviar una plantilla pendiente o rechazada: la API acepta la solicitud, pero Meta nunca entrega el mensaje.

Enviar un mensaje saliente

Enviar un mensaje de plantilla inicia una nueva conversación. El agente permanece en silencio hasta que el usuario responde: la propia plantilla es el primer mensaje y ningún temporizador de conversación comienza hasta que el usuario responde.

Panel

Python

TypeScript

cURL

Ve a la página de WhatsApp, selecciona tu cuenta y haz clic en el botón Saliente -> Mensaje. Selecciona un agente, proporciona un ID de usuario de WhatsApp y elige la plantilla de mensaje y sus parámetros:

Consulta la referencia de la API para ver el esquema completo de la solicitud.

Parámetros de plantilla

template_params es una lista de objetos component, uno por cada componente de la plantilla que tenga parámetros:

• {"type": "body", "parameters": [...]} para marcadores de posición del cuerpo
• {"type": "header", "parameters": [...]} para una cabecera parametrizada (texto, imagen, documento o ubicación)
• {"type": "button", "sub_type": ..., "index": ..., "parameters": [...]} para parámetros de botones

Cada entrada de parameters es un objeto de valor como {"type": "text", "text": "Daniele"}. Para plantillas con parámetros con nombre, incluye parameter_name en cada valor. Se rechaza omitir el contenedor del componente —por ejemplo, pasar {"type": "text", ...} directamente en template_params—.

Formato del número del destinatario

whatsapp_user_id solo debe contener dígitos: el código de país seguido del número, sin +, espacios ni guiones. Por ejemplo, 14155552671, no +1 (415) 555-2671.

Variables dinámicas, ramas y entornos

El campo conversation_initiation_client_data te permite establecer variables dinámicas para la conversación y fijarla a una rama de agente y un entorno específicos:

{
  "dynamic_variables": { "customer_name": "Daniele" },
  "branch_id": "agtbrch_8721kwarbs83e233mg1fzkaf9pg0",
  "environment": "staging"
}

Estos ajustes se mantienen durante la conversación: cuando el usuario responde, el agente se reanuda en la rama y el entorno solicitados. La rama y el entorno se validan primero; si alguno no existe, la solicitud falla con un error y no se envía ningún mensaje.

Este campo de solicitud permite que las conversaciones salientes reciban variables dinámicas; las conversaciones entrantes las reciben de un webhook de inicio de conversación en su lugar. Consulta el contexto de inicialización.

Después de enviar

Una solicitud correcta devuelve un conversation_id y la conversación aparece en tu historial con la plantilla procesada como primer mensaje. El agente no se ejecuta hasta que el usuario responde. El envío de la plantilla no inicia ni el temporizador de duración máxima ni el de inactividad; ambos comienzan cuando se reanuda la conversación. Una respuesta 200 significa que ElevenLabs aceptó la solicitud, pero Meta aún puede rechazar la entrega después. Si el mensaje nunca llega, consulta Resolución de problemas.

Programar una llamada saliente

Las llamadas salientes de WhatsApp requieren el permiso del usuario; consulta los permisos de llamadas de usuario. Crea una plantilla de mensaje con un componente de solicitud de permiso de llamada en WhatsApp Manager. Cuando programas una llamada, ElevenLabs comprueba el estado del permiso:

• Permiso ya concedido: la llamada se realiza inmediatamente.
• Permiso aún no solicitado: se envía la plantilla de solicitud de permiso y la llamada se realiza en cuanto el usuario aprueba.
• Permiso rechazado: la conversación se registra como fallida con el motivo User declined the call permission request.

Panel

Python

TypeScript

cURL

Ve a la página de WhatsApp, selecciona tu cuenta y haz clic en el botón Saliente -> Llamada. Selecciona un agente, proporciona un ID de usuario de WhatsApp y elige la plantilla de solicitud de permiso de llamada:

Consulta la referencia de la API para ver el esquema completo de la solicitud. Como ocurre con los mensajes salientes, conversation_initiation_client_data establece variables dinámicas y fija la conversación a una rama y un entorno, y una rama o un entorno desconocidos se rechazan antes de programar la llamada.

Campañas y procesamiento por lotes

Para llamar a muchos usuarios, utiliza llamadas por lotes con whatsapp_params: proporciona el ID de número de teléfono y la plantilla de solicitud de permiso de llamada una vez, y un whatsapp_user_id por destinatario.

Aún no hay una ruta de API nativa por lotes para los mensajes salientes. Para campañas con plantillas, llama a la ruta de API de mensajes salientes una vez por destinatario y respeta los límites de mensajería de Meta para tu número; consulta los límites de mensajería.