Nó OpenAI

O nó OpenAI (openai_chat) envia uma requisição de chat completion para modelos OpenAI (GPT-4o, GPT-5 Mini, etc.) pelo proxy de IA de workflows da WhatsWave. Use-o para classificação, resumo, extração estruturada e geração de texto dentro das Automações.

Figura 1: Nó OpenAI — API key, model, response format, prompt e temperature

O que faz

A cada execução, o engine do workflow:

1. Resolve placeholders {{variable}} dentro do JSON de Messages
2. Envia POST {{API_URL}}/workflows/ai/chat com provider openai, o modelo selecionado e as mensagens
3. Autentica com o integration token da empresa ({{api_token}})
4. Usa a AI API key selecionada no nó (ou a primeira chave OpenAI ativa da empresa)
5. Retorna a mensagem do assistente em data.choices[0].message.content mais o usage de tokens

Pré-requisitos

1. Integration token — gerado em Settings → API Keys (injetado como {{api_token}} automaticamente)
2. OpenAI API key — adicione em AI / LLM keys na mesma página de configurações e selecione no nó
3. Assinatura ativa ou cota de tokens disponível (quando não usar chave própria)

Guia de configuração

Passo 1 — Adicionar o nó

1. Abra Automações e edite seu workflow
2. Abra a paleta e selecione o grupo AI
3. Arraste OpenAI para o canvas
4. Conecte após o trigger ou um nó que prepare contexto (texto da mensagem, campos do CRM, etc.)

Passo 2 — Selecionar API key e model

Clique duas vezes no nó. No topo, use o seletor API key / Model:

Modelos disponíveis (template do nó):

Passo 3 — Escolher response format

Use JSON (object) quando a próxima etapa precisar de campos estruturados (ex.: { "score": 85, "tier": "hot" }).

Passo 4 — Escrever o prompt (Messages)

O campo Prompt edita o array Messages (JSON) subjacente. Por padrão:

[
  { "role": "user", "content": "Your instructions here..." }
]

Roles suportadas: system, user, assistant. Variáveis funcionam dentro de content:

Classify this lead message as hot, warm, or cold.
Message: {{trigger.body.message}}
Contact name: {{trigger.body.name}}

Para contexto multi-turno, mude para JSON bruto no editor (se exposto) ou monte as mensagens em um nó JavaScript e passe via variável.

Exemplo avançado — system + user:

[
  {
    "role": "system",
    "content": "You are a sales assistant. Reply ONLY with JSON: {\"tier\":\"hot|warm|cold\",\"score\":0-100}."
  },
  {
    "role": "user",
    "content": "Lead message: {{trigger.body.text}}"
  }
]

Passo 5 — Definir temperature

Passo 6 — Testar e inspecionar a saída

1. Salve o workflow
2. Execute Test ou clique em Play no nó
3. No log de execução, confira Prompt sent (mensagens resolvidas) e Output
4. Copie caminhos da aba References do nó

Campos de saída

A saída do nó segue o envelope HTTP padrão:

Exemplos (node ID openai_1):

{{openai_1.data.choices[0].message.content}}
{{input.data.choices[0].message.content}}
{{openai_1.data.usage.total_tokens}}

Em erro, a saída inclui error e opcionalmente http_error_detail.

Dicas e boas práticas

• Use JSON mode + system prompt quando nós seguintes precisarem de campos previsíveis
• Mantenha prompts explícitos — inclua formato de saída, valores permitidos e exemplos
• Prefira GPT-4o Mini para classificação em alto volume; GPT-4o para raciocínio mais difícil
• Adicione um nó Variable após OpenAI para armazenar tier ou score parseados da resposta
• Use sua própria API key em uso intenso para evitar limites de tokens do plano (is_own_key: true)
• Inspecione Prompt sent nos logs quando variáveis resolverem para strings vazias
• Combine com Condition — ramifique com base no tier extraído ou score numérico

FAQ

Por que recebo "Nenhuma chave de API ativa para openai"?

Nenhuma chave OpenAI está selecionada no nó e nenhuma está configurada para a empresa. Adicione uma chave em Settings → API Keys, selecione no nó e salve o workflow.

Por que {{trigger.body.message}} está vazio no prompt?

O nome do campo do webhook pode ser diferente (text, body, caminhos aninhados). Inspecione a saída do trigger no drawer de teste e use o caminho exato.

Por que o JSON mode retorna string em vez de objeto?

O modelo pode ter retornado JSON inválido ou cercado por markdown fences. Aperte o system prompt ou faça parse em um nó JavaScript com JSON.parse.

Este nó suporta function calling / tools?

Não — é um chat completion único. Para ferramentas e memória, use o nó AI Agent no grupo WhatsWave.

Os tokens contam contra meu plano?

Sim, a menos que is_own_key seja true (sua própria chave OpenAI). O uso aparece em data.usage e é rastreado para cobrança.

Posso usar um nome de modelo customizado fora do dropdown?

O template do nó lista modelos fixos. Para outros modelos, use o nó HTTP genérico contra a API da OpenAI ou solicite atualização do template.

Exemplos de uso

Exemplo 1 — Lead scoring

Nó OpenAI:

• Model: gpt-5.4-mini
• Response format: json_object
• Prompt: Rate this lead 0-100 and return JSON { "score": number, "reason": string }. Message: {{trigger.body.message}}

Nó Variable: score = parseado de {{input.data.choices[0].message.content.score}}

Condition: {{variables.score}} >= 80 → ramo hot

Exemplo 2 — Resumir ticket para resposta no WhatsApp

Prompt:

Summarize in 2 short sentences in Portuguese:
{{trigger.body.ticket_description}}

Send message: {{input.data.choices[0].message.content}}

Exemplo 3 — Extrair order ID de texto livre

Prompt:

Extract order_id from the text. Reply JSON only: {"order_id":"..."}
Text: {{trigger.body.message}}

Nó HTTP: buscar pedido usando {{variables.order_id}} definido a partir da saída da IA

Referências de API