Agent Bots para agentes de IA

Autenticação

O token do bot vai no header api_access_token. O NooviChat não lê Authorization: Bearer nesta API: uma requisição que use apenas Authorization é tratada como não autenticada e cai no fluxo de login de usuário, não no de bot.

curl -s "https://chat.seudominio.com/api/v1/accounts/1/conversations" \
  -H "api_access_token: SEU_TOKEN_DE_BOT" \
  -H "Content-Type: application/json"

Descobrir o que você pode

Chame isto antesde planejar uma tarefa. É a única rota liberada a qualquer agent-bot, inclusive um que ainda não tem permissão nenhuma — justamente para que a resposta a "o que eu posso fazer?" nunca seja a mesma negação genérica das outras rotas.

{
  "id": 118,
  "name": "Hermes Teste",
  "account_id": 1,
  "permissions": ["conversation_manage", "pipeline_manage", "appointment_manage"],
  "inboxes": [{ "id": 18499, "name": "Vendas Teste" }],
  "pipeline_actions": ["cards_move", "cards_win"],
  "pipeline_actions_effect": "narrowed",
  "pipelines": [{ "id": 15236, "name": "Funil de Vendas" }],
  "endpoints": [
    {
      "surface": "api/v1/accounts/conversations",
      "actions": ["index", "show", "filter", "search", "create", "update"],
      "requires_any_of": ["conversation_manage", "conversation_unassigned_manage"],
      "granted": true
    }
  ]
}

Permissões do bot

As permissões de um bot usam o mesmo vocabulário das funções personalizadas de usuário, mais uma exclusiva de bot. Elas ficam em bot_config.permissions, um array de strings. Um valor fora deste catálogo faz a gravação falhar com 422.

Provisionar o bot

Os três passos abaixo exigem um token de administrador da conta. Um bot não consegue se autoprovisionar: as rotas de agent_bots e de inboxes não fazem parte da superfície de bot e respondem 401 para um token de bot.

curl -s -X POST "https://chat.seudominio.com/api/v1/accounts/1/agent_bots" \
  -H "api_access_token: TOKEN_DE_ADMIN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agente Hermes",
    "description": "Agente de IA externo",
    "outgoing_url": "https://meuagente.exemplo.com/hooks/noovichat"
  }'

{
  "id": 7,
  "name": "Agente Hermes",
  "description": "Agente de IA externo",
  "outgoing_url": "https://meuagente.exemplo.com/hooks/noovichat",
  "bot_type": "webhook",
  "bot_config": {},
  "account_id": 1,
  "access_token": "AbCdEf...",
  "secret": "...",
  "system_bot": false
}

curl -s -X PATCH "https://chat.seudominio.com/api/v1/accounts/1/agent_bots/7" \
  -H "api_access_token: TOKEN_DE_ADMIN" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_config": {
      "permissions": [
        "conversation_manage",
        "contact_manage",
        "pipeline_manage",
        "follow_up_manage",
        "appointment_manage"
      ]
    }
  }'

{
  "message": "unknown bot permissions: pipeline_admin",
  "attributes": ["base"]
}

curl -s -X POST "https://chat.seudominio.com/api/v1/accounts/1/inboxes/42/set_agent_bot" \
  -H "api_access_token: TOKEN_DE_ADMIN" \
  -H "Content-Type: application/json" \
  -d '{"agent_bot": 7}'

Superfície completa

Esta é a lista integral do que um token de bot alcança. Qualquer rota ou ação fora dela responde 401 com {"error":"Access to this endpoint is not authorized for bots"}, independentemente das permissões gravadas. Quando a coluna de permissão lista mais de um valor, basta o bot carregar um deles.

Contrato de erros

Os corpos abaixo são literais. As mensagens marcadas como traduzidas seguem o idioma configurado na conta; o status HTTP e as chaves JSON não mudam.

Atendimento

Ler o histórico da conversa

curl -s "https://chat.seudominio.com/api/v1/accounts/1/conversations/318/messages" \
  -H "api_access_token: SEU_TOKEN_DE_BOT"

