Brain

O Brain é a IA da Arara para atendimento no WhatsApp. Ele responde conversas com a base de conhecimento da sua organização, executa Actions (Pix no AbacatePay, agendamento no Cal.com, link de pagamento Stripe, card do catálogo Meta) e encaminha a conversa para um atendente quando não deve responder sozinho.

O acesso ao Brain depende do plano. Os endpoints que executam trabalho do Brain (alterar config, ingerir conteúdo, configurar Actions, testar) respondem 403 com PLAN_FEATURE_LOCKED quando o plano não inclui Brain, e 403 com NO_DEDICATED_NUMBER quando a organização não tem número WhatsApp dedicado.

O que o Brain faz

Responde em linguagem natural

Usa a personalidade, as regras e o conhecimento configurados pra sua organização.

Executa ações

Gera Pix, lista e reserva horários, cria link de pagamento, envia card de produto. Ver a seção Actions disponíveis, abaixo.

Encaminha para um atendente

Abre um handoff com motivo e resumo e dispara o evento de webhook conversation.needs_human.

Aprende do seu conteúdo

Você adiciona texto, uma URL ou um PDF. O conteúdo é indexado para consulta nas respostas.

Como configurar

Confira os pré-requisitos

GET /v1/brain/prerequisites lista o que falta. Enquanto houver pré-requisito bloqueante, ligar o Brain (active: true) é recusado.

Configure personalidade e regras

No dashboard em Brain, ou via PATCH /v1/brain/config.

Adicione conhecimento

Texto, URL ou PDF. Ver Knowledge base.

Configure Actions

Veja a seção Actions disponíveis, abaixo. O encaminhamento para um atendente (HANDOFF_TO_HUMAN) já vem habilitado quando o Brain é ligado.

Teste com a eval suite

Cadastre perguntas com o que a resposta deve e não deve conter e rode a suite. Ver Eval suite.

Ligue

PATCH /v1/brain/config com {"active": true} e escolha o assistMode.

Os exemplos usam a chave de API na variável de ambiente ARARA_API_KEY (ara_live_...). Não há modo de teste.

Knowledge base

# Texto
curl -X POST https://api.ararahq.com/v1/brain/knowledge \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "FAQ",
    "content": "Aceitamos devolução em até 7 dias após o recebimento, com o produto sem uso."
  }'

# URL (lê a página informada)
curl -X POST https://api.ararahq.com/v1/brain/ingest-url \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://meusite.com.br/ajuda/devolucao" }'

# PDF (multipart, campo file)
curl -X POST https://api.ararahq.com/v1/brain/ingest-pdf \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -F "file=@manual.pdf"

POST /v1/brain/knowledge: type é opcional (default GENERAL), content é obrigatório. GET /v1/brain/knowledge lista, PUT /v1/brain/knowledge/{id} atualiza o content, DELETE /v1/brain/knowledge/{id} remove.
ingest-url: busca uma única página (não faz crawl do site), exige ao menos 200 caracteres de texto útil e extrai dados do negócio e perguntas frequentes pra config do Brain. Responde { ok, sourceUrl, charsScraped, extracted, error }.
ingest-pdf: até 10 MB e 100 páginas. PDF escaneado sem texto extraível é recusado (sem OCR). Responde { ok, fileName, pagesProcessed, charsExtracted, chunksStored, error }.
GET /v1/brain/sources lista as fontes indexadas.

Eval suite

Cada caso tem uma pergunta e, opcionalmente, um texto que a resposta deve conter e um que não deve conter:

curl -X POST https://api.ararahq.com/v1/brain/eval/cases \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Quero devolver um produto que comprei semana passada",
    "expectedHint": "Explicar o prazo de 7 dias e a condição de produto sem uso",
    "mustContain": "7 dias",
    "mustNotContain": "não aceitamos"
  }'

