# API – Click-to-Call

Use the VoiceB API to trigger outbound calls automatically. Ideal for form submissions, lead callbacks, or click-to-call features from your website or CRM.

To enable API-triggered outbound calls in VoiceB.ai, the configuration is done **at the agent level**.

Before you can access your API credentials and endpoint:

1. Go to your agent’s configuration screen
2. Set the **Type** to `Click to Call`
3. Click **Save**
4. The **"Show Credentials & Instructions"** button will then appear

Clicking that button reveals your **API Token**, **Secret**, and full usage instructions — all specific to that agent.

> ⚠️ Each agent has its own credentials and endpoint. Make sure you configure and save the correct agent before using the API.

<figure><img src="/files/AdbAHNuP6YoKbcFsAo1J" alt=""><figcaption></figcaption></figure>

Once configured, you’ll be able to securely trigger real-time outbound calls from your backend or product flows.

***

### 🔐 API Authentication

You’ll need:

* `API Token`
* `API Secret`

> 📌 Credentials are available in  **Agent -> Show Credentials & Instructions** in your VoiceB.ai dashboard.

Always trigger calls **from your backend** to avoid exposing secrets.

{% hint style="info" %}
If you need to trigger a call from a system that can't sign the request, like Pardot, check the option **Disable Signature Verification** from agent configuration.&#x20;
{% endhint %}

***

### 📍 Endpoint

```
POST https://app.voiceb.ai/api/click-to-call
```

### 🧪 Sample Request Payload

```json
{
  "phone": "+34612345678",
  "variables": {
      "name": "John",
      "product": "VoiceB AI"
  }
}
```

***

### 🔐 Headers

* `api-key`: your API Token
* `signature`: HMAC SHA256 of the request body using your API Secret

***

#### 📦 Variables

The `variables` object in the request allows you to send data that can be utilized during interactions with the AI agent. By including specific key-value pairs, you can tailor the conversation and provide context or parameters that the AI can use to generate more accurate and relevant responses.

To utilize variables defined in the request, you need to explicitly reference them in your script using `{{variable name}}`. For example, if your request includes `"name": "John"` and `"product": "VoiceB AI"`, your script should instruct the agent with something like: "The client's name is `{{name}}` and is interested in `{{product}}`." Additionally, avoid using variables prefixed with "voiceb" or "system" to prevent conflicts with reserved system variables.

It is essential to explicitly reference all necessary variables in your script, as failing to do so may result in unsuccessful calls. The request may include any number of variables, but ensure that all required ones are clearly specified. For optional variables, it is acceptable to have them as empty strings, but they should never be undefined to avoid potential errors.

***

### 🧰 Error Codes

| **Code** | **Message**              | **Status** |
| -------- | ------------------------ | ---------- |
| ctc:001  | Missing headers          | 400        |
| ctc:002  | Error fetching agent     | 500        |
| ctc:003  | Invalid API key          | 403        |
| ctc:004  | Agent is disabled        | 400        |
| ctc:005  | Agent not configured     | 400        |
| ctc:006  | Invalid signature        | 403        |
| ctc:007  | Call already in progress | 400        |
| ctc:008  | Error initiating call    | 500        |

***

### 🔧 Code Samples

#### Node.js

```javascript
const axios = require('axios');
const crypto = require('crypto');

const API_KEY = process.env.API_KEY;
const SECRET_KEY = process.env.SECRET_KEY;
const ENDPOINT = process.env.ENDPOINT;

function generateSignature(secret, data) {
  return crypto.createHmac('sha256', secret).update(data).digest('hex');
}

async function makeRequest() {
  const body = {
    phone: '+34612345678',
    variables: {
      name: "John",
      product: "VoiceB AI"
    }
  };
  const textBody = JSON.stringify(body);
  const signature = generateSignature(SECRET_KEY, textBody);

  try {
    const response = await axios.post(ENDPOINT, body, {
      headers: {
        'api-key': API_KEY,
        'signature': signature,
        'Content-Type': 'application/json',
      },
    });

    console.log('Response:', response.data);
  } catch (error) {
    console.error('Error making request:', error.response ? error.response.data : error.message);
  }
}

makeRequest();
```

#### Python

```python
import os
import hmac
import hashlib
import requests
import json

API_KEY = os.getenv('API_KEY')
SECRET_KEY = os.getenv('SECRET_KEY')
ENDPOINT = os.getenv('ENDPOINT')

def generate_signature(secret, data):
    return hmac.new(secret.encode(), data.encode(), hashlib.sha256).hexdigest()

def make_request():
    body = {
        'phone': '+34612345678',
        'variables': {
            'name': 'John',
            'product': 'VoiceB AI'
        }
    }
    text_body = json.dumps(body)
    signature = generate_signature(SECRET_KEY, text_body)

    headers = {
        'api-key': API_KEY,
        'signature': signature,
        'Content-Type': 'application/json',
    }

    response = requests.post(ENDPOINT, headers=headers, data=text_body)
    print('Response:', response.json())

if __name__ == '__main__':
    make_request()
```

***


---

# 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://docs.voiceb.ai/api-click-to-call.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.