Message Sending Tool

A Message Sending Tool permite que um Agente envie mensagens de WhatsApp de saída para números de telefone específicos.

Use-a para alertas, resumos, transferências, lembretes e notificações operacionais. As mensagens são enviadas imediatamente quando o Agente decide usar a tool.

🔎 O que ela faz

Com a Message Sending, um Agente pode:

Enviar mensagens de texto comuns
Enviar templates aprovados de WhatsApp em conexões oficiais
Tentar texto primeiro e recorrer a um template quando a janela de 24 horas estiver fechada
Escolher o destino dinamicamente ou usar números predefinidos

⚙️ Como a tool funciona

O Agente decide usar a tool com base em sua descrição e instruções.

Em tempo de execução:

O Agente decide se uma mensagem deve ser enviada.
Ele determina o número de telefone de destino.
Ele usa o modo de envio configurado.
O Zaia envia a mensagem pela conexão selecionada.

📞 Regras de conexão do WhatsApp

WhatsApp (Official)

Conexões WhatsApp Official suportam três modos de envio:

Text
Template
Text with template fallback

Text

O Zaia envia uma mensagem comum.

Isso funciona quando o destinatário está dentro de uma janela ativa de 24 horas do WhatsApp.

Template

O Zaia envia diretamente um template de WhatsApp aprovado.

Use esse modo quando você precisar de uma mensagem de saída pré-aprovada.

Text with template fallback

O Zaia tenta enviar uma mensagem comum primeiro.

Se o WhatsApp rejeitar a mensagem porque a janela de 24 horas expirou, o Zaia envia o template configurado em vez disso.

⚠️ O fallback de template não é genérico. Ele só é acionado para o erro específico de janela do WhatsApp expirada.

WhatsApp (Waha)

Conexões Waha suportam apenas texto.

Templates e fallback de template não estão disponíveis no Waha.

📲 Números de telefone predefinidos vs. descoberta dinâmica

Números de telefone predefinidos

Quando ativado:

Você define um ou mais números de telefone
A tool envia apenas para esses números
Isso funciona bem para alertas internos e destinatários fixos

Descoberta dinâmica de número de telefone

Quando desativado:

O Agente determina o número de destino em tempo de execução
O número pode vir do contexto da conversa
Isso funciona bem para notificações sensíveis ao contexto

🧩 Comportamento de templates na tool

Quando a conexão selecionada é WhatsApp (Official), o Zaia lista apenas templates que estão:

Aprovados na Meta
Disponíveis para aquela conexão
Válidos para a conta de WhatsApp vinculada

O Zaia monta as entradas do template dinamicamente a partir do schema da Meta. Isso inclui:

Variáveis do Body
Variáveis do Header
Variáveis de Button
Entrada de imagem do header, quando exigida

Na tool, os campos do template podem ser preenchidos parcialmente. Valores ausentes podem ser completados durante a execução a partir do contexto, dos dados de execução ou da saída do LLM.

Se um valor já existir na configuração da tool, o Zaia o mantém. Se um valor estiver ausente, o Zaia pode mesclar variáveis extras no payload do template.

🖼️ Headers com imagem

Templates com header de imagem aceitam:

Uma URL pública
Um arquivo armazenado
Uma data URL

Antes de enviar, o Zaia converte a imagem para o formato aceito pela API do WhatsApp.

✍️ Definindo o conteúdo da mensagem

Para o modo text, o conteúdo é controlado por instruções de prompt.

Você pode:

Definir uma mensagem fixa
Instruir o Agente a gerar a mensagem dinamicamente

Para os modos template, o conteúdo vem do template de WhatsApp selecionado e de suas variáveis.

Exemplo de instrução

“Ao criar um ticket de suporte, envie uma mensagem de WhatsApp para 11 984444444 contendo:

Um resumo da conversa até o momento

O número de telefone do usuário como um link clicável no formato
https://wa.me/55{{user_phone}}“

Nesse caso, o Agente escreve o texto, injeta o contexto e envia a mensagem para o número selecionado.

✅ Validações e restrições

O Zaia valida os dados do template antes de enviar.

Isso inclui limites para campos como:

Texto do body
Texto do header
Valores de OTP
Sufixos de URL de botão

Os templates só funcionam quando a conexão oficial do WhatsApp está ativa e corretamente configurada. Se o template não puder ser resolvido ou validado pela Meta, o envio é bloqueado.

Para envio de mensagens de saída baseado em Workflow, veja Message Sending Node. Para os requisitos de conexão oficial, veja WhatsApp (Official).

📌 Padrão de uso recomendado

Use um número de telefone dedicado para notificações de saída sempre que possível.

Isso ajuda a:

Proteger a reputação do seu número principal
Controlar o volume de saída
Isolar o tráfego operacional das conversas ao vivo

🧠 Boas práticas

Seja explícito na descrição da tool para que o Agente saiba quando enviar
Use text para conversas ativas
Use template quando precisar de uma mensagem de saída aprovada
Use text with template fallback apenas quando existir um template de fallback válido
Evite tráfego de saída excessivo

✅ Resumo

A Tool Message Sending suporta tanto texto quanto templates aprovados de WhatsApp.

Com uma conexão WhatsApp Official, você pode enviar texto, enviar templates diretamente ou se recuperar de uma janela de 24 horas expirada com um fallback de template controlado.