Examples

Copy-paste examples for common use cases.

Basic Chat Loop

import { createDriftClient } from '@driftos/client';
import OpenAI from 'openai';

const drift = createDriftClient(
  'https://api.driftos.dev/api/v1/embed',
  process.env.DRIFTOS_API_KEY
);

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

async function chat(conversationId: string, userMessage: string) {
  // Route message
  const result = await drift.route(conversationId, userMessage);

  // Get context
  const { system, messages } = await drift.buildPrompt(result.branchId);

  // Call LLM
  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [
      { role: 'system', content: system },
      ...messages,
      { role: 'user', content: userMessage }
    ]
  });

  return {
    reply: response.choices[0].message.content,
    routing: result
  };
}

Express.js API Endpoint

import express from 'express';
import { createDriftClient } from '@driftos/client';
import OpenAI from 'openai';

const app = express();
app.use(express.json());

const drift = createDriftClient(
  'https://api.driftos.dev/api/v1/llm',
  process.env.DRIFTOS_API_KEY
);

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

app.post('/chat', async (req, res) => {
  const { conversationId, message } = req.body;

  try {
    // Route message
    const result = await drift.route(conversationId, message);

    // Get context
    const { system, messages } = await drift.buildPrompt(result.branchId, {
      maxMessages: 10
    });

    // Call LLM
    const response = await openai.chat.completions.create({
      model: 'gpt-4',
      messages: [
        { role: 'system', content: system },
        ...messages,
        { role: 'user', content: message }
      ]
    });

    res.json({
      reply: response.choices[0].message.content,
      routing: {
        action: result.action,
        topic: result.branchTopic
      }
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000);

Custom System Prompt

const result = await drift.route(conversationId, userMessage);

const { system, messages } = await drift.buildPrompt(result.branchId, {
  maxMessages: 15,
  systemPrompt: 'You are a helpful travel assistant specializing in European destinations.'
});

const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [
    { role: 'system', content: system },
    ...messages,
    { role: 'user', content: userMessage }
  ]
});

Streaming Responses

async function chatStream(conversationId: string, userMessage: string) {
  // Route message
  const result = await drift.route(conversationId, userMessage);

  // Get context
  const { system, messages } = await drift.buildPrompt(result.branchId);

  // Stream LLM response
  const stream = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [
      { role: 'system', content: system },
      ...messages,
      { role: 'user', content: userMessage }
    ],
    stream: true
  });

  for await (const chunk of stream) {
    const content = chunk.choices[0]?.delta?.content || '';
    process.stdout.write(content);
  }
}

Error Handling

async function chatWithRetry(conversationId: string, message: string) {
  try {
    const result = await drift.route(conversationId, message);
    const { system, messages } = await drift.buildPrompt(result.branchId);

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

    return response.choices[0].message.content;
  } catch (error) {
    if (error.status === 401) {
      throw new Error('Invalid DriftOS API key');
    }

    if (error.status === 500) {
      // Retry once
      console.log('Retrying...');
      return chatWithRetry(conversationId, message);
    }

    throw error;
  }
}

Switching Between Core and Embed

// Start with Embed for speed
let drift = createDriftClient(
  'https://api.driftos.dev/api/v1/embed',
  process.env.DRIFTOS_API_KEY
);

// Switch to Core for complex conversations
function switchToCore() {
  drift = createDriftClient(
    'https://api.driftos.dev/api/v1/llm',
    process.env.DRIFTOS_API_KEY
  );
}

// Switch to Embed for high-volume
function switchToEmbed() {
  drift = createDriftClient(
    'https://api.driftos.dev/api/v1/embed',
    process.env.DRIFTOS_API_KEY
  );
}

Clear Chat History

Use deleteConversation to implement a "Clear history" button that wipes all branches, messages, and facts for a conversation — both server-side and whatever local cache your app keeps.

async function clearChatHistory(conversationId: string) {
  try {
    const { deletedBranches, deletedMessages, deletedFacts } =
      await drift.deleteConversation(conversationId);

    // Also wipe your local state
    clearLocalConversationState(conversationId);

    return {
      ok: true,
      deletedBranches,
      deletedMessages,
      deletedFacts,
    };
  } catch (err) {
    // Already gone server-side — treat as a no-op
    if ((err as Error).message.includes('not found')) {
      clearLocalConversationState(conversationId);
      return { ok: true, deletedBranches: 0, deletedMessages: 0, deletedFacts: 0 };
    }
    throw err;
  }
}

Dismiss a Single Branch

Use deleteBranch to let the user dismiss a single branch from the UI. All descendant branches cascade — there's no re-parenting.

async function dismissBranch(branchId: string) {
  const { deletedMessages, deletedFacts } = await drift.deleteBranch(branchId);
  console.log(
    `Dismissed branch, removed ${deletedMessages} messages and ${deletedFacts} facts`
  );
}

Next Steps

API Reference - Complete method docs
REST API - Direct HTTP usage
Troubleshooting - Fix issues

Examples

On this page