{
  "meta": {
    "labels": ["lead-quente"],
    "additional_attributes": {},
    "contact": { "id": 91, "name": "Ana Souza", "phone_number": "+5511999990000", "type": "contact" },
    "assignee": { "id": 4, "name": "Carlos", "type": "user" },
    "agent_last_seen_at": 1771596000,
    "assignee_last_seen_at": 1771596000
  },
  "payload": [
    {
      "id": 88120,
      "content": "Bom dia, ainda da tempo de agendar?",
      "message_type": 0,
      "content_type": "text",
      "private": false,
      "created_at": 1771595880,
      "conversation_id": 318,
      "inbox_id": 42,
      "sender": { "id": 91, "name": "Ana Souza", "type": "contact" },
      "attachments": []
    },
    {
      "id": 88121,
      "content": "Bom dia, Ana! Da sim.",
      "message_type": 1,
      "content_type": "text",
      "private": false,
      "created_at": 1771595940,
      "conversation_id": 318,
      "inbox_id": 42,
      "sender": { "id": 7, "name": "Agente Hermes", "type": "agent_bot" }
    }
  ]
}

BASE="https://chat.seudominio.com/api/v1/accounts/1/conversations/318/messages"
CURSOR=0

while : ; do
  PAGE=$(curl -s "$BASE?after=$CURSOR" -H "api_access_token: SEU_TOKEN_DE_BOT")
  COUNT=$(echo "$PAGE" | jq '.payload | length')
  [ "$COUNT" -eq 0 ] && break
  echo "$PAGE" | jq -c '.payload[]'
  CURSOR=$(echo "$PAGE" | jq '.payload[-1].id')
  [ "$COUNT" -lt 100 ] && break
done

Saber o que você ainda não viu

O meta da resposta declara a paginação. Confira sempre — o truncamento é invisível sem estes campos, e o modo after corta jogando fora as mensagens mais recentes: é exatamente o que esconde a mensagem que você acabou de enviar, levando o agente a concluir que a entrega falhou e reenviar ao cliente.

"meta": {
  "total_count": 108,        // total real da conversa
  "returned_count": 100,     // quantas vieram nesta pagina
  "has_more_before": false,  // ha mensagens ANTES da mais antiga desta pagina
  "has_more_after": true,    // ha mensagens DEPOIS da mais recente desta pagina
  "oldest_id": 83390,
  "newest_id": 83489
}

Interpretar cada mensagem

Três campos decidem o significado de uma mensagem. Ignorar qualquer um leva o agente a responder ao próprio texto ou a repetir para o cliente uma nota escrita entre atendentes.

Anexos: imagem, áudio e vídeo

Quando a mensagem tem mídia, ela vem em attachments. O campo data_url é uma URL assinada: baixa sem o header api_access_token. É o caminho para o agente enviar a imagem a um modelo de visão, o áudio a um modelo de transcrição ou o vídeo a um extrator de quadros.

{
  "id": 88124,
  "message_type": 0,
  "content": "",
  "content_type": "text",
  "private": false,
  "sender": { "id": 91, "name": "Ana Souza", "type": "contact" },
  "attachments": [
    {
      "id": 5512,
      "message_id": 88124,
      "file_type": "image",
      "account_id": 1,
      "extension": "jpg",
      "content_type": "image/jpeg",
      "data_url": "https://chat.seudominio.com/rails/active_storage/blobs/redirect/...",
      "thumb_url": "https://chat.seudominio.com/rails/active_storage/representations/...",
      "file_size": 184322,
      "width": 1280,
      "height": 960
    }
  ]
}

Responder na conversa

curl -s -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations/318/messages" \
  -H "api_access_token: SEU_TOKEN_DE_BOT" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Consigo encaixar voce amanha as 14h. Confirma?",
    "message_type": "outgoing",
    "private": false
  }'

{
  "id": 88130,
  "content": "Consigo encaixar você amanha as 14h. Confirma?",
  "message_type": 1,
  "content_type": "text",
  "private": false,
  "conversation_id": 318,
  "inbox_id": 42,
  "created_at": 1771596300,
  "sender": { "id": 7, "name": "Agente Hermes", "type": "agent_bot" }
}

{ "error": "<mensagem>" }

Quando um agente marca o bot numa nota

Em uma nota interna, o agente pode digitar @ e escolher o bot na aba Botspara pedir algo sobre aquela conversa — "refaça o orçamento", "me passa um resumo". O bot recebe, na sua outgoing_url, um evento próprio, agent_bot_mentioned:

• só o bot marcado recebe, e só se a nota foi escrita por uma pessoa;
• só pode ser marcado o bot que atende a caixa de entrada da conversa (o mesmo vínculo que libera a escrita nela) — os outros aparecem na lista como "Não atende esta caixa de entrada";
• notas internas continuam fora do message_created: sem a menção, o bot não recebe a nota.

