API Reference

Complete reference documentation for the Chat SDK React components, hooks, and types.

Components
Hooks
Types
Interfaces

Components

CyborgProvider

The main provider component that wraps your application and manages chat state.

Signature:

tsx

function CyborgProvider(props: CyborgProviderProps): JSX.Element

Props:

typescript

interface CyborgProviderProps {
  config: CyborgConfig;   // Required: SDK configuration
  children: ReactNode;    // Required: Child components
}

Returns: JSX.Element (Chat context provider and UI)

Example:

tsx

import { CyborgProvider } from '@cyborg-sdk/react';

function App() {
  return (
    <CyborgProvider config={{ publishableKey: 'YOUR_API_KEY' }}>
      <YourApp />
    </CyborgProvider>
  );
}

Features:

Manages chat state (messages, loading, errors)
Provides dual contexts: CyborgChatContext and CyborgContext
Automatically renders chat UI
Persists conversation IDs to localStorage
Handles SSE streaming from backend
Manages tool execution lifecycle

Related Documentation: CyborgProvider Guide

Hooks

useChat

Access chat state and methods from any component within CyborgProvider.

Signature:

tsx

function useChat(): CyborgChatContextValue

Returns:

typescript

interface CyborgChatContextValue {
  messages: Message[];
  isLoading: boolean;
  error: Error | null;
  conversationId: string | null;
  isOpen: boolean;
  hasUniqueIdentifier: boolean;
  isLoadingConversation: boolean;
  sendMessage: (content: string) => Promise<void>;
  clearMessages: () => void;
  startNewConversation: () => void;
  loadConversation: (conversationId: string) => Promise<void>;
  listConversations: () => Promise<ConversationSummary[]>;
  openChat: () => void;
  closeChat: () => void;
  triggerPrompt: (prompt: string, options?: TriggerPromptOptions) => Promise<void>;
}

Example:

tsx

import { useChat } from '@cyborg-sdk/react';

function MyComponent() {
  const { messages, sendMessage, isLoading, triggerPrompt } = useChat();

  return (
    <div>
      {messages.map(msg => (
        <div key={msg.id}>{msg.content}</div>
      ))}
      <button onClick={() => sendMessage('Hello')} disabled={isLoading}>
        Send
      </button>
    </div>
  );
}

Throws:

Error if used outside of CyborgProvider

Related Documentation: useChat Hook Guide

useCyborg

Signature:

tsx

function useCyborg(options?: UseCyborgOptions): UseCyborgReturn

Parameters:

typescript

interface UseCyborgOptions {
  context?: CyborgContext;
  instructions?: string;
  tools?: ToolDefinition[];
  suggestedPrompts?: string[];
}

Returns:

typescript

interface UseCyborgReturn {
  setContext: (data: CyborgContext) => void;
  setInstructions: (instructions: string) => void;
  registerTool: (tool: ToolDefinition) => void;
  setSuggestedPrompts: (prompts: string[]) => void;
  setTriggerPrompt: (prompt: string, options?: TriggerPromptOptions) => void;
}

Example:

tsx

import { useCyborg } from '@cyborg-sdk/react';

function ProductPage({ product }) {
  useCyborg({
    context: {
      page: 'product',
      productId: product.id,
      productName: product.name
    },
    instructions: 'Help users understand this product.',
    tools: [{
      name: 'addToCart',
      description: 'Add the product to cart',
      parameters: {
        type: 'object',
        properties: {
          quantity: { type: 'number' }
        },
        required: ['quantity']
      },
      handler: async ({ quantity }) => {
        await cart.add(product.id, quantity);
        return { success: true };
      }
    }],
    suggestedPrompts: ['What are the features?', 'Compare with alternatives']
  });

  return <ProductDetails product={product} />;
}

Related Documentation: useCyborg Hook Guide

Types

CyborgConfig

Configuration object for CyborgProvider.

Definition:

typescript

interface CyborgConfig {
  publishableKey: string;
  apiUrl?: string;
  debug?: boolean;
  zIndex?: number;
  maxToolResultSizeKb?: number;
  initialContext?: CyborgContext;
  globalInstructions?: string;
  uniqueIdentifier?: string;
  theme?: 'auto' | 'light' | 'dark';
  suggestedPrompts?: string[];
}

