Quickstart Guide

Get started with DialogueDB in under 5 minutes. This guide will walk you through creating your first conversation and sending messages.

Prerequisites

Before you begin, you'll need:

• A DialogueDB API token
• An HTTP client (cURL, Postman, or your preferred programming language)
• The API base URL: https://api.dialoguedb.com

TIP

Don't have an API token yet? Contact your administrator or visit the Authentication guide for details on obtaining one.

Step 1: Create Your First Dialogue

Create a new dialogue with an initial message:

cURL

curl -X POST https://api.dialoguedb.com/dialogue \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "role": "user",
      "content": "Hello! Can you help me understand DialogueDB?"
    }
  }'

TypeScript

const response = await fetch('https://api.dialoguedb.com/dialogue', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: {
      role: 'user',
      content: 'Hello! Can you help me understand DialogueDB?'
    }
  })
});

const dialogue = await response.json();
console.log('Dialogue ID:', dialogue.id);

DialogueDB SDK

import { DialogueDB } from 'dialogue-db';

const client = new DialogueDB({
  apiKey: 'YOUR_API_KEY'
});

const dialogue = await client.dialogues.create({
  message: {
    role: 'user',
    content: 'Hello! Can you help me understand DialogueDB?'
  }
});

console.log('Dialogue ID:', dialogue.id);

Response:

{
  "id": "01KACE6RAZKQ93354SF18CJHHC",
  "requestId": "cf7cbe59-9882-4539-a760-7eb68fbb6275",
  "tags": [],
  "totalMessages": 1,
  "threadCount": 0,
  "lastMessageCreated": "2025-11-18T21:33:49.795Z",
  "metadata": {},
  "created": "2025-11-18T21:33:49.899Z",
  "modified": "2025-11-18T21:33:49.899Z",
  "messages": [
    {
      "dialogueId": "01KACE6RAZKQ93354SF18CJHHC",
      "id": "01KACE6RB06C5E1CCJKG8TTJ5B",
      "role": "user",
      "name": "greg",
      "preview": "Hello! Can you help me understand DialogueDB?",
      "content": "Hello! Can you help me understand DialogueDB?",
      "created": "2025-11-18T21:33:49.795Z",
      "metadata": {},
      "tags": []
    }
  ],
  "state": {}
}

TIP

Save the dialogue id - you'll need it to add more messages to this conversation!

Step 2: Add a Message to the Dialogue

Add an assistant response to the conversation:

cURL

curl -X POST https://api.dialoguedb.com/dialogue/dlg_abc123xyz/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "role": "assistant",
      "content": "Of course! DialogueDB is a conversation management API that helps you store and retrieve chat histories for AI applications."
    }
  ]'

TypeScript

const messageResponse = await fetch(
  `https://api.dialoguedb.com/dialogue/${dialogue.id}/messages`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      role: 'assistant',
      content: 'Of course! DialogueDB is a conversation management API that helps you store and retrieve chat histories for AI applications.'
    })
  }
);

const message = await messageResponse.json();
console.log('Message ID:', message.id);

DialogueDB SDK

const message = await client.messages.create(dialogue.id, {
  role: 'assistant',
  content: 'Of course! DialogueDB is a conversation management API that helps you store and retrieve chat histories for AI applications.'
});

console.log('Message ID:', message.id);

Response:

[
  {
    "dialogueId": "01KAD6TA5XHAHESWVJ8TMWJQAW",
    "id": "01KAD7FYPBVZBF5J1KVVR9NR8S",
    "role": "assistant",
    "preview": "Of course! DialogueDB is a conversation management API that helps you store and retrieve chat histories for AI applications.",
    "content": "Of course! DialogueDB is a conversation management API that helps you store and retrieve chat histories for AI applications.",
    "created": "2025-11-19T04:55:45.628Z",
    "metadata": {},
    "tags": []
  }
]

Step 3: Retrieve the Conversation

Fetch the dialogue metadata and messages:

cURL

# Get dialogue metadata
curl -X GET https://api.dialoguedb.com/dialogue/01KAD6TA5XHAHESWVJ8TMWJQAW \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get messages
curl -X GET https://api.dialoguedb.com/dialogue/01KAD6TA5XHAHESWVJ8TMWJQAW/messages \
  -H "Authorization: Bearer YOUR_API_KEY"

TypeScript

