Calls

Create and manage voice calls

Create voice call

post

Create a voice call session with your agent.

Supports multiple connection types:

• webrtc - For browser-based voice calls

• twilio - For Twilio telephony connections (default)

• telnyx - For Telnyx telephony provider

• plivo - For Plivo telephony provider

• websocket - For custom WebSocket integrations (requires inputSampleRate and outputSampleRate)

Returns a WebSocket URL for the voice connection.

WebSocket Protocol (websocket connection type only)

The WebSocket connection carries:

• Binary frames: PCM s16le audio data

• Text frames: JSON messages (see schemas below)

Supported Messages

Client Tool Execution:

• client_tool_invocation - Received when agent invokes a client tool

• client_tool_result - Send your tool execution response

Call Status:

• call_started - Received when call is ready

• state - Received on agent state changes (idle, listening, thinking, speaking)

Important: When you receive a client_tool_invocation, you must respond with client_tool_result using the same invocationId value.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

API key for authentication

Body

application/json

agentIdstringRequired

The ID of the agent to use for this call

connectionTypestring · enumOptional

The connection type for the call. Use 'webrtc' for browser-based calls

Default: twilioPossible values:

Responses

201

Call created successfully

application/json

post

/calls/create

HTTPcURLJavaScriptPython

POST /api/v1/calls/create HTTP/1.1
Host: api.omnia-voice.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 149

