> For the complete documentation index, see [llms.txt](https://dataqueue.gitbook.io/voicehub-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dataqueue.gitbook.io/voicehub-docs/api-reference/webcall-api-v1.md).

# WebCall API V1

This document explains how to initiate a new web call through our API. Creating a call provides you with a unique `callId` and a WebSocket path, which you can then use to establish a real-time connection and interact with the agent.

#### `POST /calls/public/create-web-call`

Creates a new **web-based call session** authenticated via API key.

* **Response:** Returns a unique `callId` and a `webSocketPath`.
* **Usage:** Clients (such as web widgets) can use the returned path to establish a **real-time WebSocket connection** with the call for live interaction with the agent.

***

#### 🔐 Authentication

**Prerequisite:** This endpoint requires a valid **API access key**.

**Required headers:**

```http
x-api-access-key: <API_KEY>
voicehub-agent-id: <yourAgentId>
Content-Type: application/json
```

<table><thead><tr><th width="205.74609375">Header</th><th>Description</th></tr></thead><tbody><tr><td><code>voicehub-agent-id</code></td><td>Dataqueue Agent Id used to register this call.<br>Note: All your agent configuration will apply for this call.</td></tr><tr><td><code>x-api-access-key</code></td><td>API key for authenticating the request</td></tr><tr><td><code>Content-Type</code></td><td>Must be <code>application/json</code></td></tr></tbody></table>

***

#### 🧾 Request Body

```json
{
  "type": "text | WebAudio | TextAudio",
}
```

**Field descriptions:**

<table><thead><tr><th width="103.5">Field</th><th width="83.2578125">Type</th><th width="550.8515625">Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Defines the call mode:<br>• <strong>text</strong> – Text-only chat with the agent.<br>• <strong>WebAudio</strong> – Audio-only conversation with the agent.<br>• <strong>TextAudio</strong> – Combined text and audio communication with the agent.</td></tr></tbody></table>

***

#### ✅ Example Request

```json
{
  "type": "WebAudio",
}
```

***

#### 🌐 CORS

This endpoint supports cross-origin requests.

```http
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type, Authorization, voicehub-agent-id, x-api-access-key
```

***

#### 💻 Example cURL

```bash
curl -X POST "https://voicehub.dataqueue.ai/calls/public/create-web-call" \
  -H "Content-Type: application/json" \
  -H "voicehub-agent-id: agent_123" \
  -H "x-api-access-key: sk_live_abc123" \
  -d '{
    "type": "TextAudio"
  }'
```

#### 📤 Response

**Status: 201 Created**

```json
{
  "callId": "<call-shortuuid>",
  "webCallSocketPath": "<socket path>"
}
```

<table><thead><tr><th width="176.07421875">Field</th><th width="106.4296875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>callId</code></td><td>string</td><td>A <strong>unique identifier</strong> for the newly created call session.</td></tr><tr><td><code>webCallSocketPath</code></td><td>string</td><td>The URL path used to establish a <strong>real-time WebSocket connection</strong> with the agent for live interaction and communication.</td></tr></tbody></table>

***

#### ❌ Error Responses

| Status | Description           |
| ------ | --------------------- |
| 400    | Misconfigured agent   |
| 401    | Invalid API key       |
| 403    | Insufficient credits  |
| 405    | Operation not allowed |

***

After sending this request, the response includes a `callId` and a `webCallSocketPath`. Use this path to establish a **WebSocket connection** and interact with the agent in real time using the `callId`.\
For detailed instructions on connecting to the call via WebSocket, see[WebCall Socket V1](/voicehub-docs/api-reference/webcall-api-v1/webcall-socket-v1.md)