API / Desenvolvedores

§1 Autenticação

Todas as requisições à API CAMILE exigem autenticação via API Key. Sua chave de API pode ser gerada no painel em Configurações → API Keys.

Inclua a chave no header Authorization no formato Bearer:

# Header de autenticação
Authorization: Bearer cm_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

ⓘ Chaves de API têm acesso total aos recursos da sua conta. Mantenha-as em segredo.

§2 Agentes

GET /v1/agents

Lista todos os agentes da sua conta.

curl -H "Authorization: Bearer cm_sk_xxx" \
  https://api.camile.ia.br/v1/agents

{
  "data": [
    {
      "id": "ag_1234",
      "name": "Agente Suporte",
      "soul": "Profissional",
      "status": "active",
      "created_at": "2026-03-15T10:00:00Z"
    }
  ],
  "total": 1
}

POST /v1/agents

Cria um novo agente.

Parâmetros (body JSON)
name	string	Nome do agente obrigatório
soul_id	string	ID da personalidade obrigatório
language	string	Idioma padrão opcional

curl -X POST -H "Authorization: Bearer cm_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Agente Vendas","soul_id":"sl_5678"}' \
  https://api.camile.ia.br/v1/agents

GET /v1/agents/{id}

Retorna os detalhes de um agente específico.

DELETE /v1/agents/{id}

Remove um agente e todos os seus dados associados.

§3 Conversas

GET /v1/conversations

Lista conversas com suporte a paginação e filtros.

Parâmetros (query)
agent_id	string	Filtrar por agente opcional
status	string	active \| waiting \| closed opcional
limit	number	Máx. por página (default 50) opcional

POST /v1/conversations

Inicia uma nova conversa com um agente.

Parâmetros (body JSON)
agent_id	string	ID do agente obrigatório
channel	string	Canal de origem obrigatório
external_id	string	ID do cliente no seu sistema opcional
metadata	object	Dados adicionais opcional

GET /v1/conversations/{id}/messages

Obtém o histórico de mensagens de uma conversa.

§4 Mensagens

POST /v1/conversations/{id}/messages

Envia uma mensagem em uma conversa existente. O agente responde automaticamente.

Parâmetros (body JSON)
content	string	Texto da mensagem obrigatório
role	string	"user" (padrão) opcional
attachments	array	URLs de arquivos opcional

curl -X POST -H "Authorization: Bearer cm_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"content":"Qual o horário de funcionamento?"}' \
  https://api.camile.ia.br/v1/conversations/cv_1234/messages

§5 Canais

GET /v1/channels

Lista os canais conectados à sua conta.

POST /v1/channels

Conecta um novo canal (WhatsApp, Telegram, Slack).

DELETE /v1/channels/{id}

Desconecta um canal.

§6 Exemplos de Uso

Exemplo 1: Criar agente e iniciar conversa

# 1. Criar agente
curl -X POST https://api.camile.ia.br/v1/agents \
  -H "Authorization: Bearer cm_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Suporte","soul_id":"sl_5678","language":"pt-BR"}'

# 2. Iniciar conversa
curl -X POST https://api.camile.ia.br/v1/conversations \
  -H "Authorization: Bearer cm_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"ag_1234","channel":"api","external_id":"cli_001"}'

# 3. Enviar mensagem
curl -X POST https://api.camile.ia.br/v1/conversations/cv_1234/messages \
  -H "Authorization: Bearer cm_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"content":"Olá, preciso de ajuda!"}'

Exemplo 2: Webhook de mensagens recebidas

Configure uma URL de webhook no painel para receber eventos em tempo real. Payload enviado via POST:

{
  "event": "message.received",
  "data": {
    "conversation_id": "cv_1234",
    "agent_id": "ag_1234",
    "content": "Qual o valor do plano?",
    "role": "user",
    "channel": "whatsapp",
    "timestamp": "2026-05-18T14:30:00Z"
  }
}

Exemplo 3: Erros comuns

# 401 — Não autorizado (API Key inválida ou ausente)
{
  "error": "unauthorized",
  "message": "Invalid or missing API key",
  "status": 401
}

# 429 — Rate limit excedido (máx. 100 req/min)
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Retry after 15 seconds.",
  "status": 429,
  "retry_after": 15
}