# API do Agente

> Rode o agente da Waslo do seu próprio código: um endpoint REST para respostas, além de base de conhecimento, catálogo, memória e agenda — sem precisar do painel.

Source: https://waslo.io/pt-BR/docs/agent-api · Last updated: 2026-10-12

Tudo o que o motor de respostas do agente faz, seu código também faz — inclusive base de conhecimento, memória, catálogo, agenda, configuração e uso. A API do Agente expõe o mesmo motor que responde no WhatsApp e no Instagram — a mesma base de conhecimento, a mesma memória por cliente, as mesmas ferramentas de agenda e catálogo — como uma API REST que você chama do seu produto.

A referência completa e a gestão de chaves ficam no [portal do desenvolvedor](/developers).

## Quando usar

- Você já tem um app ou site e quer a Waslo respondendo lá dentro, não em um canal.
- Você é uma agência e quer operar o agente para seus clientes sob sua marca.
- Você quer só a classificação, a memória ou a busca na base de conhecimento, sem a camada de mensagens.

Se você só quer um agente no WhatsApp ou Instagram, não precisa disto — conecte o canal em [Integrações](/docs/connecting-channels).

## Uma chamada

Envie uma mensagem e um id de usuário; receba uma resposta já com memória, citações da base de conhecimento e ações de ferramentas aplicadas.

```bash
curl https://api.waslo.io/v1/agent/reply \
  -H "Authorization: Bearer wsk_live_..." \
  -d '{
    "message": "Do you have a morning slot Thursday?",
    "userId": "customer_8842",
    "tools": ["calendar"]
  }'
```

O `userId` é escolha sua: é o que faz o agente lembrar de uma pessoa entre chamadas. Reutilize e a conversa continua; troque e começa uma nova.

## O que mais a API cobre

| Área | O que dá para fazer |
| --- | --- |
| Respostas | Texto, mídia (imagem, áudio, vídeo, PDF) e saída de voz |
| Classificação | Pontuar uma mensagem como HOT / WARM / COLD isoladamente |
| Memória | Ler ou apagar o que o agente lembra de um usuário |
| Base de conhecimento | Enviar, listar e apagar documentos — compartilhada com o painel |
| Catálogo | CRUD completo de produtos — compartilhado com o painel |
| Agenda | Conectar Google Calendar ou Cal.com sem abrir o painel |
| Configuração | Definir o prompt e o comportamento por requisição ou de forma persistente |
| Uso | Créditos consumidos, saldo atual, teto de gasto |

Tudo que você envia pela API aparece no painel, e tudo que você adiciona no painel é visível para a API. É um único workspace, não dois.

## Chaves de API

As chaves são criadas no [portal do desenvolvedor](/developers) e mostradas **uma única vez** — ficam guardadas com hash, então não conseguimos recuperá-las para você. Cada chave carrega escopos — `agent`, `memory`, `kb`, `catalog`, `config`, `usage` e `tenants` (tenants só para chaves White-label) — e só faz o que eles permitem. Você pode manter até 10 chaves ativas por organização e revogar qualquer uma a qualquer momento.

Trate a chave como uma senha: só no servidor, nunca em bundle de navegador ou app mobile.

## Créditos e limites

**A API sempre cobra créditos, em todos os planos** — é um produto separado da sua assinatura de canais, então uma assinatura Growth não torna as chamadas gratuitas. As tarifas são maiores que as respostas de canal porque cada chamada carrega mais trabalho:

| Evento | Créditos |
| --- | --- |
| Resposta de texto | 2 |
| Resposta que usou uma ferramenta | 3 |
| Resposta que leu mídia (imagem, áudio, vídeo ou PDF) | 5 |
| Saída de voz | +2 |
| Classificação | 1 |

Os planos de desenvolvedor definem seu limite de taxa e concedem uma cota mensal de créditos além do que você compra. Sem plano, valem os limites padrão por minuto e por dia. Você também pode definir um teto de gasto mensal para que um loop descontrolado não esvazie seu saldo — as requisições são recusadas com `spend_cap_reached` ao atingi-lo.

## Erros

Todo erro volta no mesmo envelope, com um `request_id` que vale citar se você falar com o suporte.

| Código | Significado |
| --- | --- |
| 400 | O corpo da requisição não passou na validação |
| 401 | Chave de API ausente ou inválida |
| 402 | Créditos insuficientes, ou teto de gasto atingido |
| 403 | Os escopos da chave não cobrem este endpoint |
| 413 | Payload grande demais |
| 429 | Limite de taxa — tente de novo após o intervalo do cabeçalho |

Envie o cabeçalho `Idempotency-Key` nas respostas: uma chamada repetida em 24 horas devolve a resposta original em vez de cobrar duas vezes.

## Seus usuários de API ficam fora da caixa do operador

As conversas criadas pela API pertencem aos usuários do seu app, não a quem acompanha a caixa da Waslo — por isso ficam ocultas por padrão em Leads e Caixa de entrada. Use `?includeApi=true` quando quiser vê-las.

## White-label

Inquilinos existem só no plano White-label. Nesse plano, uma chave mestra pode criar workspaces isolados por cliente, cada um com sua chave, base de conhecimento e catálogo. A conta principal paga todo o uso e recebe um medidor por inquilino para refaturar; o inquilino nunca vê o saldo da principal. Inquilinos não têm acesso ao painel por design — a API é toda a superfície deles, inclusive [conectar uma agenda](/docs/integrations).

## Próximos passos

- [Portal do desenvolvedor](/developers) — crie uma chave, leia a referência completa, escolha um plano
- [Base de conhecimento](/docs/knowledge-base) — o que o agente lê antes de responder
- [Catálogo de produtos](/docs/product-catalog) — de onde ele pode vender
- [Por que esta resposta](/docs/why-this-reply) — o rastro de raciocínio por trás de cada resposta

## Tópicos

Quando sua organização define rótulos de tópico (2–8), `POST /v1/agent/reply` e `POST /v1/agent/classify` incluem um campo `topic`, e `GET/PUT /v1/config` lê e grava `topicLabels` — totalmente headless, incluindo white-label. Veja [Tópicos e roteamento da equipe](/docs/team-routing).

`GET/PUT /v1/config` também lê e grava `replyLanguage`: `"auto"` responde no idioma de cada usuário final, um código de idioma (`"es"`, `"ar"`, `"zh-Hans"`…) responde sempre nesse idioma e `null` segue a configuração da organização no painel (o idioma do usuário, a menos que um tenha sido fixado).
