Ações

Deixe o agente consultar e atualizar dados no seu sistema, com segurança e confirmação do usuário.

Ações são endpoints do seu sistema que o agente pode chamar durante uma conversa. Com elas, o agente deixa de responder só o que está no conhecimento e passa a resolver: "quais são minhas próximas consultas?", "remarca para sexta", "meu pagamento caiu?".

texto

Cliente → Agente Nevox → (precisa de dado) → POST na sua URL → sua resposta → Agente responde

A Nevox nunca recebe acesso ao seu banco de dados: ela só chama os endereços que você cadastrar, e o agente só vê o que esses endereços devolverem.

Onde valem: por enquanto, nas conversas pela API e no widget. WhatsApp, chat do site e SMS chegam numa próxima versão.

Cadastrar uma ação

POST /v1/agents/{agent_id}/actions · escopo actions:write

bash

curl https://api.nevox.ai/v1/agents/agt_8f2k1x/actions \
  -H "Authorization: Bearer $NEVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "proximas_consultas",
    "description": "Busca as próximas consultas agendadas do paciente. Use quando ele perguntar sobre consultas marcadas, horários ou o link da consulta.",
    "url": "https://api.suaempresa.com/nevox/proximas-consultas",
    "mode": "read",
    "parameters": {
      "type": "object",
      "properties": {
        "limite": { "type": "integer", "description": "Quantas consultas trazer", "default": 3 }
      }
    }
  }'

json

{
  "id": "act_51nb",
  "name": "proximas_consultas",
  "mode": "read",
  "requires_confirmation": false,
  "status": "active",
  "signing_secret": "whsec_act_...",
  "created_at": "2026-11-03T17:00:00Z"
}

O signing_secret aparece uma única vez. Use para validar que a chamada veio da Nevox.

Campo	Descrição
`name`	Só letras minúsculas, números e `_`. Único por agente.
`description`	O campo mais importante. É assim que o agente decide quando usar a ação. Escreva como explicaria para um atendente novo.
`url`	HTTPS obrigatório. Endereços internos ou privados são recusados.
`mode`	`read` (só consulta) ou `write` (altera algo no seu sistema)
`requires_confirmation`	Sempre `true` em `write`. O agente confirma com o usuário antes de chamar.
`parameters`	JSON Schema dos argumentos que o agente deve preencher
`requires_contact`	Padrão `true`: a ação só roda quando o contato está identificado (conversa aberta pela API com `contact`, ou widget com token de sessão). Sem contato, o agente diz que não consegue consultar por ali.
`timeout_ms`	Padrão 8.000, máximo 15.000

Outros endpoints: GET /v1/agents/{agent_id}/actions, PATCH .../actions/{id}, DELETE .../actions/{id}, POST .../actions/{id}/rotate-secret.

O que a Nevox envia para você

http

POST /nevox/proximas-consultas HTTP/1.1
Host: api.suaempresa.com
Content-Type: application/json
Nevox-Signature: t=1762182000,v1=5f2b0c...
Nevox-Environment: live
Nevox-Request-Id: req_8q1m

{
  "action": "proximas_consultas",
  "invocation_id": "inv_3k2l",
  "agent_id": "agt_8f2k1x",
  "conversation_id": "conv_7mk2p9",
  "contact": {
    "id": "ctc_4hq81",
    "external_id": "paciente_1042",
    "name": "Maria Souza",
    "language": "pt-BR"
  },
  "arguments": { "limite": 3 },
  "confirmed": false
}

O que você responde

Responda 200 com JSON em até 8 segundos:

json

{
  "result": {
    "consultas": [
      { "data": "2026-11-06T13:00:00Z", "medico": "Dra. Lima", "tipo": "Retorno" }
    ]
  },
  "message_for_agent": "Lembre o paciente de entrar 5 minutos antes."
}

Campo	Descrição
`result`	Qualquer JSON. O agente usa para montar a resposta. Até 20 KB.
`message_for_agent`	Opcional. Uma instrução extra para esta resposta.
`error`	Se algo deu errado do seu lado: `{ "code": "not_found", "message": "Paciente sem consultas" }`. O agente explica ao usuário sem expor detalhes técnicos.

Se a sua URL não responder a tempo ou devolver erro 5xx, o agente diz que não conseguiu consultar agora e oferece passar para um humano. Ações de read têm 1 nova tentativa; ações de write nunca são repetidas automaticamente.

Validar a assinatura

Toda chamada traz o cabeçalho Nevox-Signature. Recuse chamadas sem assinatura válida ou com mais de 5 minutos.

import crypto from "node:crypto";

export function assinaturaValida(rawBody, header, secret) {
  const partes = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(partes.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;

  const esperado = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(partes.v1));
}

Valide sempre sobre o corpo bruto da requisição, antes de converter para JSON.

Ações de escrita

Para mode: "write", o agente sempre confirma antes. A confirmação é conferida pela Nevox, não só pela IA: a chamada com "confirmed": true só acontece se o usuário respondeu depois de o agente perguntar, e com exatamente os mesmos argumentos.

Agente: Confirmo a remarcação da sua consulta de quinta (06/11, 10h) para sexta (07/11, 10h) com a Dra. Lima? Maria: Sim (a Nevox chama sua URL com "confirmed": true)

Boas práticas:

Use o invocation_id como chave de idempotência do seu lado.
Valide no seu sistema se o contato pode fazer aquilo. O agente nunca deve ser a única barreira.
Para pagamentos, descontos e mudanças de cadastro, prefira passar para humano.

Teste

POST /v1/agents/{agent_id}/actions/{id}/test chama a sua URL com argumentos de exemplo e devolve o que a Nevox recebeu, o tempo de resposta e se a assinatura foi aceita.

As ações também podem ser cadastradas, testadas, ligadas e desligadas em Painel → Desenvolvedores → Ações, que mostra as últimas chamadas (sucesso, erro e tempo). O histórico fica guardado por 30 dias. O que o seu sistema devolve não é guardado: só o tamanho, a situação e o tempo.