> 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. # Mensagens de saída e modelos ## Visão geral Um agente só pode enviar mensagens do WhatsApp em formato livre dentro de uma conversa ativa. Para entrar em contato com um usuário primeiro — para notificações, reengajamento ou chamadas agendadas — você envia um **modelo de mensagem** aprovado pela Meta. Esta página aborda a criação de modelos, o envio de mensagens e chamadas proativas e a execução dessas ações em escala. ## Como criar modelos no WhatsApp Manager Os modelos são criados e aprovados no [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/message_templates), não na ElevenLabs. Ao criar um modelo: * Escolha uma categoria: **Utilidade** para mensagens transacionais, **Marketing** para mensagens promocionais ou **Autenticação** para códigos de verificação. A Meta cobra valores e aplica limites de taxa diferentes para cada categoria — consulte os [preços do WhatsApp](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing). * Escolha um formato de parâmetro: posicional (`{{1}}`, `{{2}}`) ou nomeado (`{{customer_name}}`). Parâmetros nomeados exigem um `parameter_name` em cada valor enviado. * Envie para aprovação. A aprovação geralmente leva de minutos a horas. Um modelo pendente ou rejeitado não pode ser enviado — a API aceita a solicitação, mas a Meta nunca entrega a mensagem. > **Note** > > A Meta limita a quantidade de [modelos de marketing](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/per-user-limits) > que um único usuário pode receber em determinado período. Se um modelo de marketing não for entregue silenciosamente, > esse limite é uma causa comum (erro 131049 da Meta). ## Como enviar uma mensagem proativa Enviar uma mensagem de modelo inicia uma nova conversa. O agente permanece em silêncio até que o usuário responda — o próprio modelo é a primeira mensagem, e nenhum temporizador da conversa é iniciado até que o usuário responda. #### Painel Acesse a [página do WhatsApp](https://elevenlabs.io/app/agents/whatsapp), selecione sua conta e clique no botão ***Proativo -> Mensagem***. Selecione um agente, informe um ID de usuário do WhatsApp e escolha o modelo de mensagem e seus parâmetros: ![Caixa de diálogo de mensagem proativa do 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"} } }' ``` Consulte a [referência da API](/docs/pt/api-reference/whats-app/outbound-message) para ver o esquema completo da solicitação. > **Tip** > > Um assistente de IA pode adaptar estes exemplos ao seu modelo. Direcione-o à documentação da ElevenLabs > [llms.txt](/docs/pt/llms.txt) (ou ao [llms-full.txt](/docs/pt/llms-full.txt), mais detalhado), cole a definição do seu > modelo do WhatsApp Manager e solicite a requisição — ele produzirá um comando cURL > ou uma chamada do SDK com os `template_params` corretos para seu modelo. ### Parâmetros do modelo `template_params` é uma lista de objetos de **componente**, um para cada componente do modelo que tem parâmetros: * `{"type": "body", "parameters": [...]}` para espaços reservados no corpo * `{"type": "header", "parameters": [...]}` para um cabeçalho parametrizado (texto, imagem, documento ou localização) * `{"type": "button", "sub_type": ..., "index": ..., "parameters": [...]}` para parâmetros de botão Cada entrada em `parameters` é um objeto de valor, como `{"type": "text", "text": "Daniele"}`. Para modelos com parâmetros nomeados, inclua `parameter_name` em cada valor. Omitir o wrapper do componente — por exemplo, passar `{"type": "text", ...}` diretamente em `template_params` — é rejeitado. ### Formato do número do destinatário `whatsapp_user_id` deve conter apenas dígitos: o código do país seguido do número, sem `+`, espaços ou hífens. Por exemplo, `14155552671`, e não `+1 (415) 555-2671`. > **Warning** > > Em alguns países, o ID que o WhatsApp usa para uma pessoa difere do número discado — por > exemplo, números mexicanos têm um `1` extra depois do código do país (`521...`), e números > brasileiros podem incluir ou omitir um nono dígito. Se o usuário já enviou uma mensagem a você, prefira o > `whatsapp_user_id` dessa conversa anterior, que pode ser copiado do histórico > de conversas. ### Variáveis dinâmicas, ramificações e ambientes O campo `conversation_initiation_client_data` permite definir [variáveis dinâmicas](/docs/pt/eleven-agents/customization/personalization/dynamic-variables) para a conversa e fixá-la em uma [ramificação de agente](/docs/pt/eleven-agents/operate/versioning) e um [ambiente](/docs/pt/eleven-agents/integrate/environment-variables) específicos: ```json { "dynamic_variables": { "customer_name": "Daniele" }, "branch_id": "agtbrch_8721kwarbs83e233mg1fzkaf9pg0", "environment": "staging" } ``` Essas configurações persistem durante a conversa: quando o usuário responde, o agente é retomado na ramificação e no ambiente solicitados. A ramificação e o ambiente são validados primeiro — se algum deles não existir, a solicitação falha com um erro e nenhuma mensagem é enviada. Esse campo de solicitação é como conversas proativas recebem variáveis dinâmicas; conversas recebidas as recebem por um webhook de início de conversa — consulte o [contexto de inicialização](/docs/pt/eleven-agents/whatsapp#initialization-context). > **Note** > > Os parâmetros do modelo preenchem apenas o texto do modelo — eles não ficam disponíveis para o agente. Se o > agente precisar de um valor do modelo (como o nome do cliente), passe-o novamente em > `dynamic_variables`. ### Depois do envio Uma solicitação bem-sucedida retorna um `conversation_id`, e a conversa aparece no seu histórico com o modelo renderizado como primeira mensagem. O agente não é executado até que o usuário responda. O envio do modelo não inicia nem o temporizador de duração máxima nem o temporizador de inatividade; ambos começam quando a conversa é retomada. Uma resposta `200` significa que a ElevenLabs aceitou a solicitação — a Meta ainda pode recusar a entrega depois. Se a mensagem nunca chegar, consulte [Solução de problemas](/docs/pt/eleven-agents/whatsapp/troubleshooting). ## Como agendar uma chamada proativa As chamadas proativas do WhatsApp exigem a permissão do usuário — consulte as [permissões de chamada do usuário](https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/user-call-permissions). Crie um modelo de mensagem com um componente de **solicitação de permissão de chamada** no [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/message_templates). Quando você agenda uma chamada, a ElevenLabs verifica o estado da permissão: * Permissão já concedida: a chamada é realizada imediatamente. * Permissão ainda não solicitada: o modelo de solicitação de permissão é enviado, e a chamada é realizada assim que o usuário aprovar. * Permissão recusada: a conversa é registrada como falha pelo motivo `User declined the call permission request.` #### Painel Acesse a [página do WhatsApp](https://elevenlabs.io/app/agents/whatsapp), selecione sua conta e clique no botão ***Proativo -> Chamada***. Selecione um agente, informe um ID de usuário do WhatsApp e escolha o modelo de solicitação de permissão de chamada: ![Caixa de diálogo de chamada proativa do 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"} } }' ``` Consulte a [referência da API](/docs/pt/api-reference/whats-app/outbound-call) para ver o esquema completo da solicitação. Assim como nas mensagens proativas, `conversation_initiation_client_data` define variáveis dinâmicas e fixa a conversa em uma ramificação e ambiente; uma ramificação ou ambiente desconhecido é rejeitado antes de a chamada ser agendada. > **Note** > > A Meta cobra por chamadas proativas e por solicitações de permissão de chamada enviadas fora de uma [Janela de Atendimento ao Cliente](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#customer-service-windows). > Adicione uma forma de pagamento no WhatsApp Manager antes de agendar chamadas. ## Campanhas e processamento em lote Para ligar para muitos usuários, use as [chamadas em lote](/docs/pt/eleven-agents/phone-numbers/batch-calls) com `whatsapp_params`: informe o ID do número de telefone e o modelo de solicitação de permissão de chamada uma vez, e um `whatsapp_user_id` para cada destinatário. Ainda não há um endpoint nativo em lote para mensagens proativas. Para campanhas com modelos, chame o [endpoint de mensagem proativa](/docs/pt/api-reference/whats-app/outbound-message) uma vez por destinatário e respeite os limites de mensagens da Meta para seu número — consulte os [limites de mensagens](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/messaging-limits).