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? Create one in your project dashboard or visit the Authentication guide for details on obtaining one.

Installation

If you're using the SDK, install the DialogueDB package:

bash

npm install dialogue-db

Step 1: Create Your First Dialogue

Create a new dialogue with an initial message:

cURLTypeScript (fetch)PythonSDK

bash

curl -X POST https://api.dialoguedb.com/dialogue \
  -H "Authorization: Bearer DIALOGUE_DB_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 DIALOGUE_DB_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);

python

import requests

response = requests.post(
    "https://api.dialoguedb.com/dialogue",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
    json={
        "message": {
            "role": "user",
            "content": "Hello! Can you help me understand DialogueDB?"
        }
    }
)

dialogue = response.json()
print("Dialogue ID:", dialogue["id"])

typescript

import { DialogueDB } from 'dialogue-db';

const db = new DialogueDB({
  apiKey: 'DIALOGUE_DB_API_KEY'
});

const dialogue = await db.createDialogue({
  messages: [{
    role: 'user',
    content: 'Hello! Can you help me understand DialogueDB?'
  }]
});

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

Response:

json

{
  "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",
      "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:

cURLTypeScript (fetch)PythonSDK

bash

curl -X POST https://api.dialoguedb.com/dialogue/dlg_abc123xyz/messages \
  -H "Authorization: Bearer DIALOGUE_DB_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 DIALOGUE_DB_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);

python

response = requests.post(
    f"https://api.dialoguedb.com/dialogue/{dialogue_id}/messages",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
    json={
        "role": "assistant",
        "content": "Of course! DialogueDB is a conversation management API that helps you store and retrieve chat histories for AI applications."
    }
)

message = response.json()
print("Message ID:", message["id"])

typescript

const message = await dialogue.saveMessage({
  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:

json

[
  {
    "dialogueId": "01KAD6TA5XHAHESWVJ8TMWJQAW",
    "id": "01KAD7FYPBVZBF5J1KVVR9NR8S",
    "role": "assistant",
    "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:

cURLTypeScript (fetch)PythonSDK

bash

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

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

typescript

// Get dialogue metadata
const dialogueResponse = await fetch(
  `https://api.dialoguedb.com/dialogue/${dialogue.id}`,
  {
    headers: {
      'Authorization': 'Bearer DIALOGUE_DB_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 DIALOGUE_DB_API_KEY'
    }
  }
);

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

python

# Get dialogue metadata
response = requests.get(
    f"https://api.dialoguedb.com/dialogue/{dialogue_id}",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"}
)
dialogue_data = response.json()
print("Total messages:", dialogue_data["totalMessages"])

# Get messages
response = requests.get(
    f"https://api.dialoguedb.com/dialogue/{dialogue_id}/messages",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"}
)
messages = response.json()
print("Messages:", messages)

typescript

// Get dialogue
const dialogue = await db.getDialogue(dialogueId);
console.log('Total messages:', dialogue.totalMessages);

// Load messages
const messages = await dialogue.loadMessages();
console.log('Messages:', messages);

Dialogue Response:

json

{
  "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",
      "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",
      "content": "Hello! Can you help me understand DialogueDB?",
      "created": "2025-11-19T04:43:56.488Z",
      "metadata": {},
      "tags": []
    }
  ],
  "state": {}
}

Messages Response:

json

[
  {
    "dialogueId": "01KAD6TA5XHAHESWVJ8TMWJQAW",
    "id": "01KAD7FYPBVZBF5J1KVVR9NR8S",
    "role": "assistant",
    "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",
    "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:

cURLTypeScript (fetch)PythonSDK

bash

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

typescript

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

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

python

response = requests.get(
    "https://api.dialoguedb.com/dialogue",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
    params={"limit": 10, "order": "desc"}
)

data = response.json()
print(f"Found {len(data['items'])} dialogues")

typescript

const { items, next } = await db.listDialogues({
  limit: 10,
  order: 'desc'
});

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

Step 5: Store a Memory

Memories let you persist information across dialogues — such as user preferences, facts, or context that should be available long-term.

cURLTypeScript (fetch)PythonSDK

bash

curl -X POST https://api.dialoguedb.com/memory \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "User prefers dark mode",
    "label": "UI Preference",
    "tags": ["preferences"]
  }'

typescript

const response = await fetch('https://api.dialoguedb.com/memory', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    value: 'User prefers dark mode',
    label: 'UI Preference',
    tags: ['preferences']
  })
});

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

python

response = requests.post(
    "https://api.dialoguedb.com/memory",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
    json={
        "value": "User prefers dark mode",
        "label": "UI Preference",
        "tags": ["preferences"]
    }
)

memory = response.json()
print("Memory ID:", memory["id"])

typescript

const memory = await db.createMemory({
  value: 'User prefers dark mode',
  label: 'UI Preference',
  tags: ['preferences']
});

console.log('Memory ID:', memory.id);

// Retrieve the memory later
const retrieved = await db.getMemory(memory.id);
console.log('Value:', retrieved.value);

Memories vs State vs Messages

Memories persist across dialogues and are searchable via semantic search — use for long-term facts and preferences
State is scoped to a single dialogue — use for conversation-specific context
Messages are the actual conversation turns — use for chat history

Learn more in the Memory API and Core Concepts guides.

Congratulations!

You've successfully:

Created your first dialogue
Added messages to a conversation
Retrieved conversation history
Listed all dialogues
Stored a memory

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

typescript

import { DialogueDB } from 'dialogue-db';

const db = new DialogueDB({ apiKey: process.env.DIALOGUE_DB_API_KEY });

// Initialize conversation
const dialogue = await db.createDialogue({
  messages: [{ role: 'system', content: 'You are a helpful assistant.' }]
});

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

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

// Store AI response
await dialogue.saveMessage({
  role: 'assistant',
  content: aiResponse
});

// Retrieve full history for context
const messages = await dialogue.loadMessages();

Managing Long Conversations

cURLSDK

bash

# End the conversation
curl -X POST https://api.dialoguedb.com/dialogue/DIALOGUE_ID/end \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY"

# Compact conversation to reduce token usage
curl -X POST https://api.dialoguedb.com/dialogue/DIALOGUE_ID/compact \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY"

typescript

// End the conversation
await dialogue.end();

// Compact is not yet available in the SDK — use the REST API

Creating Threads

typescript

// Create a thread linked to a parent dialogue
const thread = await dialogue.createThread({
  metadata: { purpose: 'subtask' }
});

// Add messages after creation
await thread.saveMessage({
  role: 'system',
  content: 'Processing subtask...'
});

Advanced Features

Custom Identifiers

Set your own IDs to match your database records:

typescript

const dialogue = await db.createDialogue({
  id: 'customer_inquiry_12345',  // Your custom ID
  messages: [{
    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:

typescript

// Create user-specific dialogue
const dialogue = await db.createDialogue({
  namespace: `user_${userId}`,
  messages: [{
    role: 'user',
    content: 'Hello'
  }]
});

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

Quickstart Guide ​

Prerequisites ​

Installation ​

Step 1: Create Your First Dialogue ​

Step 2: Add a Message to the Dialogue ​

Step 3: Retrieve the Conversation ​

Step 4: List All Dialogues ​

Step 5: Store a Memory ​

Congratulations! ​

Next Steps ​

Common Patterns ​

Building a Chatbot ​

Managing Long Conversations ​

Creating Threads ​

Advanced Features ​

Custom Identifiers ​

Namespace for Multi-Tenancy ​

Quickstart Guide

Prerequisites

Installation

Step 1: Create Your First Dialogue

Step 2: Add a Message to the Dialogue

Step 3: Retrieve the Conversation

Step 4: List All Dialogues

Step 5: Store a Memory

Congratulations!

Next Steps

Common Patterns

Building a Chatbot

Managing Long Conversations

Creating Threads

Advanced Features

Custom Identifiers

Namespace for Multi-Tenancy