{
  "event": "agent_bot_mentioned",
  "mentioned_agent_bot": { "id": 7, "name": "Agente Hermes" },
  "instruction": "refaça o orçamento com 10% de desconto",
  "id": 88131,
  "content": "[@Agente Hermes](mention://agent_bot/7/Agente%20Hermes) refaça o orçamento com 10% de desconto",
  "private": true,
  "message_type": "outgoing",
  "sender": { "id": 3, "name": "Ana", "type": "user" },
  "conversation": { "id": 318, "inbox_id": 42 },
  "inbox": { "id": 42, "name": "WhatsApp Vendas" },
  "account": { "id": 1, "name": "Minha Empresa" }
}

instruction é a nota em texto puro, sem a menção ao bot; outras menções (agentes, times) ficam como @Nome. conversation, inbox e sender têm o mesmo formato do message_created. Para responder, use Responder na conversa com o token do bot.

Transferir para um humano

curl -s -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations/318/assignments" \
  -H "api_access_token: SEU_TOKEN_DE_BOT" \
  -H "Content-Type: application/json" \
  -d '{"assignee_id": 4}'

CRM / Pipeline

Achar o card da conversa

curl -s "https://chat.seudominio.com/api/v1/accounts/1/pipeline_cards?conversation_display_id=318&include_linked_conversations=true" \
  -H "api_access_token: SEU_TOKEN_DE_BOT"

{
  "payload": [
    {
      "id": 4412,
      "title": "Ana Souza - Consulta",
      "pipeline_id": 3,
      "pipeline_stage": "negociação",
      "conversation_display_id": 318,
      "contact_id": 91,
      "value": "980.0",
      "priority": "high",
      "won_at": null,
      "lost_at": null
    }
  ]
}

Mover o card de etapa

# 1. leia o card para saber a versão da etapa
curl -s "https://chat.seudominio.com/api/v1/accounts/1/pipeline_cards/4412" \
  -H "api_access_token: SEU_TOKEN_DE_BOT" | jq .stage_version
# -> 7

# 2. mova enviando a versão que você leu
curl -s -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline_cards/4412/move_to_stage" \
  -H "api_access_token: SEU_TOKEN_DE_BOT" \
  -H "Content-Type: application/json" \
  -d '{"pipeline_stage": "negociacao", "expected_version": 7}'

{ "error": "<mensagem da policy>" }

{
  "error": "Pipeline card stage changed since the version you sent",
  "reason": "stage_version_conflict",
  "expected_version": 7,
  "current_version": 8,
  "current_stage": "proposta"
}

{
  "error": "expected_version is required for agent bots on this endpoint",
  "reason": "expected_version_required",
  "requires_fresh_read": true
}

{
  "error": "Invalid stage 'negociando'",
  "available_stages": ["lead", "qualificado", "negociação", "Ganho", "Perdido"]
}

{ "error": "<mensagem>" }

Fechar a venda: produto, quantidade e valor

Um bot com pipeline_manage não fecha apenas o card — ele registra a venda no razão financeiro, escolhendo produto do catálogo e definindo os valores praticados. O catálogo vem de GET /pipeline/products, que responde para pipeline_view e pipeline_manage. Depois do fechamento, o razão do card é lido em GET /pipeline/cards/{card_id}/opportunities.

O corpo aceito é o mesmo documentado em API · Pipeline na seção de mark_won — pipeline_product_id, quantity, unit_value, ou o array items para vender mais de um produto na mesma negociação. Não repetimos a tabela aqui de propósito: um contrato descrito em dois lugares vira dois contratos.

# 1. escolher o produto
curl -s "https://chat.seudominio.com/api/v1/accounts/1/pipeline/products" \
  -H "api_access_token: SEU_TOKEN_DE_BOT"

# 2. fechar com produto e valor praticado
curl -s -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline/cards/19800/deal_status/mark_won" \
  -H "api_access_token: SEU_TOKEN_DE_BOT" \
  -H "Content-Type: application/json" \
  -d '{"pipeline_product_id": 2, "quantity": 3, "unit_value": 2500.50, "won_value": 7501.50, "won_note": "fechado pelo agente"}'

# 3. conferir o razão do card
curl -s "https://chat.seudominio.com/api/v1/accounts/1/pipeline/cards/19800/opportunities" \
  -H "api_access_token: SEU_TOKEN_DE_BOT"

Registrar o que aconteceu

{ "errors": ["<mensagem>"] }

Agendamento