Properties:

Property	Type	Required	Default	Description
`publishableKey`	string	Yes	-	Publishable key for authentication
`apiUrl`	string	No	`https://api.cyborgsdk.dev/api/v1`	Custom API endpoint
`debug`	boolean	No	`false`	Enable debug logging
`zIndex`	number	No	`2147483647`	Z-index for chat widget
`maxToolResultSizeKb`	number	No	`100`	Max tool result size in KB
`initialContext`	CyborgContext	No	-	Base context always present
`globalInstructions`	string	No	-	Global AI behavior instructions
`uniqueIdentifier`	string	No	-	User ID for conversation history
`theme`	`'auto' \| 'light' \| 'dark'`	No	`'auto'`	Theme mode
`suggestedPrompts`	string[]	No	-	Default suggested prompts

CyborgContext

Key-value data about the current state.

Definition:

typescript

type CyborgContext = Record<string, unknown>;

Example:

typescript

const context: CyborgContext = {
  page: 'dashboard',
  userId: 'user123',
  metrics: {
    revenue: 45000,
    orders: 127
  }
};

Message

Represents a chat message.

Definition:

typescript

interface Message {
  id: string;
  content: string;
  role: 'user' | 'assistant' | 'system' | 'tool';
  timestamp: Date;
  toolCallId?: string;
  metadata?: Record<string, unknown>;
}

Properties:

Property	Type	Required	Description
`id`	string	Yes	Unique identifier (UUID)
`content`	string	Yes	Message text
`role`	`'user' \| 'assistant' \| 'system' \| 'tool'`	Yes	Who sent the message
`timestamp`	Date	Yes	When message was created
`toolCallId`	string	No	ID of the tool call (for tool role)
`metadata`	`Record<string, unknown>`	No	Additional message metadata

ToolDefinition

Definition of a tool the AI can execute.

Definition:

typescript

interface ToolDefinition {
  name: string;
  description: string;
  parameters: ToolParameter;
  handler: (params: any) => Promise<any>;
  timeout?: number;
}

Properties:

Property	Type	Required	Default	Description
`name`	string	Yes	-	Unique tool identifier
`description`	string	Yes	-	What the tool does (shown to AI)
`parameters`	ToolParameter	Yes	-	JSON Schema-like parameter definition
`handler`	function	Yes	-	Function to execute
`timeout`	number	No	`30000`	Timeout in milliseconds

ToolParameter

JSON Schema-like parameter definition.

Definition:

typescript

interface ToolParameter {
  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
  description?: string;
  enum?: string[];
  properties?: Record<string, ToolParameter>;
  required?: string[];
  items?: ToolParameter;
}

Example:

typescript

const parameters: ToolParameter = {
  type: 'object',
  properties: {
    title: {
      type: 'string',
      description: 'Ticket title'
    },
    priority: {
      type: 'string',
      enum: ['low', 'medium', 'high'],
      description: 'Priority level'
    },
    tags: {
      type: 'array',
      items: { type: 'string' }
    }
  },
  required: ['title', 'priority']
};

TriggerPromptOptions

Options for the triggerPrompt function.

Definition:

typescript

interface TriggerPromptOptions {
  startNew?: boolean;
  instruction?: string;
}

Properties:

Property	Type	Required	Default	Description
`startNew`	boolean	No	`true`	Whether to start a new conversation
`instruction`	string	No	-	Additional instruction for this prompt

ConversationSummary

Summary of a conversation for listing purposes.

Definition:

typescript

interface ConversationSummary {
  id: string;
  title?: string;
  createdAt: Date;
  updatedAt: Date;
}

UseCyborgOptions

Options for the useCyborg hook.

Definition:

typescript

interface UseCyborgOptions {
  context?: CyborgContext;
  instructions?: string;
  tools?: ToolDefinition[];
  suggestedPrompts?: string[];
}

UseCyborgReturn

Return value of the useCyborg hook.

Definition:

typescript

