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, 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.
• 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.

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

Python

TypeScript

cURL

Acesse a página do 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:

Consulte a referência da API para ver o esquema completo da solicitação.

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.

Variáveis dinâmicas, ramificações e ambientes

O campo conversation_initiation_client_data permite definir variáveis dinâmicas para a conversa e fixá-la em uma ramificação de agente e um ambiente específicos:

{
  "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.

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.

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. Crie um modelo de mensagem com um componente de solicitação de permissão de chamada no WhatsApp Manager. 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

Python

TypeScript

cURL

Acesse a página do 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:

Consulte a referência da API 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.

Campanhas e processamento em lote

Para ligar para muitos usuários, use as chamadas em lote 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 uma vez por destinatário e respeite os limites de mensagens da Meta para seu número — consulte os limites de mensagens.