Endpoint	Função
`GET /v1/brain/eval/cases`	Lista os casos com o último resultado
`PUT /v1/brain/eval/cases/{id}`	Atualiza um caso
`DELETE /v1/brain/eval/cases/{id}`	Remove um caso
`POST /v1/brain/eval/cases/{id}/run`	Roda um caso
`POST /v1/brain/eval/run-all`	Roda todos os casos
`GET /v1/brain/eval/summary`	Resumo da suite
`POST /v1/brain/eval/cases/{id}/thumbs`	Marca a última resposta com `{ "thumbsUp": true }`

Cada caso retornado traz lastResponse, lastPassed, judgeScore, judgeReasoning e hallucinationDetected.

Actions disponíveis

Actions são integrações que o Brain invoca durante a conversa. O cliente pede para pagar, o Brain gera o Pix no AbacatePay e manda o link. Pede um horário, o Brain consulta o Cal.com e confirma. Actions só rodam com o Brain ligado.

`actionType`	O que faz	Config	Guia
`ABACATE_PIX`	Gera cobrança Pix no AbacatePay e envia link e copia-e-cola	`apiKey`	AbacatePay (Pix)
`CAL_COM_BOOKING`	Lista horários livres e cria agendamento no Cal.com	`apiKey`, `eventTypeId`	Cal.com
`STRIPE_CHECKOUT`	Cria um Payment Link na sua conta Stripe	`secretKey` (ou `apiKey`)	Stripe
`META_CATALOG_SEND`	Envia o card de um produto do catálogo Meta na conversa	`catalogId`, `phoneNumberId`	Catálogo Meta
`HANDOFF_TO_HUMAN`	Encaminha a conversa para um atendente	nenhuma (habilitada por padrão)	Handoff

Como uma Action funciona

Você habilita a Action

No dashboard em Brain, ou via POST /v1/brain/actions.

O Brain decide quando chamar

Cada Action descreve para o modelo o que faz, quando usar e quais parâmetros precisa. Só Actions habilitadas entram no prompt.

A Arara executa

A chamada ao provedor roda no backend da Arara com as credenciais da sua organização. Toda execução fica registrada.

O Brain responde no WhatsApp

Com o link, o horário ou a confirmação que a Action devolveu.

Configurar via API

curl -X POST https://api.ararahq.com/v1/brain/actions \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actionType": "ABACATE_PIX",
    "enabled": true,
    "config": {
      "apiKey": "sua_chave_abacatepay"
    }
  }'

Responde 204. O mesmo endpoint cria ou atualiza (uma linha por actionType).

Para ligar ou desligar sem reenviar a chave, mande enabled com config vazio: a config salva é preservada.
Valores sensíveis são criptografados antes de gravar.

Para listar o estado de todas as Actions:

curl https://api.ararahq.com/v1/brain/actions \
  -H "Authorization: Bearer $ARARA_API_KEY"

Cada item traz type, displayName, description, parameters, enabled, configured, config (com segredos mascarados) e invocations30d.

Regras (guardrails)

As regras entram no prompt do Brain. Todas vêm ligadas por padrão:

curl -X PATCH https://api.ararahq.com/v1/brain/config \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "guardrails": {
      "noDealPromises": true,
      "noDiscounts": true,
      "noCompetitors": true,
      "noPriceInvention": true,
      "noPersonalDataRequest": true,
      "custom": ["Não prometa entrega no mesmo dia"]
    }
  }'

Além das regras, a resposta passa por uma moderação antes de sair: bloqueia CPF, RG ou número de cartão no texto, URL fora das fontes conhecidas e menções ao próprio prompt. Resposta bloqueada é trocada por encaminhamento para um atendente.

Modo de operação

assistMode aceita:

Valor	Comportamento
`COPILOT` (default)	O Brain sugere resposta para o atendente (`POST /v1/brain/suggest-reply`)
`AUTO`	O Brain responde sozinho
`OFF`	Desligado

Métricas

curl https://api.ararahq.com/v1/brain/metrics \
  -H "Authorization: Bearer $ARARA_API_KEY"

{
  "windowDays": 30,
  "totalResponses": 1820,
  "handoffCount": 364,
  "handoffRate": 0.2,
  "avgLatencyMs": 8400,
  "spentCents": 18750,
  "topHandoffReasons": [
    { "reason": "pergunta fora do escopo", "count": 120 }
  ]
}