// Get dialogue metadata
const dialogueResponse = await fetch(
  `https://api.dialoguedb.com/dialogue/${dialogue.id}`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const dialogueData = await dialogueResponse.json();
console.log('Total messages:', dialogueData.totalMessages);

// Get messages
const messagesResponse = await fetch(
  `https://api.dialoguedb.com/dialogue/${dialogue.id}/messages`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const { messages } = await messagesResponse.json();
console.log('Messages:', messages);

DialogueDB SDK

// Get dialogue metadata
const dialogue = await client.dialogues.get(dialogueId);
console.log('Total messages:', dialogue.totalMessages);

// Get messages
const { messages } = await client.messages.list(dialogueId);
console.log('Messages:', messages);

Dialogue Response:

{
  "id": "01KAD6TA5XHAHESWVJ8TMWJQAW",
  "__namespace": "01KAD6DKJTTX0Z470XVCWXZBN8",
  "projectId": "01KAD6R34620P1C5J0M2KRMGRG",
  "requestId": "ddd0a625-0d91-4a41-996a-dcc5d2ea8cc8",
  "status": "active",
  "tags": [],
  "totalMessages": 2,
  "threadCount": 0,
  "lastMessageCreated": "2025-11-19T04:55:45.628Z",
  "metadata": {},
  "metadataLength": 2,
  "metadataSHA256": "RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=",
  "created": "2025-11-19T04:43:56.625Z",
  "modified": "2025-11-19T04:55:45.768Z",
  "messages": [
    {
      "dialogueId": "01KAD6TA5XHAHESWVJ8TMWJQAW",
      "id": "01KAD7FYPBVZBF5J1KVVR9NR8S",
      "role": "assistant",
      "preview": "Of course! DialogueDB is a conversation management API that helps you store and retrieve chat histories for AI applications.",
      "content": "Of course! DialogueDB is a conversation management API that helps you store and retrieve chat histories for AI applications.",
      "created": "2025-11-19T04:55:45.628Z",
      "metadata": {},
      "tags": []
    },
    {
      "dialogueId": "01KAD6TA5XHAHESWVJ8TMWJQAW",
      "id": "01KAD6TA5YCDQ87RMXPHRRJ05C",
      "role": "user",
      "preview": "Hello! Can you help me understand DialogueDB?",
      "content": "Hello! Can you help me understand DialogueDB?",
      "created": "2025-11-19T04:43:56.488Z",
      "metadata": {},
      "tags": []
    }
  ],
  "state": {}
}

Messages Response:

[
  {
    "dialogueId": "01KAD6TA5XHAHESWVJ8TMWJQAW",
    "id": "01KAD7FYPBVZBF5J1KVVR9NR8S",
    "role": "assistant",
    "preview": "Of course! DialogueDB is a conversation management API that helps you store and retrieve chat histories for AI applications.",
    "content": "Of course! DialogueDB is a conversation management API that helps you store and retrieve chat histories for AI applications.",
    "created": "2025-11-19T04:55:45.628Z",
    "metadata": {},
    "tags": []
  },
  {
    "dialogueId": "01KAD6TA5XHAHESWVJ8TMWJQAW",
    "id": "01KAD6TA5YCDQ87RMXPHRRJ05C",
    "role": "user",
    "preview": "Hello! Can you help me understand DialogueDB?",
    "content": "Hello! Can you help me understand DialogueDB?",
    "created": "2025-11-19T04:43:56.488Z",
    "metadata": {},
    "tags": []
  }
]

Step 4: List All Dialogues

Retrieve all conversations in your project:

cURL

curl -X GET "https://api.dialoguedb.com/dialogue?limit=10&order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

TypeScript

const listResponse = await fetch(
  'https://api.dialoguedb.com/dialogue?limit=10&order=desc',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const { items, next } = await listResponse.json();
console.log(`Found ${items.length} dialogues`);

DialogueDB SDK

const { items, next } = await client.dialogues.list({
  limit: 10,
  order: 'desc'
});

console.log(`Found ${items.length} dialogues`);

Congratulations!

You've successfully:

• ✅ Created your first dialogue

• ✅ Added messages to a conversation

• ✅ Retrieved conversation history

• ✅ Listed all dialogues

Next Steps

Now that you've created your first conversation, explore more advanced features:

• Core Concepts - Learn about threads, state, and message management
• Use Cases & Patterns - Common patterns for building conversational apps
• API Reference - Complete API documentation
• Best Practices - Optimization tips and error handling strategies

Common Patterns

Building a Chatbot

// Initialize conversation
const dialogue = await client.dialogues.create({
  message: { role: 'system', content: 'You are a helpful assistant.' }
});

// User sends a message
await client.messages.create(dialogue.id, {
  role: 'user',
  content: userInput
});

// Get AI response (from your LLM)
const aiResponse = await generateResponse(userInput);

// Store AI response
await client.messages.create(dialogue.id, {
  role: 'assistant',
  content: aiResponse
});

// Retrieve full history for context
const conversation = await client.dialogues.get(dialogue.id);

Managing Long Conversations

// Compact conversation to reduce token usage
await client.dialogues.action(dialogue.id, 'compact');

// Or end the conversation
await client.dialogues.action(dialogue.id, 'end');

Creating Threads

// Create a thread linked to a parent dialogue
// Threads are for organizing related sub-conversations or processes
const thread = await client.dialogues.create({
  threadOf: 'dlg_abc123', // ID of parent dialogue
  message: {
    role: 'system',
    content: 'Processing subtask...'
  }
});

Advanced Features

Custom Identifiers

Set your own IDs to match your database records:

const dialogue = await client.dialogues.create({
  id: 'customer_inquiry_12345',  // Your custom ID
  message: {
    id: 'initial_message_001',   // Custom message ID
    role: 'user',
    content: 'Help with billing'
  }
});

Namespace for Multi-Tenancy

Use namespace to isolate data by user or organization:

// Create user-specific dialogue
const dialogue = await client.dialogues.create({
  namespace: `user_${userId}`,
  message: {
    role: 'user',
    content: 'Hello'
  }
});

// List only this user's dialogues
const userDialogues = await client.dialogues.list({
  namespace: `user_${userId}`
});