Struct Conversations 

pub struct Conversations { /* private fields */ }

Client for interacting with the OpenAI Conversations API.

This struct provides methods to create, retrieve, update, delete conversations, and manage conversation items. Use Conversations::new() to create a new instance.

Example

use openai_tools::conversations::request::Conversations;
use std::collections::HashMap;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let conversations = Conversations::new()?;

    // Create a conversation with metadata
    let mut metadata = HashMap::new();
    metadata.insert("user_id".to_string(), "user123".to_string());

    let conv = conversations.create(Some(metadata), None).await?;
    println!("Created: {}", conv.id);

    // Retrieve the conversation
    let retrieved = conversations.retrieve(&conv.id).await?;
    println!("Retrieved: {:?}", retrieved.metadata);

    Ok(())
}

Implementations

impl Conversations

pub fn new() -> Result<Self>

Creates a new Conversations client for OpenAI API.

Initializes the client by loading the OpenAI API key from the environment variable OPENAI_API_KEY. Supports .env file loading via dotenvy.

Returns

• Ok(Conversations) - A new Conversations client ready for use
• Err(OpenAIToolError) - If the API key is not found in the environment

Example

use openai_tools::conversations::request::Conversations;

let conversations = Conversations::new().expect("API key should be set");

pub fn with_auth(auth: AuthProvider) -> Self

Creates a new Conversations client with a custom authentication provider

pub fn azure() -> Result<Self>

Creates a new Conversations client for Azure OpenAI API

pub fn detect_provider() -> Result<Self>

Creates a new Conversations client by auto-detecting the provider

pub fn with_url<S: Into<String>>(base_url: S, api_key: S) -> Self

Creates a new Conversations client with URL-based provider detection

pub fn from_url<S: Into<String>>(url: S) -> Result<Self>

Creates a new Conversations client from URL using environment variables

pub fn auth(&self) -> &AuthProvider

Returns the authentication provider

pub fn timeout(&mut self, timeout: Duration) -> &mut Self

Sets the request timeout duration.

Arguments

• timeout - The maximum time to wait for a response

Returns

A mutable reference to self for method chaining

pub async fn create( &self, metadata: Option<HashMap<String, String>>, items: Option<Vec<InputItem>>, ) -> Result<Conversation>

Creates a new conversation.

You can optionally provide metadata and initial items to include in the conversation.

Arguments

• metadata - Optional key-value pairs for storing additional information
• items - Optional initial items to add to the conversation (up to 20 items)

Returns

• Ok(Conversation) - The created conversation object
• Err(OpenAIToolError) - If the request fails

Example

use openai_tools::conversations::request::Conversations;
use openai_tools::conversations::response::InputItem;
use std::collections::HashMap;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let conversations = Conversations::new()?;

    // Create with metadata and initial message
    let mut metadata = HashMap::new();
    metadata.insert("topic".to_string(), "greeting".to_string());

    let items = vec![InputItem::user_message("Hello!")];

    let conv = conversations.create(Some(metadata), Some(items)).await?;
    println!("Created conversation: {}", conv.id);
    Ok(())
}

pub async fn retrieve(&self, conversation_id: &str) -> Result<Conversation>

Retrieves a specific conversation.

Arguments

• conversation_id - The ID of the conversation to retrieve

Returns

• Ok(Conversation) - The conversation object
• Err(OpenAIToolError) - If the conversation is not found or the request fails

Example

use openai_tools::conversations::request::Conversations;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let conversations = Conversations::new()?;
    let conv = conversations.retrieve("conv_abc123").await?;

    println!("Conversation: {}", conv.id);
    println!("Created at: {}", conv.created_at);
    Ok(())
}

pub async fn update( &self, conversation_id: &str, metadata: HashMap<String, String>, ) -> Result<Conversation>

Updates a conversation’s metadata.

Arguments

• conversation_id - The ID of the conversation to update
• metadata - The new metadata to set

Returns

• Ok(Conversation) - The updated conversation object
• Err(OpenAIToolError) - If the request fails

Example

use openai_tools::conversations::request::Conversations;
use std::collections::HashMap;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let conversations = Conversations::new()?;

    let mut metadata = HashMap::new();
    metadata.insert("topic".to_string(), "updated-topic".to_string());

    let conv = conversations.update("conv_abc123", metadata).await?;
    println!("Updated: {:?}", conv.metadata);
    Ok(())
}

pub async fn delete( &self, conversation_id: &str, ) -> Result<DeleteConversationResponse>

Deletes a conversation.

Arguments

• conversation_id - The ID of the conversation to delete

Returns

• Ok(DeleteConversationResponse) - Confirmation of deletion
• Err(OpenAIToolError) - If the request fails

Example

use openai_tools::conversations::request::Conversations;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let conversations = Conversations::new()?;
    let result = conversations.delete("conv_abc123").await?;

    if result.deleted {
        println!("Conversation {} was deleted", result.id);
    }
    Ok(())
}

pub async fn create_items( &self, conversation_id: &str, items: Vec<InputItem>, ) -> Result<ConversationItemListResponse>

Creates items in a conversation.

You can add up to 20 items at a time.

Arguments

• conversation_id - The ID of the conversation
• items - The items to add to the conversation

Returns

• Ok(ConversationItemListResponse) - The created items
• Err(OpenAIToolError) - If the request fails

Example

use openai_tools::conversations::request::Conversations;
use openai_tools::conversations::response::InputItem;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let conversations = Conversations::new()?;

    let items = vec![
        InputItem::user_message("What is the weather like?"),
        InputItem::assistant_message("I'd be happy to help with weather information!"),
    ];

    let result = conversations.create_items("conv_abc123", items).await?;
    println!("Added {} items", result.data.len());
    Ok(())
}

pub async fn list_items( &self, conversation_id: &str, limit: Option<u32>, after: Option<&str>, order: Option<&str>, include: Option<Vec<ConversationInclude>>, ) -> Result<ConversationItemListResponse>

Lists items in a conversation.

Arguments

• conversation_id - The ID of the conversation
• limit - Maximum number of items to return (1-100, default 20)
• after - Cursor for pagination (item ID to start after)
• order - Sort order (“asc” or “desc”, default “desc”)
• include - Additional data to include in the response

Returns

• Ok(ConversationItemListResponse) - The list of items
• Err(OpenAIToolError) - If the request fails

Example

use openai_tools::conversations::request::{Conversations, ConversationInclude};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let conversations = Conversations::new()?;

    // List items with pagination
    let items = conversations.list_items(
        "conv_abc123",
        Some(20),
        None,
        Some("desc"),
        None,
    ).await?;

    for item in &items.data {
        println!("Item: {} ({})", item.id, item.item_type);
    }
    Ok(())
}

pub async fn list( &self, limit: Option<u32>, after: Option<&str>, ) -> Result<ConversationListResponse>

Lists all conversations (if available).

Note: This endpoint may not be available in all API versions.

Arguments

• limit - Maximum number of conversations to return (1-100, default 20)
• after - Cursor for pagination (conversation ID to start after)

Returns

• Ok(ConversationListResponse) - The list of conversations
• Err(OpenAIToolError) - If the request fails

Example

use openai_tools::conversations::request::Conversations;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let conversations = Conversations::new()?;

    let response = conversations.list(Some(10), None).await?;
    for conv in &response.data {
        println!("Conversation: {} (created: {})", conv.id, conv.created_at);
    }
    Ok(())
}