@convokit/server

ConvoKit is currently in early access. The waitlist is live — join at convokit.dev to get early access.

Server SDK for ConvoKit — send AI chat messages from your server using your secret API key. The key never leaves your backend, making this more secure than using a public key in the browser.

Website: convokit.dev

Installation

npm install @convokit/server

Usage

const { createClient } = require('@convokit/server');

const client = createClient(process.env.CONVOKIT_SECRET_KEY); // sk_live_...

// New conversation
const { reply, conversation_id } = await client.chat({
  message: 'What are your support hours?',
});
console.log(reply);

// Follow-up in the same thread
const { reply: reply2 } = await client.chat({
  message: 'And on weekends?',
  conversationId: conversation_id,
});
console.log(reply2);

TypeScript

import { createClient, type ChatOptions, type ChatResponse } from '@convokit/server';

const client = createClient({ apiKey: process.env.CONVOKIT_SECRET_KEY! });

const res: ChatResponse = await client.chat({
  message: 'Hello',
  instanceId: 'my-bot',
  chatHistory: [],
});

Conversation history

Pass previous messages so the AI has context:

const { reply } = await client.chat({
  message: 'What did I just ask?',
  chatHistory: [
    { role: 'user', content: 'What are your support hours?' },
    { role: 'assistant', content: 'We are open 9am–5pm Monday to Friday.' },
  ],
});

Format: { role: 'user' | 'assistant' | 'system', content: string }.

When you have a conversationId, you can omit chatHistory — the backend already has the thread.

Options

| Option | Required | Description | |--------|----------|-------------| | message | Yes | The user message to send | | conversationId | No | Use for follow-up messages in the same thread | | widgetId | No | Identifier for grouping (e.g. bot name, channel) | | chatHistory | No | Previous messages for context |

Response

| Field | Description | |-------|-------------| | reply | AI reply text | | conversation_id | Pass this in the next message to continue the thread | | usage | Token usage — prompt_tokens, completion_tokens, total_tokens |

Security

• Use a secret key (sk_live_...) on your server only. Never expose it in browser or client-side code.
• For browser / widget use, use a public key (pk_live_...) with the @convokit/widget package.

Early access

ConvoKit is in early access. Get your API keys and configure your AI at convokit.dev.

The waitlist is live — join now to get early access.

License

MIT