Primeira chamada à API

A API pública do Cognizy é REST com JSON. Com ela, o seu sistema lê e altera conversas, contatos, negócios, tarefas, a base de conhecimento e o resto do que a chave permitir. A referência completa, com cada rota, fica em Referência da API.

1. Crie a chave

No Cognizy, abra Configurações › Integrações › API e webhooks e clique em Nova chave. Escolha:

• Ambiente: sandbox (cgz_test_…) para testar, produção (cgz_live_…) para valer.
• Permissões: marque só os módulos e as ações que a integração precisa. Uma chave sem permissão autentica, mas não chama nada.

A chave aparece uma vez só. Guarde num cofre de segredos ou numa variável de ambiente, nunca no código nem no navegador.

2. Faça a primeira chamada

Toda chamada leva a chave no cabeçalho Authorization. A chave já diz de qual empresa são os dados: você nunca envia o id da organização.

export COGNIZY_API_KEY="cole-a-chave-aqui"

curl https://api.cognizy.ai/api/v1/public/agents \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

A resposta lista os agentes de IA da empresa. Essa rota precisa da permissão agents:read.

3. Ou use o SDK (JavaScript e TypeScript)

npm install @cognizy/sdk

import { Cognizy } from '@cognizy/sdk'

const cognizy = new Cognizy({ apiKey: process.env.COGNIZY_API_KEY! })

// Abre uma conversa ligada a um cliente do seu sistema (externalId)
const conversation = await cognizy.conversations.create({
  contact: { externalId: 'cliente-42', name: 'Maria Souza', email: 'maria@example.com' },
})

// Manda uma mensagem e recebe a resposta da IA
const { reply } = await cognizy.messages.send({
  conversationId: conversation.id,
  message: 'Qual é o horário de vocês?',
})
console.log(reply?.body)

O SDK cobre agentes, conversas, mensagens (com streaming), e-mail e WhatsApp diretos e a verificação de webhooks. O resto da API você chama com fetch, com o mesmo cabeçalho. Veja o guia do SDK.

Limites

• Cada chave faz até 60 chamadas por minuto e 1.000 por hora.
• A empresa tem uma cota mensal de chamadas, que depende do plano.
• Toda resposta traz X-RateLimit-Remaining-Minute, X-RateLimit-Remaining-Hour e X-Quota-Remaining-Month.
• Passou do limite: 429 com code: "RATE_LIMITED" e o cabeçalho Retry-After (em segundos). Passou da cota do mês: 429 com code: "QUOTA_EXCEEDED".

Paginação

• Por página (conversas, contatos, tarefas, campanhas, bases): ?page=1&limit=25. A resposta traz data, page, limit e total.
• Por cursor (mensagens e listas por ordem de tempo): ?cursor=…&limit=50. A resposta traz data, nextCursor e hasMore.

O limit vai de 1 a 100.

Repetir sem duplicar

Em POST e PATCH, mande o cabeçalho Idempotency-Key com um valor seu (um UUID, por exemplo). Se a rede cair e você repetir com a mesma chave em até 24 h, a API devolve a mesma resposta sem executar de novo.

curl -X POST https://api.cognizy.ai/api/v1/public/conversations \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"contact":{"externalId":"cliente-42","name":"Maria Souza"}}'

Erros

Os erros têm sempre o mesmo formato:

{ "statusCode": 404, "code": "not_found", "message": "Conversation not found" }

Ações que pedem aprovação

Algumas escritas que chegam ao cliente (agendar, cancelar, mandar mensagem, lançar campanha) não executam na hora: respondem 202 com o pedido. Um dono ou administrador aprova em Para revisar ou na aba Aprovações de IA de API e webhooks. Na referência, essas rotas têm o selo "Pede aprovação".