> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # 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](https://business.facebook.com/latest/whatsapp_manager/message_templates), 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing). * 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. > **Note** > > Meta limita la cantidad de [plantillas de marketing ](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/per-user-limits) > que puede recibir un mismo usuario durante un periodo determinado. Si una plantilla de marketing no se entrega sin avisar, > este límite es una causa habitual (error 131049 de Meta). ## 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 Ve a la [página de WhatsApp](https://elevenlabs.io/app/agents/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: ![Cuadro de diálogo de mensaje saliente de WhatsApp](/docs/_fern-img/13913c2ccc1d92cb59e7332b6fdb4a8c8c64760a334d1a311fa2007831eeb986.webp) #### Python ```python from elevenlabs import ElevenLabs elevenlabs = ElevenLabs() elevenlabs.conversational_ai.whatsapp.outbound_message( whatsapp_phone_number_id="524029457612345", whatsapp_user_id="12213231492", template_name="welcome", template_language_code="en", template_params=[ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "name", "text": "Daniele", } ], } ], agent_id="agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", conversation_initiation_client_data={ "dynamic_variables": {"customer_name": "Daniele"}, }, ) ``` #### TypeScript ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.whatsapp.outboundMessage({ whatsappPhoneNumberId: "524029457612345", whatsappUserId: "12213231492", templateName: "welcome", templateLanguageCode: "en", templateParams: [ { type: "body", parameters: [ { type: "text", parameterName: "name", text: "Daniele", }, ], }, ], agentId: "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", conversationInitiationClientData: { dynamicVariables: { customer_name: "Daniele" }, }, }); ``` #### cURL ```bash curl -X POST https://api.elevenlabs.io/v1/convai/whatsapp/outbound-message \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "whatsapp_phone_number_id": "524029457612345", "whatsapp_user_id": "12213231492", "template_name": "welcome", "template_language_code": "en", "template_params": [ { "type": "body", "parameters": [ {"type": "text", "parameter_name": "name", "text": "Daniele"} ] } ], "agent_id": "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", "conversation_initiation_client_data": { "dynamic_variables": {"customer_name": "Daniele"} } }' ``` Consulta la [referencia de la API](/docs/es/api-reference/whats-app/outbound-message) para ver el esquema completo de la solicitud. > **Tip** > > Un asistente de IA puede adaptar estos ejemplos a tu plantilla. Indícale la documentación de ElevenLabs > [llms.txt](/docs/es/llms.txt) (o el [llms-full.txt](/docs/es/llms-full.txt) más detallado), pega la definición de tu > plantilla de WhatsApp Manager y pide la solicitud: generará un comando cURL > o una llamada al SDK con los `template_params` correctos para tu plantilla. ### 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`. > **Warning** > > En algunos países, el ID que WhatsApp usa para una persona difiere de su número marcado; por > ejemplo, los números mexicanos llevan un `1` adicional después del código de país (`521...`) y los > brasileños pueden incluir u omitir un noveno dígito. Si el usuario ya te ha enviado mensajes, utiliza preferiblemente el > `whatsapp_user_id` de esa conversación anterior, que puedes copiar del historial de > conversaciones. ### Variables dinámicas, ramas y entornos El campo `conversation_initiation_client_data` te permite establecer [variables dinámicas](/docs/es/eleven-agents/customization/personalization/dynamic-variables) para la conversación y fijarla a una [rama de agente](/docs/es/eleven-agents/operate/versioning) y un [entorno](/docs/es/eleven-agents/integrate/environment-variables) específicos: ```json { "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](/docs/es/eleven-agents/whatsapp#initialization-context). > **Note** > > Los parámetros de plantilla solo rellenan el texto de la plantilla; no se exponen al agente. Si el > agente necesita un valor de la plantilla (como el nombre del cliente), vuelve a pasarlo en > `dynamic_variables`. ### 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](/docs/es/eleven-agents/whatsapp/troubleshooting). ## Programar una llamada saliente Las llamadas salientes de WhatsApp requieren el permiso del usuario; consulta los [permisos de llamadas de usuario](https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/user-call-permissions). Crea una plantilla de mensaje con un componente de **solicitud de permiso de llamada** en [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/message_templates). 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 Ve a la [página de WhatsApp](https://elevenlabs.io/app/agents/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: ![Cuadro de diálogo de llamada saliente de WhatsApp](/docs/_fern-img/1fcf7968f1651ce8e9474e770aad4dce4e702c69b4522f5bcc65efcd8bf8a3e4.webp) #### Python ```python from elevenlabs import ElevenLabs elevenlabs = ElevenLabs() elevenlabs.conversational_ai.whatsapp.outbound_call( whatsapp_phone_number_id="524029457612345", whatsapp_user_id="12213231492", whatsapp_call_permission_request_template_name="call_permission", whatsapp_call_permission_request_template_language_code="en", agent_id="agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", conversation_initiation_client_data={ "dynamic_variables": {"customer_name": "Daniele"}, }, ) ``` #### TypeScript ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.whatsapp.outboundCall({ whatsappPhoneNumberId: "524029457612345", whatsappUserId: "12213231492", whatsappCallPermissionRequestTemplateName: "call_permission", whatsappCallPermissionRequestTemplateLanguageCode: "en", agentId: "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", conversationInitiationClientData: { dynamicVariables: { customer_name: "Daniele" }, }, }); ``` #### cURL ```bash curl -X POST https://api.elevenlabs.io/v1/convai/whatsapp/outbound-call \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "whatsapp_phone_number_id": "524029457612345", "whatsapp_user_id": "12213231492", "whatsapp_call_permission_request_template_name": "call_permission", "whatsapp_call_permission_request_template_language_code": "en", "agent_id": "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", "conversation_initiation_client_data": { "dynamic_variables": {"customer_name": "Daniele"} } }' ``` Consulta la [referencia de la API](/docs/es/api-reference/whats-app/outbound-call) 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. > **Note** > > Meta cobra por las llamadas salientes y por las solicitudes de permiso de llamada enviadas fuera de una [ventana de atención al cliente ](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#customer-service-windows). > Añade un método de pago en WhatsApp Manager antes de programar llamadas. ## Campañas y procesamiento por lotes Para llamar a muchos usuarios, utiliza [llamadas por lotes](/docs/es/eleven-agents/phone-numbers/batch-calls) 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](/docs/es/api-reference/whats-app/outbound-message) 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/messaging-limits).