Toda a superfície de Agendamento exige appointment_manage — uma única permissão cobre ler agenda, consultar disponibilidade e criar. Nesta área a negação de policy responde 403 com {"error":"forbidden"}, e não 401.

Consultar horários livres

curl -s "https://chat.seudominio.com/api/v1/accounts/1/appointments/availability?professional_id=12&service_id=5&date=2026-08-25" \
  -H "api_access_token: SEU_TOKEN_DE_BOT"

{
  "data": {
    "date": "2026-08-25",
    "professional_id": 12,
    "slots": ["2026-08-25T09:00:00-03:00", "2026-08-25T14:00:00-03:00"]
  }
}

{ "error": "<mensagem>" }

Criar o agendamento

curl -s -X POST "https://chat.seudominio.com/api/v1/accounts/1/appointments" \
  -H "api_access_token: SEU_TOKEN_DE_BOT" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment": {
      "contact_id": 91,
      "professional_id": 12,
      "service_id": 5,
      "scheduled_at": "2026-08-25T14:00:00-03:00",
      "conversation_display_id": 318,
      "notes": "Agendado pelo agente de IA a partir da conversa."
    }
  }'

Follow-up

Há dois caminhos, com contratos diferentes. O follow-up individual é uma mensagem programada com texto livre naquela conversa. A regra de etapa é uma cadência do funil: quando um card entra em determinada etapa, o follow-up nasce sozinho.

Follow-up individual

curl -s -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations/318/follow-ups" \
  -H "api_access_token: SEU_TOKEN_DE_BOT" \
  -H "Content-Type: application/json" \
  -d '{
    "follow_up": {
      "content": "Oi Ana! Passando para confirmar seu horario de amanha as 14h.",
      "scheduled_at": "2026-08-24T18:00:00-03:00",
      "title": "Confirmacao D-1"
    }
  }'

{
  "id": 771,
  "message": "Oi Ana! Passando para confirmar seu horário de amanha as 14h.",
  "scheduled_at": 1771966800,
  "title": "Confirmação D-1",
  "inbox_id": 42,
  "conversation_id": 318,
  "created_at": 1771596400,
  "status": "pending"
}

{ "error": "Scheduled at must be in the future" }

Regra de follow-up por etapa

curl -s -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipelines/3/follow-up-rules" \
  -H "api_access_token: SEU_TOKEN_DE_BOT" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_follow_up_rule": {
      "to_stage": "negociacao",
      "from_stage": null,
      "content_mode": "ai",
      "ai_instruction": "Retome a conversa citando o servico discutido e ofereca dois horarios.",
      "delay_minutes": 1440,
      "sender_agent_bot_id": 7,
      "send_window": { "enabled": true, "start": "08:00", "end": "18:00", "days": [1,2,3,4,5] }
    }
  }'

{
  "id": 55,
  "pipeline_id": 3,
  "follow_up_template_id": null,
  "sender_id": null,
  "sender_agent_bot_id": 7,
  "sender_agent_bot_name": "Agente Hermes",
  "content_mode": "ai",
  "ai_instruction": "Retome a conversa citando o serviço discutido e ofereca dois horários.",
  "from_stage": null,
  "to_stage": "negociação",
  "delay_minutes": 1440,
  "send_window": { "enabled": true, "start": "08:00", "end": "18:00", "days": [1,2,3,4,5] },
  "enabled": true,
  "conditions": {},
  "created_at": 1771596500,
  "updated_at": 1771596500
}

{ "errors": ["Ai instruction nao pode ficar em branco"] }

{ "error": "<mensagem no idioma da conta>" }

Não suportado

Itens abaixo não existem hoje. Não há parâmetro, header ou permissão que os habilite.

• Authorization: Bearer nesta API. O único header aceito é api_access_token.
• Token de bot válido para mais de uma conta.
• Qualquer ação de apagar (destroy) em qualquer recurso.
• Cancelar ou reenviar follow-up, cancelar agendamento, apagar card ou conversa.
• Criar ou alterar produto do catálogo do Pipeline (responde 403 mesmo com pipeline_manage).
• Mover card para etapa de perda por move_to_stage (responde 403).
• Listar agentes, equipes, inboxes, webhooks, automações, relatórios ou central de ajuda com token de bot.
• Autoprovisionamento: um bot não cria bots, não altera as próprias permissões e não vincula a si mesmo a uma inbox.
• Parâmetro de tamanho de página no histórico de mensagens.
• Distinguir, pela resposta, um 404 de conta errada de um 404 de recurso fora do recorte de visibilidade.