Skip to content

Conversation Backend

createHttpConversationBackend creates a ConversationBackend that communicates with the conversation API via HTTP. The backend provides methods for listing, creating, messaging, and deleting conversations.

Import

import { createHttpConversationBackend } from "@modernpath/agent-ui-react";

Options

interface CreateHttpConversationBackendOptions {
  /**
   * Base URL for the conversation API.
   * @default ""
   */
  baseUrl?: string;

  /**
   * Path prefix for conversation endpoints.
   * @default "/api/conversations"
   */
  pathPrefix?: string;

  /**
   * Function that returns headers to include in every request.
   * Called on each request to support token refresh.
   */
  getHeaders?: () => Record<string, string>;
}

Return Value

Returns a ConversationBackend object:

interface ConversationBackend {
  /** List all conversations, ordered by updatedAt descending */
  listConversations: () => Promise<ConversationUI[]>;

  /** Create a new conversation */
  createConversation: (params: {
    agentName?: string;
    parameters?: Record<string, unknown>;
  }) => Promise<ConversationUI>;

  /** Get messages for a conversation */
  getMessages: (conversationId: string) => Promise<ConversationMessageUI[]>;

  /** Send a message and receive the assistant response */
  sendMessage: (
    conversationId: string,
    message: {
      content: string;
      agentName?: string;
      parameters?: Record<string, unknown>;
    }
  ) => Promise<ConversationMessageUI>;

  /** Delete a conversation */
  deleteConversation: (conversationId: string) => Promise<void>;
}

API Endpoints

The backend communicates with the following endpoints:

Method Endpoint Description
GET {pathPrefix} List all conversations
POST {pathPrefix} Create a new conversation
GET {pathPrefix}/{id}/messages Get messages for a conversation
POST {pathPrefix}/{id}/messages Send a message and receive a response
DELETE {pathPrefix}/{id} Delete a conversation

Create Conversation Request

{
  "agentName": "qa-chat",
  "parameters": { "language": "en" }
}

Send Message Request

{
  "content": "What is the recommended temperature?",
  "agentName": "qa-chat",
  "parameters": {}
}

Send Message Response

{
  "role": "assistant",
  "content": "The recommended indoor temperature is 21-23 degrees Celsius.",
  "timestamp": "2026-02-25T10:30:05.200Z",
  "traceId": "trace-abc-123",
  "metadata": { "tokensUsed": 150 }
}

Usage

Basic Conversation Backend

import {
  createHttpConversationBackend,
  ConversationPanel,
} from "@modernpath/agent-ui-react";

const conversationBackend = createHttpConversationBackend({
  baseUrl: "https://api.example.com",
  getHeaders: () => ({
    Authorization: `Bearer ${getToken()}`,
  }),
});

function ConversationsPage() {
  return (
    <ConversationPanel
      backend={conversationBackend}
      defaultAgentName="qa-chat"
      style={{ height: "100vh" }}
    />
  );
}

Custom Path Prefix

const conversationBackend = createHttpConversationBackend({
  baseUrl: "https://api.example.com",
  pathPrefix: "/v2/chat/conversations",
  getHeaders: () => ({
    Authorization: `Bearer ${getToken()}`,
  }),
});

Direct API Usage

const backend = createHttpConversationBackend({ baseUrl: "/api" });

// List conversations
const conversations = await backend.listConversations();

// Create a new conversation
const newConv = await backend.createConversation({
  agentName: "qa-chat",
});

// Send a message
const response = await backend.sendMessage(newConv.id, {
  content: "Hello, how can you help?",
  agentName: "qa-chat",
});

console.log(response.content); // Assistant's reply

// Get full message history
const messages = await backend.getMessages(newConv.id);

// Delete conversation
await backend.deleteConversation(newConv.id);

With useConversations Hook

import {
  createHttpConversationBackend,
  useConversations,
} from "@modernpath/agent-ui-react";

const backend = createHttpConversationBackend({ baseUrl: "/api" });

function CustomConversations() {
  const {
    conversations,
    selectedId,
    messages,
    select,
    create,
    send,
    remove,
  } = useConversations({
    backend,
    defaultAgentName: "qa-chat",
  });

  // Custom rendering...
}