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

# Create a call for your own telephony

> Create a call session for a saved agent and receive a **WebSocket URL**
to stream audio into.

This is the "bring your own telephony" endpoint: point Twilio, Telnyx or
Plivo at the returned `websocketUrl`, or connect to it directly from
your own client. It is also what the JavaScript SDK calls under the hood
when you pass an `agentId`.




## OpenAPI

````yaml /openapi.yaml post /calls/create
openapi: 3.0.0
info:
  title: Omnia Voice API
  description: >
    The Omnia Voice API allows you to programmatically manage voice agents,
    tools, phone numbers, and call logs.


    ## Authentication

    All API requests require an API key to be passed in the `X-API-Key` header.


    ## Rate Limiting

    API requests are rate limited to 1000 requests per hour per API key.
  version: 1.0.0
  contact:
    email: support@omnia-voice.com
servers:
  - url: https://api.omnia-voice.com/api/v1
    description: Production
  - url: https://dashboard.omnia-voice.com/api/v1
    description: Production (alias — same service)
security:
  - ApiKeyAuth: []
tags:
  - name: Agents
    description: Manage voice agents
  - name: Tools
    description: Manage agent tools and actions
  - name: Phone Numbers
    description: Manage phone number assignments
  - name: Calls
    description: Create and manage voice calls
  - name: Call Logs
    description: View call history and details
  - name: Pricing
    description: Get pricing information and calculate call costs
  - name: Configuration
    description: Get configuration options (voices, languages)
paths:
  /calls/create:
    post:
      tags:
        - Calls
      summary: Create a call for your own telephony
      description: |
        Create a call session for a saved agent and receive a **WebSocket URL**
        to stream audio into.

        This is the "bring your own telephony" endpoint: point Twilio, Telnyx or
        Plivo at the returned `websocketUrl`, or connect to it directly from
        your own client. It is also what the JavaScript SDK calls under the hood
        when you pass an `agentId`.
      operationId: createTelephonyCall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agentId
              properties:
                agentId:
                  type: string
                  description: The agent to run this call. Must be ACTIVE.
                connectionType:
                  $ref: '#/components/schemas/ConnectionType'
                websocket:
                  $ref: '#/components/schemas/WebSocketOptions'
                metadata:
                  type: object
                  additionalProperties: true
                  description: Arbitrary values carried on the call record.
      responses:
        '201':
          description: Call session created
          headers:
            Location:
              schema:
                type: string
              description: Path of the created call resource.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  websocketUrl:
                    type: string
                    description: >
                      Short-lived, single-use URL to stream audio to. This is
                      the

                      field to read — there is no `joinUrl` in the response.
                  status:
                    type: string
                  connectionType:
                    type: string
                  agent:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      description:
                        type: string
                  createdAt:
                    type: string
                    format: date-time
        '400':
          description: Missing `agentId`, or an unsupported `connectionType`
        '402':
          description: Insufficient credits
        '404':
          description: Agent not found or inactive
        '429':
          description: Rate limit exceeded
components:
  schemas:
    ConnectionType:
      type: string
      enum:
        - twilio
        - telnyx
        - plivo
        - websocket
        - webrtc
      default: twilio
      description: |
        Which transport the returned `websocketUrl` is prepared for.

        `twilio` / `telnyx` / `plivo` — carrier media streams, **G.711 audio**.
        `websocket` — your own client; you choose the sample rates and codec.
        `webrtc` — browser transport, normally reached through the SDK.

        Any other value returns `400`.
    WebSocketOptions:
      type: object
      description: |
        Audio parameters. Only read when `connectionType` is `websocket` —
        telephony transports force G.711 at 8000 Hz regardless of what is sent
        here.
      required:
        - inputSampleRate
        - outputSampleRate
      properties:
        inputSampleRate:
          type: integer
          example: 16000
          description: |
            Sample rate of the audio you send, in Hz. **Required** when
            `connectionType` is `websocket` — omitting it returns `400`.
        outputSampleRate:
          type: integer
          example: 16000
          description: |
            Sample rate you want back, in Hz. **Required** when
            `connectionType` is `websocket`.
        codec:
          type: string
          enum:
            - pcm
            - g711
          default: g711
          description: '`pcm` for direct integrations, `g711` for telephony.'
        enableAudioBuffering:
          type: boolean
          description: Buffer audio to smooth jitter on unreliable links.
        twilioStream:
          type: boolean
          description: Format the stream for Twilio's `<Stream>` verb.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication

````