VoiceLink Management

Make a VoiceLink DID call-ready

Runs the safe outbound call-ready workflow for a purchased VoiceLink DID: import the DID into Vocobase if missing, optionally map an unmapped DID to an explicitly supplied client_id, ensure an active VoiceLink WebSocket bot for the mapped client, and ensure outbound routing points to that bot. Existing inbound routing is preserved on routing updates. DID mapping happens only with an explicit client_id and only when the DID is currently unmapped — a DID mapped to a different client is never re-mapped, and clients are never auto-created. This endpoint does not purchase, renew, run KYC, or allocate wallet credit. Pass connection_id when the partner has more than one active VoiceLink connection.

POST

voicelink

call-ready

curl --request POST \
  --url https://api.vocobase.com/api/v2/voicelink/call-ready \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
  "did_id": 812,
  "client_id": 415,
  "agent_id": "f4df9f8c-df95-46d8-bb0e-6f9f83fd4f55",
  "bot_name": "Vocobase +918011223344"
}
'

import requests

url = "https://api.vocobase.com/api/v2/voicelink/call-ready"

payload = {
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
    "did_id": 812,
    "client_id": 415,
    "agent_id": "f4df9f8c-df95-46d8-bb0e-6f9f83fd4f55",
    "bot_name": "Vocobase +918011223344"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    connection_id: '9b7f1c44-c87f-4f0c-9124-3c802a9c1a20',
    did_id: 812,
    client_id: 415,
    agent_id: 'f4df9f8c-df95-46d8-bb0e-6f9f83fd4f55',
    bot_name: 'Vocobase +918011223344'
  })
};

fetch('https://api.vocobase.com/api/v2/voicelink/call-ready', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vocobase.com/api/v2/voicelink/call-ready",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'connection_id' => '9b7f1c44-c87f-4f0c-9124-3c802a9c1a20',
    'did_id' => 812,
    'client_id' => 415,
    'agent_id' => 'f4df9f8c-df95-46d8-bb0e-6f9f83fd4f55',
    'bot_name' => 'Vocobase +918011223344'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vocobase.com/api/v2/voicelink/call-ready"

	payload := strings.NewReader("{\n  \"connection_id\": \"9b7f1c44-c87f-4f0c-9124-3c802a9c1a20\",\n  \"did_id\": 812,\n  \"client_id\": 415,\n  \"agent_id\": \"f4df9f8c-df95-46d8-bb0e-6f9f83fd4f55\",\n  \"bot_name\": \"Vocobase +918011223344\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vocobase.com/api/v2/voicelink/call-ready")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"connection_id\": \"9b7f1c44-c87f-4f0c-9124-3c802a9c1a20\",\n  \"did_id\": 812,\n  \"client_id\": 415,\n  \"agent_id\": \"f4df9f8c-df95-46d8-bb0e-6f9f83fd4f55\",\n  \"bot_name\": \"Vocobase +918011223344\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vocobase.com/api/v2/voicelink/call-ready")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"connection_id\": \"9b7f1c44-c87f-4f0c-9124-3c802a9c1a20\",\n  \"did_id\": 812,\n  \"client_id\": 415,\n  \"agent_id\": \"f4df9f8c-df95-46d8-bb0e-6f9f83fd4f55\",\n  \"bot_name\": \"Vocobase +918011223344\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "phone_number": "+918011223344",
    "key": "918011223344",
    "ready": true,
    "steps": [
      {
        "step": "resolve_did",
        "status": "done",
        "detail": "Resolved DID +918011223344",
        "data": {
          "did_id": 812,
          "client_id": 415
        }
      },
      {
        "step": "ensure_routing",
        "status": "done",
        "detail": "Updated routing for DID +918011223344 to outbound bot_id=93",
        "data": {
          "routing_id": 120
        }
      }
    ],
    "readiness_before": {
      "key": "918011223344",
      "phone_number": "+918011223344",
      "state": "NO_BOT",
      "issues": [
        "NO_BOT",
        "ROUTING_MISSING"
      ],
      "remote_did": {
        "id": 812,
        "did_id": 812,
        "did_number": "918011223344",
        "phone_number": "+918011223344",
        "client_id": 415,
        "status": "active",
        "is_expired": false,
        "raw": {}
      },
      "local_phone_number": null,
      "routing": null,
      "bot": null,
      "actions": [
        "Create an active VoiceLink WebSocket bot for the mapped client",
        "Create VoiceLink call routing for this DID"
      ],
      "action_items": [
        {
          "code": "NO_BOT",
          "label": "Create an active VoiceLink WebSocket bot for the mapped client"
        },
        {
          "code": "ROUTING_MISSING",
          "label": "Create VoiceLink call routing for this DID"
        }
      ]
    },
    "readiness": {
      "key": "918011223344",
      "phone_number": "+918011223344",
      "state": "READY",
      "issues": [],
      "remote_did": {
        "id": 812,
        "did_id": 812,
        "did_number": "918011223344",
        "phone_number": "+918011223344",
        "client_id": 415,
        "status": "active",
        "is_expired": false,
        "raw": {}
      },
      "local_phone_number": {
        "id": "0be141f3-f72c-4630-b3bc-a0a5f59bf970",
        "phone_number": "+918011223344",
        "friendly_name": "918011223344",
        "status": "ACTIVE",
        "is_default": false,
        "inbound_enabled": true,
        "agent": {
          "id": "f4df9f8c-df95-46d8-bb0e-6f9f83fd4f55",
          "name": "Sales Agent"
        },
        "created_at": "2026-06-09T10:30:00.000Z",
        "updated_at": "2026-06-09T10:35:00.000Z"
      },
      "routing": {
        "id": 120,
        "phone_number": "+918011223344",
        "for_inbound_call": 1,
        "for_outbound_call": 3,
        "outbound_websocket_bot_id": 93,
        "raw": {}
      },
      "bot": {
        "id": 93,
        "name": "Vocobase +918011223344",
        "status": 1,
        "raw": {}
      },
      "actions": [],
      "action_items": []
    }
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "agent_name is required and must be max 50 characters"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}

