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

# VoiceLink Setup

> Configure VoiceLink for inbound and outbound calling with Vocobase

# VoiceLink Setup

This guide walks you through connecting your VoiceLink account to Vocobase for inbound and outbound calling.

<Note>
  Configure VoiceLink with the Partner API (`PUT /api/v2/config/telephony/voicelink`) for the default connection. To create multiple named VoiceLink connections, use `POST /api/v2/telephony/connections`. Once VoiceLink is configured, start calls programmatically using `POST /calls/start` with `"provider": "voicelink"`.
</Note>

## Prerequisites

* A VoiceLink account with a panel **username and password**
* At least one VoiceLink DID (phone number) provisioned for voice
* An approved Vocobase partner account with `"voicelink"` present in `allowed_telephony_providers` (check `GET /config`)

<Tip>
  If `"voicelink"` is not yet listed in your partner config's `allowed_telephony_providers`, contact your Vocobase account manager to enable it.
</Tip>

## Step 1: Get your VoiceLink credentials

<Steps>
  <Step title="Find your VoiceLink panel sign-in">
    Use the same **username and password** you use to sign in to the VoiceLink panel. Vocobase logs in with these to obtain a short-lived access token when it calls the VoiceLink API on your behalf — your password is stored encrypted and never sent back to you.

    <Warning>
      These credentials grant full access to your VoiceLink account. Treat them like any other production secret.
    </Warning>
  </Step>

  <Step title="Identify the DID you will call from">
    Copy the VoiceLink number you plan to use as the caller ID.

    The number must be in E.164 format (e.g., `+918011223344`) and must be enabled for outbound voice.
  </Step>
</Steps>

## Step 2: Configure VoiceLink in Vocobase

Send the credentials through the Partner API. `username`, `password`, and `from_number` are required; `base_url` is optional and defaults to the VoiceLink API host.

<Note>
  This endpoint updates your default VoiceLink connection. To create multiple named VoiceLink connections, use `POST /api/v2/telephony/connections` and store the returned `connection_id`.
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT https://api.vocobase.com/api/v2/config/telephony/voicelink \
    -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
    -H "Content-Type: application/json" \
    -d '{
      "username": "acme-voice",
      "password": "your-voicelink-password",
      "from_number": "+918011223344"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.vocobase.com/api/v2/config/telephony/voicelink",
    {
      method: "PUT",
      headers: {
        "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        username: "acme-voice",
        password: "your-voicelink-password",
        from_number: "+918011223344"
      })
    }
  );
  const result = await response.json();
  console.log(result);
  ```

  ```python Python theme={null}
  import requests

  response = requests.put(
      "https://api.vocobase.com/api/v2/config/telephony/voicelink",
      headers={
          "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
          "Content-Type": "application/json"
      },
      json={
          "username": "acme-voice",
          "password": "your-voicelink-password",
          "from_number": "+918011223344"
      }
  )
  print(response.json())
  ```
</CodeGroup>

A successful response confirms credentials were stored:

```json theme={null}
{
  "success": true,
  "data": {
    "username": "acme-voice",
    "from_number": "+918011223344",
    "base_url": null,
    "message": "VoiceLink credentials updated successfully."
  }
}
```

<Tip>
  Your password is encrypted at rest and never returned in API responses.
</Tip>

### Optional: custom base URL

If VoiceLink gave you a dedicated API host, pass it as `base_url`. Omit the field to use the default host.

```bash theme={null}
curl -X PUT https://api.vocobase.com/api/v2/config/telephony/voicelink \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "acme-voice",
    "password": "your-voicelink-password",
    "from_number": "+918011223344",
    "base_url": "https://app.voicelink.co.in"
  }'
```

## Step 3: Confirm the partner sees VoiceLink as configured

Fetch your partner configuration — the response should now include VoiceLink in `allowed_telephony_providers`:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.vocobase.com/api/v2/config \
    -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"
  ```
</CodeGroup>

```json theme={null}
{
  "success": true,
  "data": {
    "name": "acme-corp",
    "allowed_telephony_providers": ["twilio", "voicelink"],
    "telephony": {
      "twilio": { "configured": true, "account_sid": "conf****ured", "from_number": "+14155551111" },
      "voicelink": { "configured": true, "allowed": true, "username": "acme-voice", "base_url": null, "from_number": "+918011223344" }
    },
    "...": "..."
  }
}
```

