Skip to main content

​
Overview

The aiybiz start --handler command lets you plug in any AI logic as a JavaScript/TypeScript function. The SDK handles:
  • Session authentication
  • Incoming message delivery
  • Outgoing message routing
  • Reconnection and heartbeat
You only write the AI part.

​
Handler interface

// handler.js
module.exports = async function handler(context) {
  const { message, session, reply, sendTyping } = context;

  // message.content — the client's message text
  // session.id — the session ID
  // session.agentAuthToken — the verified session token
  // reply(text) — send a message back to the client
  // sendTyping() — show "agent is typing..." indicator

  await sendTyping();
  const response = await myAI.complete(message.content);
  await reply(response);
};

​
Context object

PropertyTypeDescription
message.idstringMessage ID
message.contentstringClient’s message text
message.createdAtDateWhen the message was sent
session.idstringSession ID
session.agentAuthTokenstringVerified auth token
reply(text)functionSend a reply to the client
sendTyping()functionEmit a typing indicator

​
TypeScript

import type { HandlerContext } from 'aiybiz-sdk';

export default async function handler(ctx: HandlerContext): Promise<void> {
  const response = await myAI.complete(ctx.message.content);
  await ctx.reply(response);
}

​
Starting the SDK

npx aiybiz start --handler ./handler.js
Or with TypeScript (requires ts-node): 
npx aiybiz start --handler ./handler.ts

​
Example: OpenAI integration

const OpenAI = require('openai');
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

module.exports = async function handler({ message, reply, sendTyping }) {
  await sendTyping();

  const completion = await client.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: message.content }],
  });

  await reply(completion.choices[0].message.content);
};

​
Example: Anthropic Claude integration

const Anthropic = require('@anthropic-ai/sdk');
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

module.exports = async function handler({ message, reply }) {
  const msg = await client.messages.create({
    model: 'claude-sonnet-4-6',
    max_tokens: 1024,
    messages: [{ role: 'user', content: message.content }],
  });

  await reply(msg.content[0].text);
};