> ## 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.

# Vobiz Setup

> Configure Vobiz for outbound calling with the Vocobase API

# Vobiz Setup

This guide walks you through connecting your Vobiz account to Vocobase for outbound calling.

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

## Prerequisites

* A [Vobiz account](https://www.vobiz.ai/) with a verified Auth ID and Auth Token
* At least one Vobiz phone number provisioned for outbound voice
* An approved Vocobase partner account with `"vobiz"` present in `allowed_telephony_providers` (check `GET /config`)

<Tip>
  If `"vobiz"` 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 Vobiz credentials

<Steps>
  <Step title="Log in to the Vobiz dashboard">
    Go to [vobiz.ai](https://www.vobiz.ai/) and sign in to your account.
  </Step>

  <Step title="Copy your Auth ID and Auth Token">
    From your account settings, copy your **Auth ID** and **Auth Token**.

    * **Auth ID** — identifier in the form `MA_XXXXXXXX`
    * **Auth Token** — alphanumeric string

    <Warning>
      Your Auth Token grants full access to your Vobiz account. Treat it like a password.
    </Warning>
  </Step>

  <Step title="Identify the phone number you will call from">
    From your Vobiz account, copy the 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 Vobiz in Vocobase

Send the credentials through the Partner API.

<Note>
  This endpoint updates your default Vobiz connection. To create multiple named Vobiz 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/vobiz \
    -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
    -H "Content-Type: application/json" \
    -d '{
      "auth_id": "MA_XXXXXXXX",
      "auth_token": "your_vobiz_auth_token",
      "from_number": "+918011223344"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.vocobase.com/api/v2/config/telephony/vobiz",
    {
      method: "PUT",
      headers: {
        "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        auth_id: "MA_XXXXXXXX",
        auth_token: "your_vobiz_auth_token",
        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/vobiz",
      headers={
          "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
          "Content-Type": "application/json"
      },
      json={
          "auth_id": "MA_XXXXXXXX",
          "auth_token": "your_vobiz_auth_token",
          "from_number": "+918011223344"
      }
  )
  print(response.json())
  ```
</CodeGroup>

A successful response confirms credentials were stored:

```json theme={null}
{
  "success": true,
  "data": {
    "auth_id": "MA_X****XXXX",
    "from_number": "+918011223344",
    "message": "Vobiz credentials updated successfully."
  }
}
```

<Tip>
  Your Auth Token is encrypted at rest and never returned in API responses. The Auth ID is masked.
</Tip>

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

Fetch your partner configuration — the response should now include Vobiz 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", "vobiz"],
    "telephony": {
      "twilio": { "configured": true, "account_sid": "conf****ured", "from_number": "+14155551111" },
      "mcube": { "configured": false, "exe_number": null },
      "exotel": { "configured": false, "account_sid": null, "subdomain": null, "caller_id": null, "applet_id": null },
      "plivo": { "configured": false, "auth_id": null, "from_number": null },
      "vobiz": { "configured": true, "auth_id": "conf****ured", "from_number": "+918011223344" }
    },
    "...": "..."
  }
}
```

`telephony.vobiz.configured: true` confirms the credentials landed and a default from-number is set. Presence in `allowed_telephony_providers` is what gates your ability to start a Vobiz call — if Vobiz 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": "vobiz"`. If your partner account has multiple active Vobiz 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": "vobiz",
      "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: "vobiz",
        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": "vobiz",
          "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": "vobiz",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
    "from_number": "+918011223344",
    "to_number": "+919876543210",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
```

Vocobase manages the carrier connection and media path for Vobiz. Partners only need to configure credentials and pass `"provider": "vobiz"` when starting calls. Passing only `"provider": "vobiz"` remains valid while there is exactly one active Vobiz connection.

## Optional: voicemail detection

For Vobiz outbound calls, supported accounts can enable carrier-side voicemail detection per agent. Set `voicemail_detection_enabled` to control detection for that agent. When Vobiz reports voicemail, Vocobase marks the call as voicemail and ends the call.

The same agent field, `voicemail_message`, is accepted for API parity and for providers that can play a post-detection message. Vobiz currently uses the hangup behavior above.

<Note>
  Carrier-side voicemail detection must be enabled for your Vobiz connection by Vocobase before these agent settings affect live calls.
</Note>

```bash theme={null}
curl -X PUT https://api.vocobase.com/api/v2/agent/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "voicemail_detection_enabled": true,
    "voicemail_message": "Hi, this is Priya from Acme Corp. I will call you back soon."
  }'
```

## Troubleshooting

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

* Confirm `"vobiz"` is in `allowed_telephony_providers` from `GET /config`. If it is not, contact your Vocobase account manager.

### `CONNECTION_AMBIGUOUS` error

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

### 401 from Vobiz during verification

* Auth ID or Auth Token is wrong. Re-copy them from your Vobiz account settings.
* If you recently rotated the Auth Token in Vobiz, send `PUT /config/telephony/vobiz` again with the new token.

### Calls ring but drop immediately

* Confirm the destination number is reachable from your Vobiz account. Some Vobiz accounts have geographic restrictions that require explicit enablement.
* Check the Vobiz call logs for the exact reason the call was dropped (e.g., "Invalid from number", "No route to destination").

### Caller ID shows the wrong number or "Unknown"

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

## Updating credentials

Rotate the Auth Token in Vobiz, then update Vocobase by re-sending `PUT /api/v2/config/telephony/vobiz` with the new token.

## Next steps

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

  <Card title="Plivo Setup" icon="phone" href="/telephony/plivo-setup">
    Configure Plivo as an additional telephony provider.
  </Card>

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