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

# MCube Setup

> Configure MCube for outbound and inbound calling with the Vocobase API

# MCube Setup

This guide walks you through connecting your MCube account to Vocobase for outbound and inbound calling. MCube is a popular telephony provider in India with support for local and toll-free numbers.

## Prerequisites

* An [MCube](https://www.mcube.com) account with API access enabled
* Your MCube JWT authentication token
* Your MCube executive number
* Every inbound DID in E.164 format
* An approved Vocobase partner account with an API key

## Step 1: Get your MCube credentials

<Steps>
  <Step title="Log in to MCube">
    Sign in to your MCube dashboard or contact your MCube account manager.
  </Step>

  <Step title="Get your JWT token">
    MCube uses JWT tokens for API authentication. You can find your token in the MCube dashboard under **API Settings**, or request it from MCube support.

    <Warning>
      Keep your JWT token secret. It provides full access to your MCube calling capabilities.
    </Warning>
  </Step>

  <Step title="Get your executive number">
    The executive number is the agent/extension number assigned to your MCube account. It acts as the caller ID for outbound calls.

    Format: 4-15 digits, with an optional `+` prefix (e.g., `+919876543210`).
  </Step>
</Steps>

## Step 2: Configure MCube in Vocobase

MCube is a first-class BYOP provider on the [telephony connections](/telephony/connections) model. Create a named connection (recommended — every connection gets a stable `connection_id` you can pass to `POST /calls/start`):

```bash theme={null}
curl -X POST https://api.vocobase.com/api/v2/telephony/connections \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "mcube",
    "name": "Production MCube",
    "jwt_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "exe_number": "9876543232"
  }'
```

The exenumber is stored as the connection's default phone number (national format is fine — no `+` required) and is used as the line your outbound calls are placed from.

<Warning>
  The executive number identifies the MCube account; it is not the inbound DID list. Each dialed DID must be added separately before inbound calls can route to an agent.
</Warning>

Alternatively, the provider config shortcut below remains supported and creates or updates your default MCube connection:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT https://api.vocobase.com/api/v2/config/telephony/mcube \
    -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
    -H "Content-Type: application/json" \
    -d '{
      "jwt_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "exe_number": "+919876543210"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.vocobase.com/api/v2/config/telephony/mcube",
    {
      method: "PUT",
      headers: {
        "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        jwt_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        exe_number: "+919876543210"
      })
    }
  );
  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/mcube",
      headers={
          "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
          "Content-Type": "application/json"
      },
      json={
          "jwt_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
          "exe_number": "+919876543210"
      }
  )
  print(response.json())
  ```
</CodeGroup>

A successful response confirms your credentials were saved:

```json theme={null}
{
  "success": true,
  "data": {
    "exe_number": "+919876543210",
    "message": "MCube credentials updated successfully."
  }
}
```

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

## Step 3: Add and assign inbound DIDs

MCube does not expose a DID inventory endpoint that Vocobase pulls. Add the DIDs manually to the selected connection with `POST /api/v2/phone-numbers/sync`. Use E.164 format even if MCube sends the webhook DID without `+91`; Vocobase handles national-format suffix matching during inbound routing.

```bash theme={null}
curl -X POST https://api.vocobase.com/api/v2/phone-numbers/sync \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "MCUBE",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
    "numbers": ["+918071844607", "+918071844608"]
  }'
```

The request is idempotent. DIDs already present on this connection and duplicate values in the same request are skipped:

```json theme={null}
{
  "success": true,
  "data": {
    "added": 1,
    "skipped": 1,
    "updated": 0,
    "removed": 0
  }
}
```

List the connection's numbers to obtain each DID row ID:

```bash theme={null}
curl -X GET "https://api.vocobase.com/api/v2/phone-numbers?provider=MCUBE&connection_id=9b7f1c44-c87f-4f0c-9124-3c802a9c1a20" \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"
```

Assign the DID to an agent and enable inbound routing:

```bash theme={null}
curl -X PUT https://api.vocobase.com/api/v2/phone-numbers/f1a2c3d4-1111-2222-3333-444455556666 \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "inbound_enabled": true,
    "friendly_name": "MCube Support DID"
  }'
```

<Note>
  A DID may exist on more than one connection for outbound use, but only one active row for that DID can have `inbound_enabled: true`. This keeps inbound routing deterministic.
</Note>

To remove a manually added DID, use its row ID. The default exeNumber cannot be deleted through this endpoint.

```bash theme={null}
curl -X DELETE https://api.vocobase.com/api/v2/phone-numbers/f1a2c3d4-1111-2222-3333-444455556666 \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"
```

## Step 4: Make a test call

Start an outbound call using the `mcube` provider:

```bash 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": "mcube"
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "call_id": "c1234567-abcd-1234-abcd-123456789012",
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "status": "pending",
    "provider": "mcube",
    "from_number": "+919876543210",
    "to_number": "+911234567890",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
```

<Note>
  If you omit the `provider` field in the call request, MCube is used by default.
</Note>

If you have multiple MCube connections, pass `connection_id` to select one (omitting it with multiple active connections returns `CONNECTION_AMBIGUOUS`):

```json theme={null}
{
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "to_number": "+919876543210",
  "provider": "mcube",
  "connection_id": "tc_12345678-abcd-1234-abcd-123456789012"
}
```

## Troubleshooting

### "MCube not configured" error

You will receive a `400` error if you try to make a call with `"provider": "mcube"` before configuring credentials. Run `PUT /config/telephony/mcube` with valid credentials.

### "Invalid MCube credentials" error

* Verify your JWT token has not expired — MCube tokens may have an expiration date
* Confirm the executive number is correctly formatted (4-15 digits, optional `+` prefix)
* Contact MCube support to verify your API access is active

### Calls not connecting

* Ensure the destination number is reachable from your MCube account
* Check that your MCube account has sufficient balance
* Verify that API-initiated calls are enabled on your MCube plan

### Inbound call returns `unknown_number`

* Confirm the dialed DID was added to the same MCube `connection_id` selected by the webhook's exeNumber
* Store the DID in E.164 format, for example `+918071844607`
* Confirm the DID row has an owned `agent_id` and `inbound_enabled: true`
* Use `GET /api/v2/phone-numbers?provider=MCUBE&connection_id=...` to inspect the current mapping

### JWT token expired

MCube JWT tokens may have an expiration date. If calls start failing after a period of time, generate a new JWT token from MCube and update your configuration:

```bash theme={null}
curl -X PUT https://api.vocobase.com/api/v2/config/telephony/mcube \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "jwt_token": "new_jwt_token_here",
    "exe_number": "+919876543210"
  }'
```

## Updating credentials

To update your MCube credentials, call `PUT /config/telephony/mcube` again with the new values. Both fields (`jwt_token`, `exe_number`) are required each time. This updates your default MCube connection; additional named connections are managed through the [connections API](/telephony/connections).

## Next steps

<CardGroup cols={2}>
  <Card title="Twilio Setup" icon="phone" href="/telephony/twilio-setup">
    Configure Twilio as an alternative telephony provider.
  </Card>

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