interface UseCyborgReturn {
  setContext: (data: CyborgContext) => void;
  setInstructions: (instructions: string) => void;
  registerTool: (tool: ToolDefinition) => void;
  setSuggestedPrompts: (prompts: string[]) => void;
  setTriggerPrompt: (prompt: string, options?: TriggerPromptOptions) => void;
}

Interfaces

Complete Type Exports

The following types are exported from the main package:

tsx

import {
  // Components
  CyborgProvider,

  // Hooks
  useChat,
  useCyborg,

  // Types
  CyborgConfig,
  CyborgContext,
  Message,
  CyborgChatContextValue,
  UseCyborgOptions,
  UseCyborgReturn,
  ConversationSummary,
  TriggerPromptOptions,
  ToolDefinition,
  ToolParameter,
  ComputedContextData,

  // Component - low-level
  ToolCallBadge,
} from '@cyborg-sdk/react';

Error Handling

Error Types

Errors are standard JavaScript Error objects:

typescript

const { error } = useChat();

if (error instanceof Error) {
  console.error('Chat error:', error.message);
}

Common Error Messages

Message	Cause	Solution
"useChat must be used within a CyborgProvider"	Hook used outside provider	Move hook usage inside CyborgProvider
"useCyborg must be used within a CyborgProvider"	Hook used outside provider	Move hook usage inside CyborgProvider
"HTTP error! status: 401"	Invalid or missing API key	Check API key in config
"HTTP error! status: 403"	API key doesn't have permission	Verify key permissions
"HTTP error! status: 500"	Backend server error	Check backend logs
"Tool execution timeout"	Tool handler took too long	Increase timeout or optimize handler

Streaming Response Format

The SDK expects SSE (Server-Sent Events) format from the backend:

data: {"type":"token","fullContent":"Hello"}

data: {"type":"token","fullContent":"Hello world"}

data: {"type":"tool_call","toolCalls":[{"id":"tc_123","toolName":"createTicket","parameters":{}}]}

data: {"type":"done","metadata":{"model":"claude-3.5-sonnet"}}

Expected Response Headers:

Content-Type: text/event-stream
X-Conversation-Id: <conversation-id> (optional, for new conversations)

Peer Dependencies

The SDK requires the following packages to be installed:

json

{
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

Build Targets

The SDK is built for the following environments:

JavaScript Version: ES2020
Module Formats:
- CommonJS (CJS) - dist/index.js
- ECMAScript Modules (ESM) - dist/index.mjs
TypeScript Definitions: dist/index.d.ts

Browser Support

Minimum browser versions:

Browser	Version	Notes
Chrome	90+	Full support
Firefox	88+	Full support
Safari	14+	Full support
Edge	90+	Full support

Requires browser support for:

ES2020 JavaScript
Fetch API
LocalStorage API
Web Crypto API (for UUID generation)

Package Information

Name: @cyborg-sdk/react
Latest Version: 0.1.0
License: MIT
Repository: GitHub

Next Steps

Installation - Get started
CyborgProvider - Main component
useChat Hook - Access chat state
useCyborg Hook - Register context and tools
Tool Calling Guide - Tool examples

API Reference ​

Table of Contents ​

Components ​

CyborgProvider ​

Hooks ​

useChat ​

useCyborg ​

Types ​

CyborgConfig ​

CyborgContext ​

Message ​

ToolDefinition ​

ToolParameter ​

TriggerPromptOptions ​

ConversationSummary ​

UseCyborgOptions ​

UseCyborgReturn ​

Interfaces ​

Complete Type Exports ​

Error Handling ​

Error Types ​

Common Error Messages ​

Streaming Response Format ​

Peer Dependencies ​

Build Targets ​

Browser Support ​

Package Information ​

Next Steps ​

API Reference

Table of Contents

Components

CyborgProvider

Hooks

useChat

useCyborg

Types

CyborgConfig

CyborgContext

Message

ToolDefinition

ToolParameter

TriggerPromptOptions

ConversationSummary

UseCyborgOptions

UseCyborgReturn

Interfaces

Complete Type Exports

Error Handling

Error Types

Common Error Messages

Streaming Response Format

Peer Dependencies

Build Targets

Browser Support

Package Information

Next Steps