Native Actions

As Native Actions permitem enviar mensagens avançadas do WhatsApp durante a conversa — botões interativos, listas, imagens, áudio sintetizado, arquivos e muito mais.

Visão Geral dos Subtipos

`SEND_TEXT` — Texto Simples

Envia uma mensagem de texto. Suporta variáveis com $:

{
  "type": "NATIVE",
  "subtype": "SEND_TEXT",
  "text": "Olá $nome_cliente! Seu pedido #$numero_pedido foi confirmado."
}

Quando usar: Quando precisar enviar texto com formatação dinâmica fora do fluxo natural da resposta do LLM.

`SEND_BUTTON` — Botões Interativos

Envia uma mensagem com botões de resposta rápida (máx. 3 botões no WhatsApp):

{
  "type": "NATIVE",
  "subtype": "SEND_BUTTON",
  "text": "Como prefere prosseguir?",
  "buttons": ["Falar com humano", "Ver planos", "Encerrar"]
}

Modos de botão

Com AI_BUTTONS, você define a quantidade e o LLM cria os textos mais adequados para o momento da conversa.

`SEND_LIST` — Lista de Opções

Envia uma lista expandida de itens (mais de 3 opções, ou itens com descrição):

{
  "type": "NATIVE",
  "subtype": "SEND_LIST",
  "text": "Escolha o tipo de atendimento:",
  "items": [
    { "title": "Suporte Técnico", "description": "Problemas com o produto" },
    { "title": "Financeiro", "description": "Faturas e pagamentos" },
    { "title": "Comercial", "description": "Novos contratos e upgrades" },
    { "title": "Cancelamento", "description": "Encerrar assinatura" }
  ]
}

Modos de lista

`SEND_IMAGE` — Imagem

Envia uma imagem a partir de uma URL pública:

{
  "type": "NATIVE",
  "subtype": "SEND_IMAGE",
  "url": "https://cdn.empresa.com/produtos/$produto_id/foto.jpg",
  "caption": "Produto: $nome_produto — R$ $preco"
}

A URL e a legenda suportam substituição de variáveis $.

`SEND_AUDIO` — Áudio

Envia um arquivo de áudio pré-gravado (formato MP3, OGG, etc.):

{
  "type": "NATIVE",
  "subtype": "SEND_AUDIO",
  "url": "https://cdn.empresa.com/audios/boas-vindas.ogg"
}

`SEND_FILE` — Arquivo/Documento

Envia um documento para o usuário (PDF, DOCX, XLSX, etc.):

{
  "type": "NATIVE",
  "subtype": "SEND_FILE",
  "url": "https://cdn.empresa.com/docs/proposta_$empresa_id.pdf",
  "filename": "Proposta_Comercial_$empresa_nome.pdf"
}

Tanto a URL quanto o nome do arquivo suportam variáveis $.

`GEN_AUDIO` — Síntese de Voz (TTS)

Gera e envia uma mensagem de áudio a partir de texto usando Text-to-Speech:

{
  "type": "NATIVE",
  "subtype": "GEN_AUDIO",
  "text": "Olá $nome_cliente, sua consulta foi confirmada para $data_consulta às $hora_consulta. Até lá!"
}

O texto suporta variáveis $. O áudio é gerado em tempo real e enviado como mensagem de voz.

Quando usar:

• Confirmações importantes que merecem destaque sonoro
• Usuários que preferem ouvir a ler
• Acessibilidade

`TRANSFER_ASSISTANT` — Transferir para Outro Assistente

Transfere a sessão do usuário para um assistente diferente, mantendo o histórico da conversa:

{
  "type": "NATIVE",
  "subtype": "TRANSFER_ASSISTANT",
  "assistantId": 42
}

Casos de uso:

• Transferir do assistente de triagem para o especialista de vendas
• Escalar para o assistente de suporte técnico avançado
• Roteamento por idioma (PT → EN)
• Handoff para atendimento humano via assistente copilot

O assistantId é o ID numérico do assistente de destino, encontrado em Configurações → Assistentes.

Interpolação de Variáveis em Native Actions

Nos campos de texto das Native Actions (text, caption, filename), use $ para inserir variáveis:

"text": "Olá $nome! Seu saldo é $saldo. Última atualização: $data_atualizacao"

Os valores vêm de:

1. Parâmetros do gatilho (args do function calling)
2. ClientData (dados enviados pela API)
3. Variáveis de sistema ($session.id, $company.id, $assistant.id)