Webhook

A integração de Webhook permite que o assistente faça requisições HTTP para qualquer API externa durante a conversa. É a integração mais flexível da plataforma.

Configuração Básica

json

{
  "type": "WEBHOOK",
  "url": "https://api.seusite.com/endpoint",
  "method": "POST",
  "headers": [
    { "key": "Authorization", "value": "Bearer meu_token" },
    { "key": "Content-Type", "value": "application/json" }
  ],
  "body": {
    "campo": "valor"
  },
  "responseDirective": "Se o status for 'success', confirme ao usuário. Se for 'error', peça para tentar novamente."
}

Métodos HTTP suportados

GET · POST · PUT · DELETE

Variáveis Disponíveis

Use $nomeDaVariavel em URLs, headers e body. As variáveis são substituídas automaticamente antes da requisição.

Variáveis de Sistema

Variável	Valor
`$session.id`	UUID único da sessão
`$company.id`	ID da empresa na plataforma
`$assistant.id`	ID do assistente configurado

Variáveis de ClientData

Qualquer chave enviada via client_data ao criar ou atualizar a sessão:

bash

# Sessão com dados do cliente
curl -X PUT /session/{id} \
  -F 'client_data={"usuario_id":"usr_999","plano":"enterprise"}'

No webhook: $usuario_id, $plano

Variáveis de Argumentos do Trigger

Parâmetros que o LLM extraiu da conversa (definidos no JSON Schema do gatilho):

json

// Trigger definido com parâmetro "numero_pedido"
// No webhook: $numero_pedido
{
  "url": "https://api.loja.com/pedidos/$numero_pedido/status",
  "method": "GET"
}

Variáveis de Imagens

Quando o usuário envia imagens na conversa:

Variável	Valor
`$images[0]`	URL da 1ª imagem
`$images[1]`	URL da 2ª imagem
`$images`	JSON array com todas as URLs

Exemplos Práticos

Consultar status de pedido

json

{
  "url": "https://erp.empresa.com/api/pedidos/$numero_pedido",
  "method": "GET",
  "headers": [
    { "key": "Authorization", "value": "Bearer $token_erp" }
  ],
  "responseDirective": "Informe o status do pedido ao cliente de forma clara. Se o status for 'entregue', parabenize. Se for 'em_transito', informe a previsão."
}

Criar ticket de suporte

json

{
  "url": "https://helpdesk.empresa.com/api/tickets",
  "method": "POST",
  "headers": [
    { "key": "Authorization", "value": "Bearer $api_key_helpdesk" },
    { "key": "X-Session-ID", "value": "$session.id" }
  ],
  "body": {
    "titulo": "$titulo_problema",
    "descricao": "$descricao_problema",
    "prioridade": "$prioridade",
    "cliente": {
      "nome": "$nome_cliente",
      "email": "$email_cliente"
    },
    "origem": {
      "canal": "whatsapp",
      "sessao": "$session.id",
      "empresa": "$company.id"
    }
  },
  "responseDirective": "Confirme o número do ticket criado para o cliente e diga que nossa equipe entrará em contato em até 24h."
}

Análise de imagem enviada pelo usuário

json

{
  "url": "https://api.vision.empresa.com/analyze",
  "method": "POST",
  "headers": [
    { "key": "Authorization", "value": "Bearer $vision_api_key" }
  ],
  "body": {
    "image_url": "$images[0]",
    "all_images": $images,
    "session_ref": "$session.id"
  },
  "responseDirective": "Descreva o que foi identificado na imagem de forma útil para o usuário."
}

`responseDirective`

O responseDirective é uma instrução para o LLM sobre como interpretar e usar a resposta do webhook ao formular a resposta ao usuário.

json

"responseDirective": "Se o campo 'disponivel' for true, ofereça os horários da lista 'horarios'. Se for false, informe que não há disponibilidade e pergunte se deseja ser notificado."

Quando não especificado, o LLM usa a resposta do webhook como contexto adicional e decide livremente o que comunicar.

Se InterpretResponse estiver como false no gatilho, o responseDirective é ignorado.

Atualizando ClientData via Resposta

Seu webhook pode retornar dados que ficam disponíveis na sessão para chamadas subsequentes:

json

// Retorno do seu webhook
{
  "status": "success",
  "paciente_id": "pac_12345",
  "session": {
    "client_data": {
      "paciente_id": "pac_12345",
      "nome_paciente": "Ana Souza",
      "ultima_consulta": "2025-02-15"
    }
  }
}

Os valores de session.client_data são automaticamente mesclados à sessão. $paciente_id ficará disponível em webhooks seguintes.

Comportamento de Substituição de Variáveis

Ordenação por comprimento

As variáveis são substituídas do nome mais longo para o mais curto. Isso evita substituições parciais:

Variáveis: $session_id (10 chars) e $session (7 chars)
Texto: "Sessão: $session_id — empresa: $session.company"

Correto: substitui $session_id primeiro (nome mais longo)
Errado seria: substitui $session primeiro, gerando "$session_id" parcial

Encoding automático

Contexto	Tratamento
URL path (`/pedidos/$id`)	URL-encoded (`%20`, `%2F`, etc.)
URL query params (`?q=$busca`)	URL-encoded
Headers	Substituição literal
Body JSON (strings)	JSON-escaped (`\n`, `\"`, etc.)

Debug e Erros

O resultado de cada chamada de webhook é registrado nos logs da sessão com:

Status HTTP da resposta
Body retornado
Variáveis utilizadas
Tempo de execução

Os logs ficam disponíveis em Painel → Conversas → Sessão → Logs.