> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voxfra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup Guide

> Step-by-step: create a Voxfra inbound webhook and configure your voice provider to deliver call reports.

## Overview

Connecting a voice AI provider to Voxfra takes two steps:

1. **Create the inbound webhook** in the Voxfra admin console — this gives you a unique URL for the client.
2. **Configure your provider** to POST call events to that URL.

This guide walks through the core setup steps for the current supported provider.

At the moment, that means Vapi. Additional providers will be added here as they move from review into production support.

For a dedicated provider reference, see [Vapi](/webhook-integration/vapi).

***

## Step 1 — Create an inbound webhook in Voxfra

<Steps>
  <Step title="Open client settings">
    In the admin console, navigate to your organization, select the **client** you want to connect, then open **Settings → Webhooks → Inbound**.
  </Step>

  <Step title="Create a webhook endpoint">
    Click **Create Webhook**. In the dialog:

    * **Provider** — select the voice platform you use (e.g. `Vapi`).
    * **Advanced security & access** *(optional)* — expand to configure:
      * **IP allowlist** — restrict incoming requests to your provider's IP ranges.
      * **HMAC Secret** — generate or paste a secret for payload signature verification. Save this value — it is shown only once.

    Click **Create Webhook**.
  </Step>

  <Step title="Copy the webhook URL">
    After creation, the dialog shows your unique webhook URL:

    ```
    https://api.voxfra.com/webhook/vapi/{your-slug}
    ```

    Copy it — you'll paste it into your provider's dashboard in the next step. The URL is also accessible any time from the **Inbound** tab.
  </Step>
</Steps>

***

## Step 2 — Configure your provider

### Vapi

<Info>
  Vapi supports server URLs at three levels — **organization**, **assistant**, and **phone number** — in ascending priority. We recommend setting the Voxfra URL at the **assistant** level so it applies precisely to the assistant you want tracked and does not interfere with other org-level configuration.
</Info>

<Steps>
  <Step title="Open the assistant in Vapi">
    Go to your [Vapi dashboard](https://dashboard.vapi.ai) → **Assistants** → select the assistant that handles calls for this client.
  </Step>

  <Step title="Set the server URL">
    In the assistant editor, scroll to **Advanced → Server URL** (or **Server Configuration** depending on UI version) and paste the webhook URL you copied from Voxfra.

    ```
    https://api.voxfra.com/webhook/vapi/{your-slug}
    ```

    <Tip>
      Setting the URL at the **assistant level** gives it the second-highest priority in Vapi's hierarchy (phone number → assistant → organization). This ensures calls from this assistant always reach the correct Voxfra client endpoint, regardless of any org-level server URL you may have set.
    </Tip>
  </Step>

  <Step title="Select the end-of-call-report message type">
    Under **Server Messages**, enable **`end-of-call-report`** and disable any message types you don't need. Voxfra expects the end-of-call report and ignores other message types.

    Sending only `end-of-call-report` reduces noise and keeps your rate limit headroom clear.

    <Frame>
      See [Vapi — Setting Server URLs](https://docs.vapi.ai/server-url/setting-server-urls) for the full reference on server URL priority and message type selection.
    </Frame>
  </Step>

  <Step title="Save and test">
    Save the assistant. Run a test call, then return to Voxfra **Settings → Webhooks → Inbound** and confirm the **Last Used** timestamp and **Requests** count have updated for your endpoint.
  </Step>
</Steps>

**Vapi minimum payload** — Voxfra reads the following fields from the end-of-call report:

| Field                             | Required    | Notes                           |
| --------------------------------- | ----------- | ------------------------------- |
| `call.id`                         | Yes         | Used for idempotency            |
| `call.status`                     | Yes         | Must be `completed`             |
| `call.startedAt` / `call.endedAt` | Yes         | ISO 8601 timestamps             |
| `customer.number`                 | Yes         | Caller phone number             |
| `transcript`                      | Recommended | Full call transcript            |
| `recordingUrl`                    | Optional    | Direct audio link               |
| `analysis.summary`                | Optional    | Populated by Vapi if configured |
| `analysis.sentiment`              | Optional    |                                 |
| `analysis.intent`                 | Optional    |                                 |

***

### Additional providers

Retell, Bland, LiveKit, and ElevenLabs are currently under review. This guide will expand as those integrations move into production support.

***

## Verifying delivery

Once configured, every inbound call report appears on the **Inbound** tab of client settings. For each endpoint you can see:

| Column        | What it shows                             |
| ------------- | ----------------------------------------- |
| **Status**    | `active` / `inactive` / `revoked`         |
| **Requests**  | Total payloads received                   |
| **Last Used** | Timestamp of the most recent delivery     |
| **HMAC**      | Whether signature verification is enabled |

Click any row to view details, update the IP allowlist, toggle HMAC verification, or replace the endpoint with a new URL.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Requests count is not incrementing">
    * Confirm the webhook URL is pasted correctly in your provider dashboard — no trailing spaces or missing characters.
    * For Vapi, verify the `end-of-call-report` message type is enabled in the assistant's server messages list.
    * Check that the endpoint status in Voxfra is `active`, not `inactive` or `revoked`.
    * Run a test call and inspect provider-side delivery logs for any HTTP errors returned by Voxfra.
  </Accordion>

  <Accordion title="Getting 404 responses">
    The slug was not found or the endpoint is inactive. Either the URL was copied incorrectly or the endpoint has been revoked. Generate a new webhook URL in Voxfra and update your provider configuration.
  </Accordion>

  <Accordion title="Getting 429 rate limit errors">
    The default rate limit is 1,000 requests per minute per endpoint. If you're hitting this with legitimate traffic, contact [support@voxfra.com](mailto:support@voxfra.com) to have the limit raised.
  </Accordion>

  <Accordion title="HMAC verification failing">
    Ensure the HMAC secret in your provider's webhook settings matches exactly what was generated in Voxfra (no extra whitespace). If you've lost the secret, replace the webhook endpoint — this generates a new URL and a new secret.
  </Accordion>
</AccordionGroup>