Bots

Gerencie bots de atendimento automatizado. Bots podem ser configurados por conta ou globalmente na plataforma.

O que um bot alcança com o token de acesso

Um agent bot autentica com api_access_token como qualquer usuário, mas ter um token válido da conta não dá acesso a toda a API pública. O alcance depende de duas coisas gravadas no próprio bot: as permissões em bot_config.permissions e o vínculo de inbox ativo com a conta. Bot novo nasce sem permissão nenhuma e não alcança nada.

A superfície completa está em uma página própria

A lista integral de rotas, a permissão que cada uma exige e o corpo exato de cada recusa estão em Agent Bots para agentes de IA. Em resumo: conversas e mensagens, contatos, funil e cards, agendamentos e follow-ups — cada domínio atrás da sua permissão. Qualquer rota ou ação fora dessa lista responde 401 com {"error":"Access to this endpoint is not authorized for bots"}, mesmo com token válido. Nenhuma ação de apagar está liberada para bot.

Mover card e marcar ganho exigem opt-in por funil

Essas duas ações do Pipeline não vêm liberadas por padrão para nenhum bot. Um funil precisa listar explicitamente quais bots podem agir nele — o mesmo mecanismo já usado para dar acesso a agentes humanos. Um bot sem esse acesso registrado no funil recebe 404 ao tentar mover um card ou marcar um negócio como ganho, mesmo com token válido. Atualizar para uma versão nova do NooviChat não libera nada sozinho: o acesso é sempre configurado funil a funil, pelo administrador da conta.

Quem fica registrado como autor

Quando um bot marca um negócio como ganho ou cria um acompanhamento, o NooviChat não atribui essa ação a nenhuma pessoa da equipe — o registro aponta para o bot, de forma distinta de um usuário humano. Isso aparece no histórico do card e no acompanhamento dentro do NooviChat; hoje esses dois endpoints não devolvem esse dado no corpo da resposta JSON. Se a sua integração precisa saber quem — pessoa ou bot — fez uma ação, não assuma que um id de usuário devolvido por outro endpoint é compatível com o de um bot: eles vêm de cadastros diferentes.

Bots da Conta

GET/api/v1/accounts/{account_id}/agent_bots

Lista os bots configurados na conta.

200Lista de bots

json

[
  {
    "id": 1,
    "name": "Bot Boas-vindas",
    "description": "Recepciona novos contatos",
    "outgoing_url": "https://meuapp.com/bot/webhook",
    "account_id": 1
  }
]

POST/api/v1/accounts/{account_id}/agent_bots

Cria um novo bot na conta.

Body

Nome	Tipo	Obrigatorio	Descricao
`name`	`string`	Sim	Nome do bot
`description`	`string`	Nao	Descrição
`outgoing_url`	`string`	Nao	URL do webhook que recebe mensagens para o bot processar
`bot_type`	`string`	Nao	Tipo do bot. Valor atualmente suportado: webhook
`bot_config`	`object`	Nao	Configuração adicional específica do bot
`avatar_url`	`string`	Nao	URL do avatar do bot

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/agent_bots" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bot Triagem",
    "description": "Faz triagem inicial das conversas",
    "outgoing_url": "https://meuapp.com/bot/triagem"
  }'

PATCH/api/v1/accounts/{account_id}/agent_bots/{id}

Atualiza um bot da conta.

DELETE/api/v1/accounts/{account_id}/agent_bots/{id}

Remove um bot da conta.

Bots de Agente (Platform API)

Bots globais gerenciados pela Platform API. Requerem token de plataforma.

GET/platform/api/v1/agent_bots

Lista todos os bots da plataforma.

POST/platform/api/v1/agent_bots

Cria um bot global na plataforma.

Body

Nome	Tipo	Obrigatorio	Descricao
`name`	`string`	Sim	Nome do bot
`description`	`string`	Nao	Descrição
`outgoing_url`	`string`	Nao	URL do webhook
`avatar_url`	`string`	Nao	URL do avatar do bot

GET/platform/api/v1/agent_bots/{id}

Obtém detalhes de um bot.

PATCH/platform/api/v1/agent_bots/{id}

Atualiza um bot.

DELETE/platform/api/v1/agent_bots/{id}

Remove um bot.