Conhecimento

Pergunte direto ao conhecimento da empresa e mantenha documentos, FAQ e tabela de serviços sincronizados.

O conhecimento é tudo o que o agente sabe sobre a sua empresa. Ele é um só para todos os canais: o que você ensina aqui vale no WhatsApp, no site, no widget e na API.

Fonte	Exemplo
`text`	Políticas, procedimentos, instruções internas
`faq`	Pergunta e resposta
`url` (em breve)	Uma página do seu site (a Nevox lê e atualiza toda semana)
`file` (em breve)	PDF, DOCX ou TXT de até 20 MB
`correction`	Correções feitas no painel ou pelo ensino
`service`	Itens da tabela de serviços

Perguntar direto ao conhecimento

POST /v1/agents/{agent_id}/ask · escopo knowledge:read

Use em telas internas, sem abrir uma conversa. Exemplo: a recepção consulta uma política no painel administrativo.

bash

curl https://api.nevox.ai/v1/agents/agt_8f2k1x/ask \
  -H "Authorization: Bearer $NEVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Qual o prazo para pedir reembolso?",
    "audience": "staff",
    "contact_external_id": "paciente_1042"
  }'

json

{
  "answered": true,
  "answer": "O reembolso pode ser pedido em até 7 dias após a consulta, pelo email financeiro@exemplo.com.",
  "confidence": "high",
  "sources": [
    { "type": "text", "id": "kn_pol07", "title": "Política de reembolso" }
  ],
  "usage": { "ask_count_month": 112, "ask_limit_month": 1000 }
}

Parâmetro	Descrição
`question`	Obrigatório. Até 2.000 caracteres.
`audience`	`customer` (padrão) responde como o agente responderia ao cliente. `staff` inclui também o conhecimento marcado como interno no painel.
`contact_external_id`	Opcional (em breve). Vai dar ao agente o contexto do contato (nome, idioma, histórico).
`language`	Opcional. Idioma da resposta.

Se o conhecimento não cobre a pergunta, a resposta vem com "answered": false e answer: null. O agente nunca inventa: toda resposta vem com as fontes (sources), os itens do conhecimento e da tabela de serviços que a sustentam. Perguntas sem resposta aparecem em análise → lacunas de conhecimento.

Gerenciar o conhecimento

Escopos knowledge:read (leitura) e knowledge:write (escrita).

Endpoint	Descrição
`GET /v1/agents/{agent_id}/knowledge`	Lista tudo o que o agente sabe, com a origem de cada item
`POST /v1/agents/{agent_id}/knowledge`	Adiciona um item
`GET /v1/agents/{agent_id}/knowledge/{id}`	Um item
`PATCH /v1/agents/{agent_id}/knowledge/{id}`	Atualiza
`DELETE /v1/agents/{agent_id}/knowledge/{id}`	Remove

Adicionar texto ou FAQ

bash

curl https://api.nevox.ai/v1/agents/agt_8f2k1x/knowledge \
  -H "Authorization: Bearer $NEVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "faq",
    "title": "Atendem por convênio?",
    "question": "Vocês aceitam convênio?",
    "answer": "Não trabalhamos com convênio. Emitimos recibo para pedir reembolso ao seu plano.",
    "visibility": "public",
    "external_id": "faq-convenio"
  }'

Campo	Descrição
`type`	`text` ou `faq` (`url` em breve)
`title`	Para `text`: nome do item, até 200 caracteres. Em `faq`, o título é a própria pergunta.
`content`	Para `text`: até 50.000 caracteres
`question` / `answer`	Para `faq` (até 2.000 e 10.000 caracteres)
`visibility`	`public` (o agente usa com clientes) ou `internal` (nenhum canal com cliente usa; só o `/ask` com `audience: "staff"`)
`external_id`	Opcional. Seu ID para o item. Se já existir, o item é atualizado. Bom para sincronizar sem duplicar.
`draft`	Opcional (beta). `true` cria um rascunho, que nenhum canal usa até você testar e publicar.

Enviar arquivo

Em breve. O envio de PDF, DOCX e TXT e a leitura de páginas do site pela API chegam numa próxima versão. Hoje, envie o conteúdo como text.

Resposta

json

{
  "id": "kn_9xk20",
  "type": "faq",
  "title": "Atendem por convênio?",
  "visibility": "public",
  "status": "ready",
  "source": "api",
  "external_id": "faq-convenio",
  "created_at": "2026-11-03T14:40:00Z",
  "updated_at": "2026-11-03T14:40:00Z"
}

O campo source mostra de onde o item veio: dashboard, api, vox, website, correction ou learning.

Tabela de serviços

A tabela de serviços é a única fonte de preços do agente. Ela é da empresa: vale para todos os agentes, então qualquer agent_id da conta lê e altera a mesma tabela. Ele repete o que está na tabela, nunca arredonda e nunca calcula desconto por conta própria. O que não estiver na tabela vira agendamento de avaliação.

GET /v1/agents/{agent_id}/services · PUT /v1/agents/{agent_id}/services

O PUT substitui a tabela inteira: o que não vier na lista sai. Serviços com o mesmo external_id mantêm o ID. Para mudar um item, use PATCH /v1/agents/{agent_id}/services/{id}.

bash

curl -X PUT https://api.nevox.ai/v1/agents/agt_8f2k1x/services \
  -H "Authorization: Bearer $NEVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "services": [
      {
        "external_id": "consulta-clinico",
        "name": "Consulta com clínico geral",
        "price_type": "fixed",
        "price": 8900,
        "duration_minutes": 30
      },
      {
        "external_id": "retorno",
        "name": "Consulta de retorno",
        "price_type": "fixed",
        "price": 4900,
        "duration_minutes": 20,
        "notes": "Válido até 30 dias após a primeira consulta"
      },
      {
        "external_id": "laudo",
        "name": "Laudo médico",
        "price_type": "on_evaluation"
      }
    ]
  }'

Campo	Descrição
`price_type`	`fixed` (preço fechado), `from` ("a partir de"), `per_unit` (por unidade) ou `on_evaluation` (sob avaliação)
`price`	Em centavos. Obrigatório, exceto em `on_evaluation`.
`unit`	Obrigatório em `per_unit`: `hour` (hora), `m2` (m²), `room` (cômodo), `visit` (visita), `pet`, `session` (sessão) ou `month` (mês). Aceita também o nome em português, como `"hora"`.
`duration_minutes`	Opcional. Sem duração, o serviço não entra na agenda (ex.: mensalidade).
`notes`	Condições que o agente deve dizer junto com o preço, até 500 caracteres
`active`	`false` esconde o serviço sem apagar
`currency`	No corpo do `PUT`, `BRL` ou `USD` (padrão: a moeda da conta)

Os valores acima são só exemplos.