Implementation:Openai Openai node Conversations Resource

Knowledge Sources	Openai_Openai_node
Domains	SDK, Conversations
Last Updated	2026-02-15 12:00 GMT

Overview

The Conversations resource class provides full CRUD operations for managing multi-turn conversations via the OpenAI Conversations API.

Description

The Conversations class extends APIResource and exposes four methods: create, retrieve, update, and delete. It also includes an items sub-resource for managing individual conversation items. The create method sends a POST to /conversations with optional initial items and metadata. The retrieve method fetches a conversation by ID. The update method modifies a conversation's metadata. The delete method removes a conversation (though items within it are not deleted).

The file defines several important interfaces. The Conversation interface contains an id, created_at timestamp, metadata (up to 16 key-value pairs), and an object type field. The Message interface represents a message in a conversation with content that can include input text, output text, reasoning text, summary text, refusal, images, computer screenshots, and files. Messages carry a role (one of unknown, user, assistant, system, critic, discriminator, developer, or tool) and a status.

Additional content-type interfaces include ComputerScreenshotContent, SummaryTextContent, TextContent, and type aliases such as InputTextContent, OutputTextContent, RefusalContent, InputImageContent, and InputFileContent that map to response types from the Responses API.

Usage

Use the Conversations resource when building applications that require persistent, multi-turn conversation management. Create conversations to maintain context across multiple responses, add items to track the conversation history, and use metadata for organization and querying.

Code Reference

Source Location

• Repository: openai-node
• File: src/resources/conversations/conversations.ts

Signature

export class Conversations extends APIResource {
  items: ItemsAPI.Items;

  create(
    body?: ConversationCreateParams | null | undefined,
    options?: RequestOptions,
  ): APIPromise<Conversation>;

  retrieve(conversationID: string, options?: RequestOptions): APIPromise<Conversation>;

  update(
    conversationID: string,
    body: ConversationUpdateParams,
    options?: RequestOptions,
  ): APIPromise<Conversation>;

  delete(conversationID: string, options?: RequestOptions): APIPromise<ConversationDeletedResource>;
}

export interface Conversation {
  id: string;
  created_at: number;
  metadata: unknown;
  object: 'conversation';
}

export interface Message {
  id: string;
  content: Array</* various content types */>;
  role: 'unknown' | 'user' | 'assistant' | 'system' | 'critic'
    | 'discriminator' | 'developer' | 'tool';
  status: 'in_progress' | 'completed' | 'incomplete';
  type: 'message';
}

Import

import OpenAI from 'openai';

I/O Contract

Inputs

create:

Name	Type	Required	Description
items	null	No	Initial items to include in the conversation (up to 20 at a time)
metadata	null	No	Up to 16 key-value pairs for structured information (keys max 64 chars, values max 512 chars)

retrieve / delete:

Name	Type	Required	Description
conversationID	string	Yes	The unique ID of the conversation

update:

Name	Type	Required	Description
conversationID	string	Yes	The unique ID of the conversation
metadata	null	Yes	Updated key-value pairs for the conversation

Outputs

Name	Type	Description
Conversation	Conversation	The conversation object with id, created_at, metadata, and object type
ConversationDeletedResource	{ id: string, deleted: boolean, object: 'conversation.deleted' }	Confirmation of deletion
Message	Message	A message within a conversation with content, role, and status

Usage Examples

import OpenAI from 'openai';

const client = new OpenAI();

// Create a new conversation
const conversation = await client.conversations.create({
  metadata: { topic: 'customer_support', session: 'abc123' },
});
console.log('Created conversation:', conversation.id);

// Retrieve a conversation
const fetched = await client.conversations.retrieve(conversation.id);
console.log('Conversation created at:', fetched.created_at);

// Update conversation metadata
const updated = await client.conversations.update(conversation.id, {
  metadata: { topic: 'billing_inquiry', resolved: 'true' },
});

// Delete a conversation
const deleted = await client.conversations.delete(conversation.id);
console.log('Deleted:', deleted.deleted);

// Access conversation items sub-resource
const items = await client.conversations.items.list(conversation.id);

Related Pages

• Environment:Openai_Openai_node_Node_20_Runtime