Agentes de IA

Os agentes de IA respondem as conversas do WhatsApp e do Chat do site sozinhos, seguindo as instruções, FAQs e a base de conhecimento configuradas no painel (Agentes de IA). Pela API você:

• lista os agentes e vê qual é o padrão;
• liga ou desliga um agente;
• escolhe qual agente atende uma conversa, ou desliga a IA só naquela conversa (para um humano assumir).

Criar agentes e editar instruções, FAQs e base de conhecimento é feito no painel.

O objeto agente de IA

{
  "id": "523fc881-026e-4e04-89e2-8a99c28607c9",
  "object": "ai_agent",
  "name": "Aurora",
  "description": "Atendimento geral: dúvidas sobre pedidos, entregas e trocas.",
  "active": true,
  "is_default": true,
  "tone": "profissional_caloroso",
  "strict_mode": false,
  "created_at": "2026-03-05T14:00:00Z",
  "updated_at": "2026-11-02T10:15:00Z"
}

Campo	Tipo	Descrição
id	UUID	ID do agente. Use em ai_agent_id de uma conversa.
object	string	Sempre ai_agent.
name	string	Nome do agente.
description	string ou null	Descrição livre (para que serve o agente).
active	booleano	Se o agente está respondendo.
is_default	booleano	Agente padrão: atende as conversas que não têm agente definido (ai_agent_id: null).
tone	string	Tom de voz configurado no painel (ex.: profissional_caloroso).
strict_mode	booleano	Modo restrito: só responde com base nas FAQs, na base de conhecimento e nas instruções.
created_at	data	Criação.
updated_at	data	Última alteração.

Quem responde uma conversa

A IA responde uma conversa quando as três condições são verdadeiras:

1. a conversa está com a IA ligada (ai_enabled: true no contato);
2. o agente da conversa — o de ai_agent_id ou, se for null, o agente padrão — está active: true;
3. a IA da organização está ligada (ou seja, o agente padrão está ativo).

Grupos não são atendidos pela IA.

Listar agentes de IA

GET/v1/ai-agents

Todos os agentes da organização. Use para descobrir o id do agente certo antes de atribuí-lo a uma conversa.

Não tem parâmetros. A lista vem inteira numa página (has_more: false).

curl

curl https://platform.toptalking.com.br/v1/ai-agents \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

JavaScript

const res = await fetch('https://platform.toptalking.com.br/v1/ai-agents', {
  headers: { Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}` },
});
const { data: agentes } = await res.json();
const padrao = agentes.find((a) => a.is_default);

Python

import os
import requests

res = requests.get(
    "https://platform.toptalking.com.br/v1/ai-agents",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    timeout=30,
)
res.raise_for_status()
agentes = res.json()["data"]
padrao = next(a for a in agentes if a["is_default"])

Resposta 200

{
  "object": "list",
  "data": [
    {
      "id": "523fc881-026e-4e04-89e2-8a99c28607c9",
      "object": "ai_agent",
      "name": "Aurora",
      "description": "Atendimento geral: dúvidas sobre pedidos, entregas e trocas.",
      "active": true,
      "is_default": true,
      "tone": "profissional_caloroso",
      "strict_mode": false,
      "created_at": "2026-03-05T14:00:00Z",
      "updated_at": "2026-11-02T10:15:00Z"
    },
    {
      "id": "52da47ff-662a-4292-9961-27a95fc5ddd8",
      "object": "ai_agent",
      "name": "Vendas",
      "description": "Qualifica leads e apresenta produtos e promoções.",
      "active": true,
      "is_default": false,
      "tone": "descontraido",
      "strict_mode": true,
      "created_at": "2026-06-18T16:30:00Z",
      "updated_at": "2026-10-21T09:05:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Erros

Só os gerais: 401 (chave) e 429 (limite por minuto). Veja Erros.

Buscar agente de IA

GET/v1/ai-agents/{agent_id}

Um agente pelo ID — por exemplo, para mostrar qual agente atende uma conversa a partir do ai_agent_id do contato.

Parâmetro	Onde	Tipo	Obrigatório	Descrição
agent_id	caminho	UUID	sim	ID do agente.

curl

curl https://platform.toptalking.com.br/v1/ai-agents/52da47ff-662a-4292-9961-27a95fc5ddd8 \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

JavaScript

const agentId = '52da47ff-662a-4292-9961-27a95fc5ddd8';
const res = await fetch(`https://platform.toptalking.com.br/v1/ai-agents/${agentId}`, {
  headers: { Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}` },
});
const agente = await res.json();

Python

import os
import requests

agent_id = "52da47ff-662a-4292-9961-27a95fc5ddd8"
res = requests.get(
    f"https://platform.toptalking.com.br/v1/ai-agents/{agent_id}",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    timeout=30,
)
res.raise_for_status()
agente = res.json()

Resposta 200

{
  "id": "52da47ff-662a-4292-9961-27a95fc5ddd8",
  "object": "ai_agent",
  "name": "Vendas",
  "description": "Qualifica leads e apresenta produtos e promoções.",
  "active": true,
  "is_default": false,
  "tone": "descontraido",
  "strict_mode": true,
  "created_at": "2026-06-18T16:30:00Z",
  "updated_at": "2026-10-21T09:05:00Z"
}

Erros

HTTP	code	Quando acontece
404	resource_not_found	O agente não existe ou é de outra organização.

Ligar ou desligar agente de IA

PATCH/v1/ai-agents/{agent_id}

Liga (active: true) ou desliga (active: false) um agente. Um agente desligado para de responder as conversas dele.

Desligar o agente padrão desliga a IA da organização inteira

O agente com is_default: true funciona como o interruptor geral da IA (o mesmo do painel). Com ele desligado, nenhuma conversa é respondida pela IA, nem as de outros agentes. Para tirar a IA de uma conversa só, use ai_enabled: false no contato.

Parâmetro	Onde	Tipo	Obrigatório	Descrição
agent_id	caminho	UUID	sim	ID do agente.
active	corpo	booleano	sim	true liga; false desliga.

curl

# Desligar o agente "Vendas" (o agente padrão continua respondendo)
curl -X PATCH https://platform.toptalking.com.br/v1/ai-agents/52da47ff-662a-4292-9961-27a95fc5ddd8 \
  -H "Authorization: Bearer $TOPTALKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

JavaScript

async function ligarAgente(agentId, active) {
  const res = await fetch(`https://platform.toptalking.com.br/v1/ai-agents/${agentId}`, {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ active }),
  });
  const body = await res.json();
  if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  return body;
}

