Skip to content
CognizyCognizyHelp
Sign in
In this area

SDK for JavaScript and TypeScript

Install @cognizy/sdk, talk to the AI, stream the reply, handle errors and send email and WhatsApp straight from your system.

Updated on November 12, 2026

On this page

@cognizy/sdk is the official TypeScript client for the public API. It runs on Node 18 or newer and in modern browsers, but the key must always stay on the server.

bash
npm install @cognizy/sdk

Quick start

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

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

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

const { reply } = await cognizy.messages.send({
  conversationId: conversation.id,
  message: 'How do I exchange a product?',
})
console.log(reply?.body)

externalId is the customer's id in your system: the first call creates the contact and the next ones reuse it.

Many customers in your product (B2B2C)

If your product serves several companies, send the account field so Cognizy groups conversations by company (it shows as a badge in the inbox and as a filter):

typescript
await cognizy.conversations.create({
  contact: { externalId: 'customer-42', name: 'Maria Souza' },
  account: { externalId: 'store-456', name: 'Example Store', source: 'my-saas', metadata: { plan: 'pro' } },
})

Streaming replies

typescript
for await (const event of cognizy.messages.stream({ conversationId: conversation.id, message: 'Tell me something new' })) {
  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)
}

Direct email and WhatsApp

For messages your system triggers (order shipped, password reset, invoice), without opening an inbox conversation. They need the email:send and whatsapp:send permissions.

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

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

Outside the 24 h conversation window, WhatsApp only accepts a Meta-approved template. The status of each send comes from cognizy.email.get(id) and cognizy.whatsapp.get(id) or from the email.message.status and whatsapp.message.status webhooks.

Errors

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

try {
  await cognizy.messages.send({ conversationId, message: 'hi' })
} catch (err) {
  if (err instanceof RateLimitError) await sleep(err.retryAfterSeconds ?? 60)
  else if (err instanceof QuotaExceededError) notifyTeam('Monthly call quota is used up')
  else if (err instanceof AuthError) rotateKey()
  else if (err instanceof CognizyError) console.error(err.status, err.code, err.message)
}

EmailQuotaExhaustedError is different: the plan's emails and the wallet balance are both spent. Waiting won't fix it; only new credit will.

Verifying webhooks

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

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

Details in Receive events by webhook.

What the SDK covers

Agents, conversations, messages (with streaming), direct email and WhatsApp, and webhook verification. Call the rest of the API (contacts, knowledge base, tasks, scheduling, sales, funnels…) with fetch, using the same header. The reference shows the example for every route.

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: 'New title' }),
})

All guides