Authorizations

Authorization

string

header

required

API key in format: rg_live_xxxx. Pass as a Bearer token in the Authorization header.

Body

application/json

Option 1
Option 2

Request for the safe outbound call-ready workflow. Provide either did_id or did_number. connection_id is optional unless multiple active VoiceLink connections exist.

did_id

integer

required

VoiceLink DID ID from /voicelink/dids/purchased.

connection_id

string<uuid>

Optional unless multiple active VoiceLink connections exist.

did_number

string

Purchased DID number. Used when did_id is not available.

client_id

integer

Optional VoiceLink client ID. Maps the DID to this client only when the DID is currently unmapped — a DID already mapped to a different client is never re-mapped, and clients are never auto-created. Composer-initiated mapping uses call_recording=0.

Required range: x >= 1

agent_id

string<uuid>

Optional Vocobase agent ID to assign to the imported local PhoneNumber row. Ownership is enforced by Vocobase.

bot_name

string

Optional name to use if a new VoiceLink WebSocket bot must be created.

websocket_url

string<uri>

Optional WebSocket URL override for bot creation. Omit to use the backend default.

Response

Call-ready workflow result.

success

boolean

required

data

object

required

Show child attributes

Make a VoiceLink DID inbound-readyRuns the secure, idempotent inbound setup workflow for one purchased VoiceLink DID. The deployment must enable the inbound runtime and configure a public WSS URL plus signing secret. Vocobase imports and enables the local number, optionally maps a currently-unmapped DID to an explicit client, creates or updates the client bot with a signed connection-scoped endpoint, points inbound routing to that bot, preserves every existing outbound routing field, and assigns the local number to the requested agent. The request cannot override the WebSocket URL.

Make a VoiceLink DID call-ready

curl --request POST \
  --url https://api.vocobase.com/api/v2/voicelink/call-ready \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
  "did_id": 812,
  "client_id": 415,
  "agent_id": "f4df9f8c-df95-46d8-bb0e-6f9f83fd4f55",
  "bot_name": "Vocobase +918011223344"
}
'

import requests

url = "https://api.vocobase.com/api/v2/voicelink/call-ready"

payload = {
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
    "did_id": 812,
    "client_id": 415,
    "agent_id": "f4df9f8c-df95-46d8-bb0e-6f9f83fd4f55",
    "bot_name": "Vocobase +918011223344"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    connection_id: '9b7f1c44-c87f-4f0c-9124-3c802a9c1a20',
    did_id: 812,
    client_id: 415,
    agent_id: 'f4df9f8c-df95-46d8-bb0e-6f9f83fd4f55',
    bot_name: 'Vocobase +918011223344'
  })
};

