# 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dataqueue.gitbook.io/voicehub-docs/api-reference/webcall-api-v1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.