gh-jezweb-claude-skills-skills-openai-responses/references/stateful-conversations.md

Stateful Conversations Guide

Last Updated: 2025-10-25

Guide to managing conversation state with the Responses API.

---

Automatic State Management

// Create conversation
const conv = await openai.conversations.create({
  metadata: { user_id: 'user_123' },
});

// Turn 1
const response1 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id,
  input: 'What are the 5 Ds of dodgeball?',
});

// Turn 2 - automatically remembers turn 1
const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id,
  input: 'Tell me more about the first one',
});

---

Conversation Management

Create:

const conv = await openai.conversations.create({
  metadata: { topic: 'support' },
  items: [
    { type: 'message', role: 'developer', content: 'You are helpful.' }
  ],
});

List:

const convs = await openai.conversations.list({ limit: 10 });

Delete:

await openai.conversations.delete(conv.id);

---

Benefits vs Manual History

Feature	Manual History	Conversation IDs
Complexity	High (you track)	Low (automatic)
Cache	Baseline	40-80% better
Reasoning	Discarded	Preserved
Errors	Common	Rare

---

Best Practices

1. Store conversation IDs: Database, session storage, cookies
2. Add metadata: Track user, topic, session type
3. Expire old conversations: Delete after 90 days or when done
4. One conversation per topic: Don't mix unrelated topics

---

Official Docs: https://platform.openai.com/docs/api-reference/conversations