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

# Create a voice session in the phone-server store.

> Tenant-scoped endpoint for persisted voice session records, stream lookup, and evaluation history.

Tenant-scoped endpoint for persisted voice session records, stream lookup, and evaluation history.

### Request body

`CreateVoiceSessionRequest`

<ParamField body="agent_name" type="string,null" />

<ParamField body="call_sid" type="string,null" />

<ParamField body="call_type" type="string,null" />

<ParamField body="customer_phone" type="string,null" />

<ParamField body="duration_ms" type="integer,null (int64)" />

<ParamField body="metadata" type="any" />

<ParamField body="model" type="string,null" />

<ParamField body="org_id" type="string,null" />

<ParamField body="sentiment" type="string,null" />

<ParamField body="status" type="string,null" />

<ParamField body="stream_id" type="string" required />

<ParamField body="summary" type="string,null" />

<ParamField body="tags" type="array,null" />

<ParamField body="transcript" type="any" />

<ParamField body="voice" type="string,null" />

### Response

`VoiceSession`

<ResponseField name="agent_name" type="string,null">
  AI agent name
</ResponseField>

<ResponseField name="call_sid" type="string,null">
  Twilio call SID
</ResponseField>

<ResponseField name="call_type" type="string,null">
  Type of call: inbound, outbound, sip\_inbound
</ResponseField>

<ResponseField name="created_at" type="string" required>
  Record creation time (ISO 8601)
</ResponseField>

<ResponseField name="customer_phone" type="string,null">
  Customer phone number (E.164)
</ResponseField>

<ResponseField name="duration_ms" type="integer,null (int64)">
  Session duration in milliseconds
</ResponseField>

<ResponseField name="ended_at" type="string" required>
  Session end time (ISO 8601)
</ResponseField>

<ResponseField name="function_calls" type="object" required>
  Function calls made during the session as JSON array
</ResponseField>

<ResponseField name="id" type="string" required>
  Unique session identifier
</ResponseField>

<ResponseField name="metadata" type="object" required>
  Arbitrary session metadata
</ResponseField>

<ResponseField name="model" type="string,null">
  AI model used
</ResponseField>

<ResponseField name="org_id" type="string,null">
  Organization ID
</ResponseField>

<ResponseField name="rating" type="integer,null (int32)">
  Operator-provided review rating
</ResponseField>

<ResponseField name="sentiment" type="string,null">
  Operator or model sentiment label
</ResponseField>

<ResponseField name="started_at" type="string" required>
  Session start time (ISO 8601)
</ResponseField>

<ResponseField name="status" type="string" required>
  Session status: active, completed
</ResponseField>

<ResponseField name="stream_id" type="string" required>
  Twilio stream ID
</ResponseField>

<ResponseField name="summary" type="string,null">
  LLM-generated summary
</ResponseField>

<ResponseField name="tags" type="string[]" required>
  Session tags applied in the voice desk
</ResponseField>

<ResponseField name="tenant_id" type="string" required>
  Tenant that owns this session
</ResponseField>

<ResponseField name="transcript" type="object" required>
  Conversation transcript as JSON array
</ResponseField>

<ResponseField name="turn_count" type="integer (int32)" required>
  Number of conversation turns
</ResponseField>

<ResponseField name="updated_at" type="string" required>
  Record last updated time (ISO 8601)
</ResponseField>

<ResponseField name="vad_events" type="object" required>
  Voice activity detection events as JSON array
</ResponseField>

<ResponseField name="voice" type="string,null">
  TTS voice used
</ResponseField>

### Status codes

| Code  | Meaning                                        |
| ----- | ---------------------------------------------- |
| `201` | Created voice session                          |
| `400` | Invalid request body                           |
| `401` | Unauthorized - invalid or missing bearer token |
| `409` | Voice session stream already exists            |
| `500` | Internal server error                          |
| `503` | Database not configured - set DATABASE\_URL    |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.voice.stateset.com/api/v1/voice-sessions' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
    "agent_name": null,
    "call_sid": null,
    "call_type": null,
    "customer_phone": null,
    "duration_ms": null,
    "metadata": null,
    "model": null,
    "org_id": null,
    "sentiment": null,
    "status": null,
    "stream_id": "string",
    "summary": null,
    "tags": null,
    "transcript": null,
    "voice": null
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "agent_name": "ResponseCX",
    "call_sid": "CA1234567890abcdef1234567890abcdef",
    "call_type": "inbound",
    "created_at": "2024-01-15T10:30:00Z",
    "customer_phone": "+15555555678",
    "duration_ms": 142000,
    "ended_at": "2024-01-15T10:32:22Z",
    "function_calls": null,
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "metadata": null,
    "model": "gpt-4o-realtime-preview",
    "org_id": "org-456",
    "rating": 4,
    "sentiment": "positive",
    "started_at": "2024-01-15T10:30:00Z",
    "status": "completed",
    "stream_id": "MZ1234567890abcdef1234567890abcdef",
    "summary": "Customer inquired about order ORD-123 status. Agent confirmed it shipped yesterday.",
    "tags": [
      "vip",
      "escalation"
    ],
    "tenant_id": "tenant-123",
    "transcript": null,
    "turn_count": 12,
    "updated_at": "2024-01-15T10:32:22Z",
    "vad_events": null,
    "voice": "alloy"
  }
  ```
</ResponseExample>