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.

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.

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.

---

📍 Endpoint

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

🧪 Sample Request Payload

{
  "phone": "[phone]",
  "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

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: '[phone]',
    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

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': '[phone]',
        '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()

---