Conversations API
Create, retrieve, update, and delete durable, server-side conversations, and manage their items. A conversation id feeds the Responses API for multi-turn exchanges without resending history. OpenAI only.
Parsed Objects
UniLM.ConversationObject — Type
ConversationObjectA durable, server-side conversation: id, optional created_at and metadata; raw holds the unparsed JSON response.
UniLM.ConversationItem — Type
ConversationItemA single item in a conversation: id and optional type; raw holds the unparsed JSON response.
UniLM.ConversationItemList — Type
ConversationItemListA page of ConversationItems from list_conversation_items; has_more signals further pages, and first_id/last_id bound the page.
Result Types
UniLM.ConversationSuccess — Type
Successful create/retrieve/update result wrapping a ConversationObject.
UniLM.ConversationItemListSuccess — Type
Successful list_conversation_items / add_conversation_items result wrapping a ConversationItemList.
UniLM.ConversationItemSuccess — Type
Successful result wrapping a single ConversationItem.
UniLM.ConversationDeleteSuccess — Type
Successful delete_conversation / delete_conversation_item result; deleted confirms removal of id.
UniLM.ConversationFailure — Type
Conversations API error result: HTTP status and the raw response body.
UniLM.ConversationCallError — Type
Local/transport error from a Conversations API call (the request never completed).
Request Functions
UniLM.create_conversation — Function
create_conversation(; items=nothing, metadata=nothing, service=OPENAIServiceEndpoint)Create a conversation. items is an optional vector of input items (e.g. InputMessage). Returns ConversationSuccess, ConversationFailure, or ConversationCallError.
Pass config::Union{Nothing,RequestConfig} to override the timeout budget for this call (a single bounded attempt; max_attempts does not apply).
UniLM.retrieve_conversation — Function
retrieve_conversation(id; service=OPENAIServiceEndpoint)Pass config::Union{Nothing,RequestConfig} to override the timeout budget for this call (a single bounded attempt; max_attempts does not apply).
UniLM.update_conversation — Function
update_conversation(id, metadata; service=OPENAIServiceEndpoint)Pass config::Union{Nothing,RequestConfig} to override the timeout budget for this call (a single bounded attempt; max_attempts does not apply).
UniLM.delete_conversation — Function
delete_conversation(id; service=OPENAIServiceEndpoint)Pass config::Union{Nothing,RequestConfig} to override the timeout budget for this call (a single bounded attempt; max_attempts does not apply).
UniLM.add_conversation_items — Function
add_conversation_items(conversation_id, items; service=OPENAIServiceEndpoint)Append input items to a conversation. Returns ConversationItemListSuccess.
Pass config::Union{Nothing,RequestConfig} to override the timeout budget for this call (a single bounded attempt; max_attempts does not apply).
UniLM.list_conversation_items — Function
list_conversation_items(conversation_id; limit=nothing, order=nothing, after=nothing, service=OPENAIServiceEndpoint)Pass config::Union{Nothing,RequestConfig} to override the timeout budget for this call (a single bounded attempt; max_attempts does not apply).
UniLM.delete_conversation_item — Function
delete_conversation_item(conversation_id, item_id; service=OPENAIServiceEndpoint)Pass config::Union{Nothing,RequestConfig} to override the timeout budget for this call (a single bounded attempt; max_attempts does not apply).
Accessors
UniLM.conversation_id — Function
conversation_id(c::ConversationObject) -> StringReturn the id of a ConversationObject.
Usage
# Create a durable, server-side conversation
result = create_conversation(metadata=Dict("topic" => "support"))
result isa ConversationSuccess && println("Created: ", conversation_id(result.response))
# Retrieve, then update its metadata
retrieve_conversation("conv_abc123")
update_conversation("conv_abc123", Dict("status" => "closed"))
# Add items, list them, then clean up
add_conversation_items("conv_abc123", [InputMessage(role="user", content="Hello")])
items = list_conversation_items("conv_abc123", limit=20)
delete_conversation_item("conv_abc123", "msg_xyz")
delete_conversation("conv_abc123")