`telephony.voicelink.configured: true` confirms the credentials and from-number landed. Presence in `allowed_telephony_providers` is what gates your ability to start a VoiceLink call — if VoiceLink isn't in that list, contact your Vocobase account manager to enable it.

## Step 4: Make a test call

Start an outbound call with `"provider": "voicelink"`. If your partner account has multiple active VoiceLink connections, include `connection_id`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.vocobase.com/api/v2/calls/start \
    -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
    -H "Content-Type: application/json" \
    -d '{
      "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "to_number": "+919876543210",
      "provider": "voicelink",
      "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.vocobase.com/api/v2/calls/start",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        agent_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        to_number: "+919876543210",
        provider: "voicelink",
        connection_id: "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
      })
    }
  );
  const result = await response.json();
  console.log(result);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.vocobase.com/api/v2/calls/start",
      headers={
          "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
          "Content-Type": "application/json"
      },
      json={
          "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "to_number": "+919876543210",
          "provider": "voicelink",
          "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
      }
  )
  print(response.json())
  ```
</CodeGroup>

```json theme={null}
{
  "success": true,
  "data": {
    "call_id": "c1234567-abcd-1234-abcd-123456789012",
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "status": "pending",
    "provider": "voicelink",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
    "from_number": "+918011223344",
    "to_number": "+919876543210",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
```

VoiceLink uses a Generic WebSocket media model. Vocobase manages the media path; partners only need to configure credentials and pass `"provider": "voicelink"` when starting calls. Passing only `"provider": "voicelink"` remains valid while there is exactly one active VoiceLink connection.

<Note>
  Inbound calling is configured per DID through the guided dashboard workflow or `POST /api/v2/voicelink/inbound-ready`. Call transfer support depends on the active VoiceLink media integration and remains outside this setup guide.
</Note>

## Managing DIDs

The `from_number` you send is stored as the default outbound DID. To manage multiple VoiceLink DIDs, create named V2 telephony connections and select the desired one with `connection_id` when starting outbound calls.

For inbound setup, client and DID mapping, sync, and readiness checks, use the [VoiceLink Management](/telephony/voicelink-management) guide. It documents the safe inbound/outbound composers under `/api/v2/voicelink/*`, including `connection_id` support for multiple active VoiceLink connections.

## Troubleshooting

### "VoiceLink not configured" or 403 on `/calls/start`

* Confirm `"voicelink"` is in `allowed_telephony_providers` from `GET /config`. If it is not, contact your Vocobase account manager.
* Confirm `username`, `password`, and a `from_number` were saved (`telephony.voicelink.configured: true`).

### `CONNECTION_AMBIGUOUS` error

* Your account has multiple active VoiceLink connections. Call `GET /api/v2/telephony/connections?provider=voicelink` and pass the desired `connection_id` in `POST /api/v2/calls/start`.

### "Invalid VoiceLink username or password"

* Re-check the credentials against the VoiceLink panel sign-in. Re-send `PUT /config/telephony/voicelink` with the correct values.

### Calls ring but drop immediately

* Confirm the destination number is reachable from your VoiceLink account.
* Check the VoiceLink panel call logs for the exact drop reason.

### Caller ID shows the wrong number

* The `from_number` saved on your Vocobase VoiceLink connection must match a number VoiceLink has provisioned for your account, in E.164 format. Update it via `PUT /config/telephony/voicelink` if it does not.

## Updating credentials

Changed your VoiceLink password? Re-send `PUT /api/v2/config/telephony/voicelink` with the new `password`. This endpoint always requires `username`, `password`, and `from_number` together, so include all three (plus `base_url` if you use a custom host) whenever you update.

## Next steps

<CardGroup cols={2}>
  <Card title="Telephony Connections" icon="settings" href="/telephony/connections">
    Create and manage multiple named connections.
  </Card>

  <Card title="VoiceLink Management" icon="settings" href="/telephony/voicelink-management">
    Manage clients, DIDs, mapping, and readiness.
  </Card>

  <Card title="Bring Your Own Phone" icon="phone" href="/telephony/byop-setup">
    Overview of all supported BYOP providers.
  </Card>

  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Create an agent and make your first call.
  </Card>
</CardGroup>