Client-to-server events — Voice Agent API: real-time conversations

The messages you send

The Voice Agent API works by exchanging JSON events over WebSocket. In this lesson, you’ll go through every event your app can send to the server. Each one has a specific role in the conversation cycle.

Event	Description	When to use it
session.update	Configure the session	At startup and to change the configuration
input_audio_buffer.append	Send a base64 audio chunk	Continuously while recording
input_audio_buffer.commit	Commit the audio buffer	In push-to-talk mode
input_audio_buffer.clear	Empty the buffer without processing	To cancel a recording
conversation.item.create	Add a message or function result	History, context, function results
conversation.item.delete	Delete an item by ID	Cleaning up the conversation
response.create	Request a response	In manual mode (automatic with VAD)
response.cancel	Cancel a response in progress	When the user interrupts

conversation.item.create

This event lets you inject messages into the conversation without going through the audio stream. It covers three main cases.

Add a user text message

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "What's the status of my order 12345?"
      }
    ]
  }
}

Inject conversation history

Before the voice conversation starts, you can prefill the history with earlier exchanges to give the agent context:

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Hello, I'm your assistant. How can I help you?"
      }
    ]
  }
}

Return a function result

After a function call has run, you send back the result with this event (see lesson 13 on function calling):

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_abc123",
    "output": "{\"status\": \"shipped\", \"tracking\": \"FR123456789\"}"
  }
}

conversation.item.delete

Deletes a conversation item by its ID:

{
  "type": "conversation.item.delete",
  "item_id": "item_audio_001"
}

This is useful for removing an incorrect message or keeping the conversation history from growing too large.

response.create and response.cancel

response.create explicitly asks the server to generate a response. In VAD mode, the server does this on its own once it detects the end of speech:

{
  "type": "response.create"
}

response.cancel stops a response that is being generated. It’s useful when the user talks over the agent:

{
  "type": "response.cancel"
}

Key takeaways

Eight types of events can be sent from the client to the server
session.update configures the session and can be sent several times
conversation.item.create lets you add text, history, or function results
response.create is required in manual mode and automatic in VAD mode
response.cancel lets you interrupt the agent when the user starts speaking again