topHandoffReasons mostra o que mais vai para atendente. É o melhor ponto de partida para adicionar conhecimento. Uso do mês contra o limite do plano: GET /v1/brain/usage.

Handoff para um atendente

Quando o Brain encaminha, a Arara cria um handoff e envia o webhook conversation.needs_human com handoffId, conversationId, reason, summary e createdAt.

curl "https://api.ararahq.com/v1/brain/handoffs?resolved=false&page=0&size=20" \
  -H "Authorization: Bearer $ARARA_API_KEY"

A resposta é { content, totalPages, totalElements }. Cada item traz id, conversationId, reason, summary, briefing, createdAt, resolvedAt e resolvedByUserId.

POST /v1/brain/handoffs/{id}/resolve marca como resolvido.
POST /v1/brain/handoffs/{id}/return-to-brain devolve a conversa pro Brain.

Quando não usar o modo `AUTO`

Conversas com alto risco financeiro ou jurídico. Use COPILOT: o Brain sugere, o atendente envia.
Setores regulados (saúde, financeiro, jurídico) em que a política interna exige atendente no processo.

Referência de endpoints

Endpoint	Função
`GET /v1/brain/config`	Config atual
`PATCH /v1/brain/config`	Atualiza `active`, `entryMode`, `businessHours`, `exitTriggers`, `personalityPreset`, `personalityCustom`, `guardrails`, `guidedKnowledge`, `model`, `autoDetectLanguage`, `notifyAdmins`, `assistMode`
`GET /v1/brain/config/versions`	Histórico de versões da config
`POST /v1/brain/config/versions/{id}/rollback`	Volta pra uma versão
`GET /v1/brain/prompt-preview`	Prompt final gerado
`GET /v1/brain/prerequisites`	O que falta pra ligar
`GET /v1/brain/templates`	Presets de config por vertical
`POST /v1/brain/templates/apply`	Aplica um preset (`{ "templateId": "..." }`)
`POST /v1/brain/test`	Testa uma resposta (`{ "prompt": "...", "conversationHistory": [] }`)
`POST /v1/brain/cost-estimate`	Estimativa de custo (`{ "monthlyConversations": 1000 }`)
`GET /v1/brain/actions` / `POST /v1/brain/actions`	Lista e configura Actions
`GET /v1/brain/handoffs`	Handoffs
`POST /v1/brain/handoffs/{id}/resolve`	Resolve um handoff

Próximos passos

AbacatePay (Pix)

Cobrança Pix dentro da conversa.

Cal.com

Agendamento pelo WhatsApp.

Atendimento no inbox

Fluxo de atendimento com handoff.

MCP e SDKs

Quando usar Brain, MCP ou SDK.

Receitas

Recursos

Automações

Brain (IA)

Integrações

Migrar de

O que o Brain faz

Responde em linguagem natural

Executa ações

Encaminha para um atendente

Aprende do seu conteúdo

Como configurar

Knowledge base

Eval suite

Actions disponíveis

Como uma Action funciona

Configurar via API

Regras (guardrails)

Modo de operação

Métricas

Handoff para um atendente

Quando não usar o modo `AUTO`

Referência de endpoints

Próximos passos

AbacatePay (Pix)

Cal.com

Atendimento no inbox

MCP e SDKs

​O que o Brain faz

Responde em linguagem natural

Executa ações

Encaminha para um atendente

Aprende do seu conteúdo

​Como configurar

​Knowledge base

​Eval suite

​Actions disponíveis

​Como uma Action funciona

​Configurar via API

​Regras (guardrails)

​Modo de operação

​Métricas

​Handoff para um atendente

​Quando não usar o modo AUTO

​Referência de endpoints

​Próximos passos

AbacatePay (Pix)

Cal.com

Atendimento no inbox

MCP e SDKs

O que o Brain faz

Como configurar

Knowledge base

Eval suite

Actions disponíveis

Como uma Action funciona

Configurar via API

Regras (guardrails)

Modo de operação

Métricas

Handoff para um atendente

Quando não usar o modo `AUTO`

Referência de endpoints

Próximos passos