fetch('https://api.vocobase.com/api/v2/voicelink/call-ready', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vocobase.com/api/v2/voicelink/call-ready",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'connection_id' => '9b7f1c44-c87f-4f0c-9124-3c802a9c1a20',
    'did_id' => 812,
    'client_id' => 415,
    'agent_id' => 'f4df9f8c-df95-46d8-bb0e-6f9f83fd4f55',
    'bot_name' => 'Vocobase +918011223344'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vocobase.com/api/v2/voicelink/call-ready"

	payload := strings.NewReader("{\n  \"connection_id\": \"9b7f1c44-c87f-4f0c-9124-3c802a9c1a20\",\n  \"did_id\": 812,\n  \"client_id\": 415,\n  \"agent_id\": \"f4df9f8c-df95-46d8-bb0e-6f9f83fd4f55\",\n  \"bot_name\": \"Vocobase +918011223344\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vocobase.com/api/v2/voicelink/call-ready")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"connection_id\": \"9b7f1c44-c87f-4f0c-9124-3c802a9c1a20\",\n  \"did_id\": 812,\n  \"client_id\": 415,\n  \"agent_id\": \"f4df9f8c-df95-46d8-bb0e-6f9f83fd4f55\",\n  \"bot_name\": \"Vocobase +918011223344\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vocobase.com/api/v2/voicelink/call-ready")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"connection_id\": \"9b7f1c44-c87f-4f0c-9124-3c802a9c1a20\",\n  \"did_id\": 812,\n  \"client_id\": 415,\n  \"agent_id\": \"f4df9f8c-df95-46d8-bb0e-6f9f83fd4f55\",\n  \"bot_name\": \"Vocobase +918011223344\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "phone_number": "+918011223344",
    "key": "918011223344",
    "ready": true,
    "steps": [
      {
        "step": "resolve_did",
        "status": "done",
        "detail": "Resolved DID +918011223344",
        "data": {
          "did_id": 812,
          "client_id": 415
        }
      },
      {
        "step": "ensure_routing",
        "status": "done",
        "detail": "Updated routing for DID +918011223344 to outbound bot_id=93",
        "data": {
          "routing_id": 120
        }
      }
    ],
    "readiness_before": {
      "key": "918011223344",
      "phone_number": "+918011223344",
      "state": "NO_BOT",
      "issues": [
        "NO_BOT",
        "ROUTING_MISSING"
      ],
      "remote_did": {
        "id": 812,
        "did_id": 812,
        "did_number": "918011223344",
        "phone_number": "+918011223344",
        "client_id": 415,
        "status": "active",
        "is_expired": false,
        "raw": {}
      },
      "local_phone_number": null,
      "routing": null,
      "bot": null,
      "actions": [
        "Create an active VoiceLink WebSocket bot for the mapped client",
        "Create VoiceLink call routing for this DID"
      ],
      "action_items": [
        {
          "code": "NO_BOT",
          "label": "Create an active VoiceLink WebSocket bot for the mapped client"
        },
        {
          "code": "ROUTING_MISSING",
          "label": "Create VoiceLink call routing for this DID"
        }
      ]
    },
    "readiness": {
      "key": "918011223344",
      "phone_number": "+918011223344",
      "state": "READY",
      "issues": [],
      "remote_did": {
        "id": 812,
        "did_id": 812,
        "did_number": "918011223344",
        "phone_number": "+918011223344",
        "client_id": 415,
        "status": "active",
        "is_expired": false,
        "raw": {}
      },
      "local_phone_number": {
        "id": "0be141f3-f72c-4630-b3bc-a0a5f59bf970",
        "phone_number": "+918011223344",
        "friendly_name": "918011223344",
        "status": "ACTIVE",
        "is_default": false,
        "inbound_enabled": true,
        "agent": {
          "id": "f4df9f8c-df95-46d8-bb0e-6f9f83fd4f55",
          "name": "Sales Agent"
        },
        "created_at": "2026-06-09T10:30:00.000Z",
        "updated_at": "2026-06-09T10:35:00.000Z"
      },
      "routing": {
        "id": 120,
        "phone_number": "+918011223344",
        "for_inbound_call": 1,
        "for_outbound_call": 3,
        "outbound_websocket_bot_id": 93,
        "raw": {}
      },
      "bot": {
        "id": 93,
        "name": "Vocobase +918011223344",
        "status": 1,
        "raw": {}
      },
      "actions": [],
      "action_items": []
    }
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "agent_name is required and must be max 50 characters"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}

Getting Started

Guides

Partner Onboarding

API Reference

Webhooks

Telephony

Make a VoiceLink DID call-ready

Authorizations

Body

Response