{
  "agentId": "text",
  "connectionType": "twilio",
  "websocket": {
    "inputSampleRate": 1,
    "outputSampleRate": 1
  },
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

201

Call created successfully

{
  "id": "text",
  "websocketUrl": "https://example.com",
  "status": "created",
  "connectionType": "webrtc",
  "agent": {
    "id": "text",
    "name": "text",
    "description": "text"
  },
  "createdAt": "2025-12-13T09:37:34.144Z"
}

Get call details

get

Retrieve details of a specific call

Authorizations

ApiKeyAuth

X-API-KeystringRequired

API key for authentication

Path parameters

idstringRequired

Call ID

Responses

200

Successful response

application/json

get

/calls/{id}

HTTPcURLJavaScriptPython

GET /api/v1/calls/{id} HTTP/1.1
Host: api.omnia-voice.com
X-API-Key: YOUR_API_KEY
Accept: */*

200

Successful response

{
  "id": "text",
  "startTime": "2025-12-13T09:37:34.144Z",
  "endTime": "2025-12-13T09:37:34.144Z",
  "duration": 1,
  "status": "text",
  "summary": "text",
  "shortSummary": "text",
  "transcript": "text"
}

Create inline voice call

post

Create a voice call session with inline configuration (no predefined agent required).

This endpoint enables stateless integration where you pass configuration and tools directly in each request. Perfect for:

• SIP/telephony integrations where config varies per call

• Dynamic agent behavior without managing agent records

• Testing different configurations without creating agents

• External systems that manage their own agent logic

Unlike /calls/create which requires a predefined agent, this endpoint accepts:

• systemPrompt - Agent behavior and personality

• voice - Voice ID to use

• language - Primary language

• selectedTools - Tools in temporaryTool format (optional)

• model, temperature, firstSpeaker - Optional overrides

WebSocket Protocol (websocket connection type only)

The WebSocket connection carries:

• Binary frames: PCM s16le audio data

• Text frames: JSON messages (see schemas below)

Received Messages (Server → Client)

• call_started - Call is initialized and ready

• state - Agent state changes (idle, listening, thinking, speaking)

• client_tool_invocation - Agent invokes a client tool

Sent Messages (Client → Server)

• client_tool_result - Response to tool invocation (must use same invocationId)

• hang_up - Gracefully end the call

Important: When you receive a client_tool_invocation, you must respond with client_tool_result using the same invocationId value within 2-3 seconds.

Tool Format

Tools must be provided in the temporaryTool format:

HTTP Tool Example:

{
  "temporaryTool": {
    "modelToolName": "checkInventory",
    "description": "Check product inventory levels",
    "dynamicParameters": [{
      "name": "productId",
      "location": "PARAMETER_LOCATION_PATH",
      "schema": {"type": "string", "description": "Product ID"},
      "required": true
    }],
    "http": {
      "baseUrlPattern": "https://api.example.com/inventory/{productId}",
      "httpMethod": "GET"
    }
  }
}

Client Tool Example:

{
  "temporaryTool": {
    "modelToolName": "transferCall",
    "description": "Transfer call to human agent",
    "dynamicParameters": [{
      "name": "department",
      "schema": {"type": "string", "description": "Department name"},
      "required": true
    }],
    "client": {}
  }
}

SIP Integration Notes

When using connectionType: websocket for SIP/telephony integration:

• Set inputSampleRate and outputSampleRate to match your SIP system (typically 8000 for G.711)

• Audio format is PCM s16le (16-bit) - you must transcode from G.711 ulaw if needed

• Use client tools for call control since they execute via the same WebSocket as audio

• HTTP tools work but require your SIP system to handle callbacks

Authorizations

ApiKeyAuth

X-API-KeystringRequired

API key for authentication

Body

application/json

Request body for creating a stateless inline call without a predefined agent. Pass configuration and tools directly in the request.

systemPromptstringRequired

The system prompt that defines the agent's behavior and personality

Example: You are a helpful customer service assistant for Acme Corp.

voicestringRequired

Voice ID to use for the agent (e.g., "Mark", "Jessica")

Example: Mark

languagestringRequired

Primary language for the conversation (BCP-47 language code)

Example: en

modelstringOptional

AI model to use

Default: fixie-ai/ultravox-qwen3-32b-previewExample: fixie-ai/ultravox-qwen3-32b-preview

temperaturenumber · max: 1Optional

Temperature for AI responses (0.0 to 1.0)

Default: 0

firstSpeakerstring · enumOptional

Who speaks first when the call starts

Default: agentPossible values:

recordingEnabledbooleanOptional

Whether to record the call

Default: true

connectionTypestring · enumOptional

The connection type for the call

Default: twilioPossible values:

Responses

201

Call created successfully

application/json

400

Bad request - missing or invalid parameters

application/json

402

Payment required - insufficient balance

application/json

500

Server error

application/json

post

/calls/inline

HTTPcURLJavaScriptPython

POST /api/v1/calls/inline HTTP/1.1
Host: api.omnia-voice.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 135

{
  "systemPrompt": "You are a helpful customer service assistant for Acme Corp.",
  "voice": "Mark",
  "language": "en",
  "connectionType": "webrtc"
}

Basic inline callWebSocket call with client tool

{
  "id": "call_abc123",
  "websocketUrl": "wss://voice.example.com/abc123",
  "status": "created",
  "connectionType": "websocket",
  "createdAt": "2025-01-09T12:00:00Z"
}

Initiate outbound call

post

Initiate an outbound call to a phone number using your agent.

You must provide either:

• fromNumberId - The ID of your configured phone number (get from /numbers endpoint)

• fromNumber - The raw phone number to call from (must be configured in your account)

The call will be initiated immediately through Twilio using your configured credentials. Billing will be charged at €0.20 per minute upon call completion.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

API key for authentication

Body

application/json

agentIdstringRequired

The ID of the agent to use for this call

phoneNumberstringRequired

The phone number to call (E.164 format, e.g., [phone])

fromNumberIdstringOptional

The ID of your configured phone number to call from (get from /numbers endpoint)

fromNumberstringOptional

The raw phone number to call from (must be configured in your account). Use either this or fromNumberId

Responses

201

Call initiated successfully

application/json

400

Bad request - missing or invalid parameters

application/json

402

Payment required - insufficient balance

application/json

404

Agent or phone number not found

application/json

post

/calls/outbound

HTTPcURLJavaScriptPython

POST /api/v1/calls/outbound HTTP/1.1
Host: api.omnia-voice.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 81

{
  "agentId": "text",
  "phoneNumber": "text",
  "fromNumberId": "text",
  "fromNumber": "text"
}

{
  "id": "text",
  "sessionId": "text",
  "status": "text",
  "websocketUrl": "https://example.com",
  "phoneNumber": "text",
  "fromNumber": "text",
  "agent": {
    "id": "text",
    "name": "text",
    "description": "text"
  },
  "createdAt": "2025-12-13T09:37:34.144Z"
}