Pular para o conteúdo
CognizyCognizyAjuda
Entrar
Nesta área

SDK para JavaScript e TypeScript

Instale o @cognizy/sdk, converse com a IA, receba a resposta em streaming, trate os erros e mande e-mail e WhatsApp direto do seu sistema.

Atualizado em 12 de novembro de 2026

Neste artigo

O @cognizy/sdk é o cliente oficial da API pública em TypeScript. Funciona no Node 18 ou mais novo e em navegadores modernos, mas a chave deve ficar sempre no servidor.

bash
npm install @cognizy/sdk

Começo rápido

typescript
import { Cognizy } from '@cognizy/sdk'

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

const conversation = await cognizy.conversations.create({
  contact: { externalId: 'cliente-42', name: 'Maria Souza', email: 'maria@example.com' },
})

const { reply } = await cognizy.messages.send({
  conversationId: conversation.id,
  message: 'Como faço para trocar um produto?',
})
console.log(reply?.body)

O externalId é o id do cliente no seu sistema: a primeira chamada cria o contato e as seguintes reaproveitam.

Vários clientes no seu produto (B2B2C)

Se o seu produto atende várias empresas, mande o campo account para o Cognizy agrupar as conversas por empresa (aparece como selo na caixa de entrada e como filtro):

typescript
await cognizy.conversations.create({
  contact: { externalId: 'cliente-42', name: 'Maria Souza' },
  account: { externalId: 'loja-456', name: 'Loja Exemplo', source: 'meu-saas', metadata: { plano: 'pro' } },
})

Resposta em streaming

typescript
for await (const event of cognizy.messages.stream({ conversationId: conversation.id, message: 'Me conte uma novidade' })) {
  if (event.type === 'token') process.stdout.write(event.token)
  if (event.type === 'done') console.log('\n', event.fullText)
  if (event.type === 'error') console.error(event.code, event.message)
}

E-mail e WhatsApp diretos

Para mensagens que o seu sistema dispara (pedido enviado, troca de senha, cobrança), sem abrir conversa na caixa de entrada. Precisam das permissões email:send e whatsapp:send.

typescript
await cognizy.email.send({
  to: 'maria@example.com',
  templateId: 'tpl_123',
  variables: { 'contact.firstName': 'Maria', 'order.id': '#1001' },
  idempotencyKey: 'pedido-1001-enviado',
})

await cognizy.whatsapp.send({
  to: '+5511999999999',
  type: 'TEMPLATE',
  template: { name: 'order_update', language: 'pt_BR', variables: ['Maria', '#1001'] },
})

Fora da janela de 24 h da conversa, o WhatsApp só aceita modelo aprovado pela Meta. A situação de cada envio sai em cognizy.email.get(id) e cognizy.whatsapp.get(id) ou nos webhooks email.message.status e whatsapp.message.status.

Erros

typescript
import { AuthError, CognizyError, QuotaExceededError, RateLimitError } from '@cognizy/sdk'

try {
  await cognizy.messages.send({ conversationId, message: 'oi' })
} catch (err) {
  if (err instanceof RateLimitError) await espera(err.retryAfterSeconds ?? 60)
  else if (err instanceof QuotaExceededError) avisaEquipe('Cota de chamadas do mês acabou')
  else if (err instanceof AuthError) trocaChave()
  else if (err instanceof CognizyError) console.error(err.status, err.code, err.message)
}

EmailQuotaExhaustedError é diferente: acabaram os e-mails do plano e o saldo da carteira. Esperar não resolve; só crédito novo.

Verificar webhooks

typescript
import { verifyWebhookSignature } from '@cognizy/sdk'

const ok = verifyWebhookSignature({ secret, body: corpoCru, header: req.headers['x-cognizy-signature'] })

Detalhes no guia Receber eventos por webhook.

O que o SDK cobre

Agentes, conversas, mensagens (com streaming), e-mail e WhatsApp diretos e a verificação de webhooks. O resto da API (contatos, base de conhecimento, tarefas, agenda, vendas, funis…) você chama com fetch, com o mesmo cabeçalho. A referência mostra o exemplo de cada rota.

typescript
const res = await fetch(`https://api.cognizy.ai/api/v1/public/tasks/${taskId}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.COGNIZY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({ title: 'Título novo' }),
})

Tutoriais da central

Todos os guias