> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vivix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# conversation.item.create

Adds a conversation item to the session. Use it to provide user messages, function calls, or function call outputs that should become part of the conversation context. The server confirms with `conversation.item.created`.

**`conversation.item.create` → `response.create`:** wait for the matching `conversation.item.created` before requesting a reply that uses the new message. Use the same sequence when returning a tool result.

## Event fields

<ParamField body="event_id" type="string">
  Client-generated id for this event.
</ParamField>

<ParamField body="type" type="string" required>
  Event type. Must be `conversation.item.create`.
</ParamField>

<ParamField body="previous_item_id" type="string">
  Item after which the new item should be inserted. If omitted, the item is appended. Use `root` to insert at the beginning of the conversation.
</ParamField>

<ParamField body="item" type="object" required>
  A single item within the realtime conversation. Provide one of the variants below.
</ParamField>

<ParamField body="id" type="string">
  Server-assigned or client-provided conversation item id.
</ParamField>

<ParamField body="type" type="string" required>
  One of `message`, `function_call`, or `function_call_output`.
</ParamField>

<ParamField body="status" type="string">
  One of `completed`, `incomplete`, or `in_progress`. Usually returned by the server.
</ParamField>

**Message variant**

Message item with `item.type: "message"`.

**Message `variant.role`: string enum**

One of `system`, `user`, or `assistant`. System messages provide additional conversation context or instructions. For assistant messages, generated audio and video are delivered over RTC media tracks, and the text for spoken output streams through `response.output_text.*` events.

**Message `variant.content`: array**

Message content parts. System messages typically use `input_text`; user messages typically use `input_text`, `input_audio`, and `input_image`; assistant messages typically use `text` parts.

**Message `variant.content[].type`: string enum**

One of `input_text`, `input_audio`, `input_image`, or `text`.

**Message `variant.content[].text`: optional string**

Text content. Used with `input_text` and `text`.

**Message `variant.content[].audio`: optional string**

Base64-encoded audio. Used with `input_audio`.

**Message `variant.content[].transcript`: optional string**

Optional transcript. Used with `input_audio`.

**Message `variant.content[].image_url`: optional string**

Image URL. Used with `input_image`.

**Message `variant.content[].detail`: optional string enum**

Image detail level of `auto`, `low`, or `high`. Used with `input_image`.

**Function call variant**

Function call item with `item.type: "function_call"`.

**Function call `variant.call_id`: optional string**

Function call id.

**Function call `variant.name`: string**

Function name.

**Function call `variant.arguments`: string**

JSON-encoded function arguments.

**Function call output variant**

Function call output item with `item.type: "function_call_output"`.

**Function call output `variant.call_id`: string**

Function call id this output belongs to.

**Function call output `variant.output`: string**

Function output as a string.

<RequestExample>
  ```json conversation.item.create theme={null}
  {
    "event_id": "evt_item_create_001",
    "type": "conversation.item.create",
    "previous_item_id": "item_000",
    "item": {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Show me the second product."
        }
      ]
    }
  }
  ```
</RequestExample>