Actions do Agent

Actions são tarefas que o agent pode executar durante uma conversa. O contrato de lançamento é estreito de propósito: só inclui actions conectadas no dashboard, filtradas pelo runtime do chat, persistidas e cobertas por testes.

Disponível hoje

O Simple Agent expõe três actions em runtime:

Action	O que faz	Limite atual
Captura de lead	Coleta campos de contato ou renderiza formulário inline	Encaminhamento opcional por webhook não é vendido como custom API
Escalação humana	Marca a conversa como escalada e abre/reabre ticket no Inbox	Notificação externa é best-effort
Agendamento Cal.com	Mostra botão de agendamento Cal.com validado	Link Cal.com apenas, sem OAuth de calendário

Shopify, links de pagamento Stripe, custom API/webhook, Zapier, HubSpot, Salesforce, Zendesk e Slack como actions de runtime são roadmap. Não trate esses itens como recursos disponíveis do produto ainda.

Captura de lead

Use Captura de lead quando o visitante pedir preço, orçamento, proposta, demo ou retorno do time.

Configuração:

{
  "type": "lead_capture",
  "name": "Capturar contato",
  "intentTriggers": ["preco", "orcamento", "demo", "contato"],
  "config": {
    "fields": [
      { "name": "email", "label": "Email", "type": "email", "required": true },
      { "name": "name", "label": "Nome", "type": "text", "required": false }
    ],
    "successMessage": "Obrigado. Vamos retornar em breve."
  }
}

Quando email ou nome são capturados, a conversa grava esses campos e a execução da action fica registrada.

Escalação humana

Use Escalação humana quando o usuário pedir uma pessoa, a resposta exigir revisão humana ou a confiança estiver baixa demais para uma resposta automática útil.

Configuração:

{
  "type": "escalate_human",
  "name": "Revisão humana",
  "intentTriggers": ["humano", "suporte", "atendente", "ajuda"],
  "config": {
    "notifyVia": "email",
    "destination": "suporte@empresa.com",
    "escalationMessage": "Uma pessoa do time vai revisar esta conversa."
  }
}

O que fica persistido:

• conversations.escalated_at
• ticket real no Inbox, aberto ou reaproveitado
• registro auditável em action_executions

Se a notificação externa falhar, o ticket do Inbox e o timestamp de escalação continuam sendo a fonte de verdade.

Agendamento Cal.com

Use Agendamento Cal.com quando o visitante pedir para marcar uma reunião.

Configuração:

{
  "type": "calcom",
  "name": "Agendar demo",
  "intentTriggers": ["agendar", "marcar", "reuniao", "horario"],
  "config": {
    "calcomUrl": "https://cal.com/seu-usuario/demo",
    "buttonLabel": "Agendar demo"
  }
}

Só URLs cal.com e app.cal.com são aceitas.

Rotas de API

Método	Path	Escopo
GET	/api/agents/:id/actions	Listar actions do agente
POST	/api/agents/:id/actions	Criar um dos três tipos de lançamento
PATCH	/api/agents/:id/actions/:actionId	Atualizar config ou estado enabled
DELETE	/api/agents/:id/actions/:actionId	Remover action
POST	/api/agents/:id/actions/:actionId/execute	Executar action manualmente

Todas as rotas exigem isolamento por tenant.