API & Webhooks

The API & Webhooks integration gives you programmatic access to BuildVoiceAI. Use the API to trigger outbound calls from your own applications, and configure webhooks to receive real-time call event data.

The API & Webhooks integration requires an Agency plan.

Prerequisites

A BuildVoiceAI account on the Agency plan
A server or application capable of making HTTP requests (for the API) and receiving them (for webhooks)

Setup

Generate an API Key

Navigate to Integrations in the sidebar
Find the API & Webhooks card and click Connect
Click Generate API Key
Copy the API key and store it securely

Your API key is shown only once when generated. If you lose it, you will need to generate a new one, which invalidates the previous key.

Enable/Disable API Access

You can toggle API access on or off without deleting your API key:

Go to Integrations → API & Webhooks
Use the Enable/Disable toggle

When disabled, all API requests will return a 403 Forbidden response.

Set a Webhook URL

To receive call event data, configure a webhook endpoint:

On the API & Webhooks integration page, find Webhook URL
Enter the URL of your server endpoint that will receive webhook events
Click Save

Default Agent

Select the default agent for API-triggered calls:

Find Default Agent on the integration page
Select an agent from the dropdown
Click Save

This agent is used when an API call request does not specify an agent_id.

API Authentication

Include your API key in the Authorization header of every request:


Authorization: Bearer your_api_key_here

All API requests must be made over HTTPS.

Triggering Outbound Calls

To trigger an outbound call via the API, send a POST request:


curl -X POST https://app.buildvoiceai.com/api/trigger-call \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15551234567",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "agent_id": "optional-agent-uuid"
  }'

Request Fields

Field	Type	Required	Description
`phone`	string	Yes	Phone number in E.164 format
`name`	string	No	Caller name, passed to the agent’s prompt context
`email`	string	No	Caller email
`agent_id`	string	No	UUID of the agent to use. Falls back to the default agent if omitted.
`metadata`	object	No	Arbitrary key-value pairs passed through to webhooks

Response

A successful request returns:


{
  "success": true,
  "call_id": "uuid-of-the-initiated-call"
}

Webhook Events

When a webhook URL is configured, BuildVoiceAI sends a POST request to your endpoint after each call completes.

Webhook Payload


{
  "event": "call.completed",
  "call_id": "uuid-of-the-call",
  "agent_id": "uuid-of-the-agent",
  "agent_name": "Sales Qualifier",
  "direction": "outbound",
  "phone_number": "+15551234567",
  "duration_seconds": 185,
  "started_at": "2025-06-15T14:30:00Z",
  "ended_at": "2025-06-15T14:33:05Z",
  "sentiment": "positive",
  "summary": "Caller expressed interest in the enterprise plan...",
  "transcript": [
    {
      "role": "agent",
      "content": "Hello, this is Sarah from Acme Corp. How can I help you today?",
      "timestamp": "2025-06-15T14:30:01Z"
    },
    {
      "role": "human",
      "content": "Hi, I was wondering about your pricing.",
      "timestamp": "2025-06-15T14:30:05Z"
    }
  ],
  "metadata": {
    "source": "your-custom-field"
  }
}

Webhook Security

Webhook requests include an X-Signature header containing an HMAC-SHA256 signature. Verify this signature on your server to ensure the request came from BuildVoiceAI:

Get the raw request body
Compute HMAC-SHA256 using your API key as the secret
Compare the result with the X-Signature header value

Retry Policy

If your webhook endpoint returns a non-2xx status code, BuildVoiceAI retries the request:

1st retry: 30 seconds after the initial attempt
2nd retry: 5 minutes after the 1st retry
3rd retry: 30 minutes after the 2nd retry

After 3 failed retries, the event is dropped. Failed webhook deliveries are logged and visible in the integration page.

Troubleshooting

API Returns 403

Verify API access is enabled on the integration page
Check that the API key in your Authorization header is correct
Ensure you are using Bearer token format

Webhook Not Receiving Events

Confirm your webhook URL is publicly accessible (not behind a firewall or VPN)
Verify the URL returns a 200 status code within 10 seconds
Check the webhook delivery log on the integration page for error details
Ensure HTTPS is used (HTTP endpoints are not supported)

Calls Not Being Placed

Verify the phone field is in E.164 format
Check that the default agent is set (or a valid agent_id is provided)
Ensure the agent has a phone number assigned
Confirm the calling window allows calls at the current time