> ## Documentation Index > Fetch the complete documentation index at: https://docs.phone.wixzel.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a realtime session > Mint a one-minute, single-use `client_secret` that lets a browser or app talk to one of your agents over `wss://api.phone.wixzel.com/v1/realtime` — no SIP trunk, no phone number. Call this from your server; the API key must never reach the client. Nothing is charged here. When the socket connects, the session is admitted exactly like a call: it needs credit, counts toward your concurrent-call limit and the key's spend limit, is billed at the same per-minute price as a phone call on the same engine, and appears in GET /v1/calls with `channel: "web"`, followed by a `callCompleted` webhook. Human transfer is not available on web sessions — there is no second line to hand the caller to. ## OpenAPI ````yaml /openapi.json post /v1/realtime/sessions openapi: 3.1.0 info: title: Wixzel Phone API version: '2026-09-01' description: >- APIs for AI voice agents. One key, one balance, every voice engine. ## Authentication Send your key as `Authorization: Bearer wv_live_...`. Keys are scoped — grant only what an integration needs. There is no admin scope. ## Versioning The `/v1` prefix covers additive changes. Behavioural changes ship behind a dated `Wixzel-Version` header, and existing keys keep the behaviour they were created with. ## Money Amounts are integer **micro-USD** (1,000,000 = $1.00). Voice usage is billed per second, per token and per character, so a float dollar figure cannot represent it without disagreeing with the ledger. ## Errors Every error carries a stable `code` and a `request_id`. Match on `code`; the `message` is for humans and may change. contact: name: Wixzel Phone url: https://phone.wixzel.com servers: - url: https://api.phone.wixzel.com description: Production security: [] tags: - name: Calls description: Place calls and read what happened on them. - name: Realtime description: Talk to an agent from a browser or app, with no phone line. - name: Agents description: The prompt, voice and behaviour of a caller. - name: Leads description: People to call, and data to merge into prompts. - name: Campaigns description: Call a list of leads with one agent. - name: Knowledge bases description: Facts an agent can draw on mid-call. - name: Phone numbers description: Numbers on your SIP trunks. - name: SIP trunks description: Your carrier connections. - name: Appointments description: Bookings, including ones agents make on calls. - name: Usage description: Itemised billing lines. - name: Billing description: Balance, ledger and top-ups. - name: API keys description: Create, scope and rotate keys. - name: Engines description: What the platform can serve, and what it costs. - name: Webhooks description: Where events are sent, and what happened when they got there. paths: /v1/realtime/sessions: post: tags: - Realtime summary: Create a realtime session description: >- Mint a one-minute, single-use `client_secret` that lets a browser or app talk to one of your agents over `wss://api.phone.wixzel.com/v1/realtime` — no SIP trunk, no phone number. Call this from your server; the API key must never reach the client. Nothing is charged here. When the socket connects, the session is admitted exactly like a call: it needs credit, counts toward your concurrent-call limit and the key's spend limit, is billed at the same per-minute price as a phone call on the same engine, and appears in GET /v1/calls with `channel: "web"`, followed by a `callCompleted` webhook. Human transfer is not available on web sessions — there is no second line to hand the caller to. requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateRealtimeSession' responses: '201': description: The session and its client secret content: application/json: schema: $ref: '#/components/schemas/RealtimeSession' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Key lacks the required scope content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No such record content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limited. Retry after the interval in `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: CreateRealtimeSession: type: object properties: agent_id: type: string pattern: ^[0-9a-f]{24}$ example: 6a96a3ead6e886d42462dd3e lead_id: type: string pattern: ^[0-9a-f]{24}$ description: >- Existing lead to attribute the session to — merge fields such as {{name}} resolve from it, and appointment booking uses its phone. Without one, merge fields resolve to nothing and the call has no lead. example: 6a96a3ead6e886d42462dd3e metadata: type: object additionalProperties: type: string description: >- Your own identifiers, kept verbatim on the resulting call and echoed in its `callCompleted` webhook. Flat, string to string. Never sent to the model. max_duration_seconds: type: integer minimum: 10 maximum: 3600 description: Hard cap on the conversation. Defaults to 600; at most 3600. example: 600 allowed_origins: type: array items: type: string maxLength: 255 pattern: ^https?:\/\/[a-z0-9.-]+(:\d{1,5})?$ example: https://app.example.com maxItems: 10 description: >- When set, the socket is refused unless the browser's Origin is one of these. Recommended for browser use: it stops a secret copied out of your page being used from another site. required: - agent_id RealtimeSession: type: object properties: id: type: string description: Becomes the `session_id` of the resulting call. example: rt-5b0c7c0e-9d1f-4c52-8a9e-2f0d3a4b6c7d object: type: string enum: - realtime_session client_secret: type: object properties: value: type: string description: >- Pass as the `client_secret` query parameter when opening the socket. Single use. expires_at: type: string format: date-time description: Connect before this. One minute after creation. example: '2026-09-01T12:00:00.000Z' required: - value - expires_at url: type: string example: wss://api.phone.wixzel.com/v1/realtime agent_id: type: string pattern: ^[0-9a-f]{24}$ example: 6a96a3ead6e886d42462dd3e engine: type: string example: gemini_live max_duration_seconds: type: integer audio_format: type: string enum: - mulaw_8000 description: >- Base64 G.711 µ-law, 8 kHz mono, both directions — what a phone line carries. required: - id - object - client_secret - url - agent_id - engine - max_duration_seconds - audio_format Error: type: object properties: error: type: object properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - rate_limit_error - insufficient_credits - not_found_error - conflict_error - api_error code: type: string description: Stable machine-readable code. example: agent_not_found message: type: string description: >- Human-readable explanation. Do not match on this — match on code. param: type: string description: Which field caused the failure, when applicable. doc_url: type: string request_id: type: string description: Quote this when asking for help. example: req_01HXYZ... required: - type - code - message - request_id required: - error securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Wixzel Phone API key: `Authorization: Bearer wv_live_...`. Keys are scoped; grant only what the integration needs. ````