await ligarAgente('52da47ff-662a-4292-9961-27a95fc5ddd8', false);

Python

import os
import requests

agent_id = "52da47ff-662a-4292-9961-27a95fc5ddd8"
res = requests.patch(
    f"https://platform.toptalking.com.br/v1/ai-agents/{agent_id}",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    json={"active": False},
    timeout=30,
)
res.raise_for_status()
agente = res.json()

Resposta 200

O agente atualizado:

{
  "id": "52da47ff-662a-4292-9961-27a95fc5ddd8",
  "object": "ai_agent",
  "name": "Vendas",
  "description": "Qualifica leads e apresenta produtos e promoções.",
  "active": false,
  "is_default": false,
  "tone": "descontraido",
  "strict_mode": true,
  "created_at": "2026-06-18T16:30:00Z",
  "updated_at": "2026-11-11T16:45:12Z"
}

Erros

HTTP	code	Quando acontece
400	missing_field	Faltou active.
400	invalid_json, invalid_field	Corpo inválido ou active não é true/false.
403	read_only_key	Chave somente leitura.
404	resource_not_found	O agente não existe ou é de outra organização.

400 missing_field

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_field",
    "message": "Informe `active` (true ou false).",
    "param": "active",
    "request_id": "req_6f1d2c3b4a5e"
  }
}

Agente e IA por conversa

O agente e a IA de cada conversa são campos do contato. Use PATCH /contacts/{contact_id}:

PATCH/v1/contacts/{contact_id}

Corpo	Efeito
{ "ai_agent_id": "<id do agente>" }	Esta conversa passa a ser atendida por este agente.
{ "ai_agent_id": null }	Volta para o agente padrão.
{ "ai_enabled": false }	Desliga a IA só nesta conversa (para um humano assumir).
{ "ai_enabled": true }	Religa a IA nesta conversa.

curl

# Passar a conversa para o agente "Vendas"
curl -X PATCH https://platform.toptalking.com.br/v1/contacts/3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60 \
  -H "Authorization: Bearer $TOPTALKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ai_agent_id": "52da47ff-662a-4292-9961-27a95fc5ddd8" }'

# Um humano vai assumir: desligar a IA e atribuir à Carla
curl -X PATCH https://platform.toptalking.com.br/v1/contacts/3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60 \
  -H "Authorization: Bearer $TOPTALKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ai_enabled": false, "assigned_to": "4083deb8-f96e-4093-8598-ebdd4dee786b" }'

JavaScript

const contactId = '3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60';
const res = await fetch(`https://platform.toptalking.com.br/v1/contacts/${contactId}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}`,
    'Content-Type': 'application/json',
  },
  // Um humano vai assumir: desliga a IA e atribui à Carla
  body: JSON.stringify({ ai_enabled: false, assigned_to: '4083deb8-f96e-4093-8598-ebdd4dee786b' }),
});
const contato = await res.json();

Python

import os
import requests

contact_id = "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60"
res = requests.patch(
    f"https://platform.toptalking.com.br/v1/contacts/{contact_id}",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    json={"ai_agent_id": "52da47ff-662a-4292-9961-27a95fc5ddd8"},  # None = agente padrão
    timeout=30,
)
res.raise_for_status()
contato = res.json()

A resposta 200 é o contato atualizado. Um ai_agent_id que não é agente da organização responde 400 invalid_field (param: "ai_agent_id").