Skip to main content

​
Message Types

Complete reference for all WebSocket message types.

​
Outgoing Messages (Client → Server)

​
init

Initialize a session with configuration options. 
{
  "type": "init",
  "payload": {
    "model": "claude-sonnet-4-5-20250929",
    "systemPrompt": "You are a helpful assistant.",
    "maxTurns": 10,
    "tools": [],
    "mcpServers": []
  }
}
FieldTypeRequiredDescription
modelstringNoClaude model (default: from token)
systemPromptstringNoSystem prompt
maxTurnsnumberNoMax conversation turns
toolsarrayNoTool definitions
mcpServersarrayNoMCP server definitions
allowedToolsstring[]NoTool whitelist
disallowedToolsstring[]NoTool blacklist
maxBudgetUsdnumberNoSession budget limit

​
prompt

Send a one-shot prompt (stateless mode). 
{
  "type": "prompt",
  "payload": {
    "message": "What is 2 + 2?",
    "model": "claude-sonnet-4-5-20250929"
  }
}
FieldTypeRequiredDescription
messagestringYesThe prompt message
modelstringNoOverride model
systemPromptstringNoSystem prompt
toolsarrayNoTool definitions
outputFormatobjectNoStructured output format

​
sdk_message

Send a message in an active session. 
{
  "type": "sdk_message",
  "payload": {
    "type": "user",
    "message": "Hello, Claude!"
  }
}
FieldTypeRequiredDescription
typestringYesMessage type (user)
messagestringYesUser message content

​
tool_result

Return a tool execution result. 
{
  "type": "tool_result",
  "payload": {
    "callId": "call_abc123",
    "result": {
      "content": [
        { "type": "text", "text": "Result data" }
      ],
      "isError": false
    }
  }
}
FieldTypeRequiredDescription
callIdstringYesTool call ID from tool_call
resultobjectYesTool result
result.contentarrayYesContent blocks
result.isErrorbooleanNoWhether result is an error

​
control

Send control commands. 
{
  "type": "control",
  "payload": {
    "action": "close"
  }
}
ActionDescription
closeGracefully close the session

​
ping

Keep-alive ping. 
{
  "type": "ping",
  "payload": {
    "timestamp": 1704067200000
  }
}

​
Incoming Messages (Server → Client)

​
control

Server control messages. 
{
  "type": "control",
  "payload": {
    "action": "ready",
    "data": {
      "sessionId": "session_abc123"
    }
  }
}
ActionDescription
readySession initialized and ready
session_infoSession metadata

​
sdk_message

Streaming response content. 
{
  "type": "sdk_message",
  "payload": {
    "type": "assistant",
    "subtype": "text",
    "text": "Hello! "
  }
}
Subtypes:
SubtypeDescription
textText content chunk
thinkingExtended thinking content
tool_useTool invocation

​
tool_call

Request tool execution from client. 
{
  "type": "tool_call",
  "payload": {
    "id": "call_abc123",
    "name": "get_weather",
    "input": {
      "city": "Paris"
    }
  }
}
FieldTypeDescription
idstringUnique call ID
namestringTool name
inputobjectTool input arguments

​
result

Final response result. 
{
  "type": "result",
  "payload": {
    "type": "result",
    "subtype": "success",
    "text": "The answer is 4.",
    "total_cost_usd": 0.0012,
    "duration_secs": 1.5,
    "session_id": "session_abc123",
    "usage": {
      "input_tokens": 50,
      "output_tokens": 20
    }
  }
}
FieldTypeDescription
typestringAlways "result"
subtypestringsuccess, error, or interrupted
textstringFinal response text
total_cost_usdnumberTotal cost in USD
duration_secsnumberResponse time
session_idstringSession ID for resumption
usageobjectToken usage details

​
error

Error message. 
{
  "type": "error",
  "payload": {
    "code": "BUDGET_EXCEEDED",
    "message": "AI budget exceeded for this period",
    "details": {
      "budgetType": "ai",
      "used": 1000000,
      "limit": 1000000
    }
  }
}
FieldTypeDescription
codestringError code
messagestringHuman-readable message
detailsobjectAdditional context

​
pong

Response to ping. 
{
  "type": "pong",
  "payload": {
    "timestamp": 1704067200000
  }
}