Create a telephony connection

POST

telephony

connections

curl --request POST \
  --url https://api.vocobase.com/api/v2/telephony/connections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Plivo India - Sales",
  "account_sid": "<string>",
  "auth_id": "<string>",
  "auth_token": "<string>",
  "api_key": "<string>",
  "subdomain": "<string>",
  "caller_id": "<string>",
  "from_number": "<string>",
  "sip_host": "<string>",
  "outbound_username": "<string>",
  "outbound_password": "<string>",
  "source_ips": [
    "<string>"
  ],
  "did_number": "<string>",
  "username": "<string>",
  "password": "<string>",
  "base_url": "<string>",
  "tata_email": "ops@example.com",
  "tata_password": "your-smartflo-password",
  "agent_number": "<string>",
  "jwt_token": "<string>",
  "exe_number": "9876543232"
}
'

import requests

url = "https://api.vocobase.com/api/v2/telephony/connections"

payload = {
    "name": "Plivo India - Sales",
    "account_sid": "<string>",
    "auth_id": "<string>",
    "auth_token": "<string>",
    "api_key": "<string>",
    "subdomain": "<string>",
    "caller_id": "<string>",
    "from_number": "<string>",
    "sip_host": "<string>",
    "outbound_username": "<string>",
    "outbound_password": "<string>",
    "source_ips": ["<string>"],
    "did_number": "<string>",
    "username": "<string>",
    "password": "<string>",
    "base_url": "<string>",
    "tata_email": "ops@example.com",
    "tata_password": "your-smartflo-password",
    "agent_number": "<string>",
    "jwt_token": "<string>",
    "exe_number": "9876543232"
}
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({
    name: 'Plivo India - Sales',
    account_sid: '<string>',
    auth_id: '<string>',
    auth_token: '<string>',
    api_key: '<string>',
    subdomain: '<string>',
    caller_id: '<string>',
    from_number: '<string>',
    sip_host: '<string>',
    outbound_username: '<string>',
    outbound_password: '<string>',
    source_ips: ['<string>'],
    did_number: '<string>',
    username: '<string>',
    password: '<string>',
    base_url: '<string>',
    tata_email: 'ops@example.com',
    tata_password: 'your-smartflo-password',
    agent_number: '<string>',
    jwt_token: '<string>',
    exe_number: '9876543232'
  })
};

fetch('https://api.vocobase.com/api/v2/telephony/connections', 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/telephony/connections",
  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([
    'name' => 'Plivo India - Sales',
    'account_sid' => '<string>',
    'auth_id' => '<string>',
    'auth_token' => '<string>',
    'api_key' => '<string>',
    'subdomain' => '<string>',
    'caller_id' => '<string>',
    'from_number' => '<string>',
    'sip_host' => '<string>',
    'outbound_username' => '<string>',
    'outbound_password' => '<string>',
    'source_ips' => [
        '<string>'
    ],
    'did_number' => '<string>',
    'username' => '<string>',
    'password' => '<string>',
    'base_url' => '<string>',
    'tata_email' => 'ops@example.com',
    'tata_password' => 'your-smartflo-password',
    'agent_number' => '<string>',
    'jwt_token' => '<string>',
    'exe_number' => '9876543232'
  ]),
  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/telephony/connections"

	payload := strings.NewReader("{\n  \"name\": \"Plivo India - Sales\",\n  \"account_sid\": \"<string>\",\n  \"auth_id\": \"<string>\",\n  \"auth_token\": \"<string>\",\n  \"api_key\": \"<string>\",\n  \"subdomain\": \"<string>\",\n  \"caller_id\": \"<string>\",\n  \"from_number\": \"<string>\",\n  \"sip_host\": \"<string>\",\n  \"outbound_username\": \"<string>\",\n  \"outbound_password\": \"<string>\",\n  \"source_ips\": [\n    \"<string>\"\n  ],\n  \"did_number\": \"<string>\",\n  \"username\": \"<string>\",\n  \"password\": \"<string>\",\n  \"base_url\": \"<string>\",\n  \"tata_email\": \"ops@example.com\",\n  \"tata_password\": \"your-smartflo-password\",\n  \"agent_number\": \"<string>\",\n  \"jwt_token\": \"<string>\",\n  \"exe_number\": \"9876543232\"\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/telephony/connections")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Plivo India - Sales\",\n  \"account_sid\": \"<string>\",\n  \"auth_id\": \"<string>\",\n  \"auth_token\": \"<string>\",\n  \"api_key\": \"<string>\",\n  \"subdomain\": \"<string>\",\n  \"caller_id\": \"<string>\",\n  \"from_number\": \"<string>\",\n  \"sip_host\": \"<string>\",\n  \"outbound_username\": \"<string>\",\n  \"outbound_password\": \"<string>\",\n  \"source_ips\": [\n    \"<string>\"\n  ],\n  \"did_number\": \"<string>\",\n  \"username\": \"<string>\",\n  \"password\": \"<string>\",\n  \"base_url\": \"<string>\",\n  \"tata_email\": \"ops@example.com\",\n  \"tata_password\": \"your-smartflo-password\",\n  \"agent_number\": \"<string>\",\n  \"jwt_token\": \"<string>\",\n  \"exe_number\": \"9876543232\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vocobase.com/api/v2/telephony/connections")

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  \"name\": \"Plivo India - Sales\",\n  \"account_sid\": \"<string>\",\n  \"auth_id\": \"<string>\",\n  \"auth_token\": \"<string>\",\n  \"api_key\": \"<string>\",\n  \"subdomain\": \"<string>\",\n  \"caller_id\": \"<string>\",\n  \"from_number\": \"<string>\",\n  \"sip_host\": \"<string>\",\n  \"outbound_username\": \"<string>\",\n  \"outbound_password\": \"<string>\",\n  \"source_ips\": [\n    \"<string>\"\n  ],\n  \"did_number\": \"<string>\",\n  \"username\": \"<string>\",\n  \"password\": \"<string>\",\n  \"base_url\": \"<string>\",\n  \"tata_email\": \"ops@example.com\",\n  \"tata_password\": \"your-smartflo-password\",\n  \"agent_number\": \"<string>\",\n  \"jwt_token\": \"<string>\",\n  \"exe_number\": \"9876543232\"\n}"

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

{
  "success": true,
  "data": {
    "connection": {
      "id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
      "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
      "provider": "plivo",
      "provider_key": "PLIVO",
      "name": "Plivo India - Sales",
      "status": "ACTIVE",
      "is_default": true,
      "phone_numbers": []
    }
  }
}

{
  "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": "FORBIDDEN",
    "message": "Access denied"
  }
}

{
  "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

provider

enum<string>

required

Telephony provider to connect.

Available options:

twilio,

exotel,

plivo,

vobiz,

tata_smartflo,

sip,

voicelink,

mcube

name

string

required

Human-readable connection name.

Required string length: 1 - 100

Example:

"Plivo India - Sales"

account_sid

string

Twilio/Exotel account SID, or Plivo/Vobiz auth ID.

auth_id

string

Alias for account_sid for Plivo/Vobiz.

auth_token

string

Provider auth token.

api_key

string

Exotel API key.

subdomain

string

Exotel account subdomain.

caller_id

string

Exotel caller ID.

from_number

string

Default outbound DID in E.164 format.

Pattern: ^\+[1-9]\d{6,14}$

sip_host

string

SIP carrier host for BYOP SIP connections.

outbound_username

string

Outbound SIP username.

outbound_password

string

Outbound SIP password.

source_ips

string[]

SIP carrier source IPs or CIDR ranges for inbound calls.

did_number

string

DID for SIP or VoiceLink connections.

Pattern: ^\+[1-9]\d{6,14}$

sip_transport

enum<string>

SIP transport protocol.

Available options:

UDP,

TCP,

TLS

username

string

VoiceLink username.

password

string

VoiceLink password.

base_url

string<uri>

Optional VoiceLink or Tata Smartflo API base URL.

tata_email

string<email>

Tata Smartflo panel email. Required when provider is tata_smartflo.

Example:

"ops@example.com"

tata_password

string

Tata Smartflo panel password. Stored encrypted; never returned. Required when provider is tata_smartflo.

Example:

"your-smartflo-password"

agent_number

string

Optional Tata Smartflo outbound agent leg number. Use only after Vocobase confirms the required Smartflo value for your account.

jwt_token

string

MCube JWT authentication token (required for MCube).

exe_number

string

MCube exenumber — the line outbound calls are placed from. National format allowed (no + required); stored as the connection's default phone number. Required for MCube.

Pattern: ^\+?\d{4,15}$

Example:

"9876543232"

Response

Connection created.

success

boolean

data

object

Show child attributes

Retrieve a telephony connectionReturns a single active partner-owned telephony connection by ID, including all of its active DIDs and the agent linked to each. Use this to keep an external system synced with the connection's numbers and agent assignments as shown in the Vocobase dashboard.

Create a telephony connection

curl --request POST \
  --url https://api.vocobase.com/api/v2/telephony/connections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Plivo India - Sales",
  "account_sid": "<string>",
  "auth_id": "<string>",
  "auth_token": "<string>",
  "api_key": "<string>",
  "subdomain": "<string>",
  "caller_id": "<string>",
  "from_number": "<string>",
  "sip_host": "<string>",
  "outbound_username": "<string>",
  "outbound_password": "<string>",
  "source_ips": [
    "<string>"
  ],
  "did_number": "<string>",
  "username": "<string>",
  "password": "<string>",
  "base_url": "<string>",
  "tata_email": "ops@example.com",
  "tata_password": "your-smartflo-password",
  "agent_number": "<string>",
  "jwt_token": "<string>",
  "exe_number": "9876543232"
}
'

import requests

url = "https://api.vocobase.com/api/v2/telephony/connections"

payload = {
    "name": "Plivo India - Sales",
    "account_sid": "<string>",
    "auth_id": "<string>",
    "auth_token": "<string>",
    "api_key": "<string>",
    "subdomain": "<string>",
    "caller_id": "<string>",
    "from_number": "<string>",
    "sip_host": "<string>",
    "outbound_username": "<string>",
    "outbound_password": "<string>",
    "source_ips": ["<string>"],
    "did_number": "<string>",
    "username": "<string>",
    "password": "<string>",
    "base_url": "<string>",
    "tata_email": "ops@example.com",
    "tata_password": "your-smartflo-password",
    "agent_number": "<string>",
    "jwt_token": "<string>",
    "exe_number": "9876543232"
}
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({
    name: 'Plivo India - Sales',
    account_sid: '<string>',
    auth_id: '<string>',
    auth_token: '<string>',
    api_key: '<string>',
    subdomain: '<string>',
    caller_id: '<string>',
    from_number: '<string>',
    sip_host: '<string>',
    outbound_username: '<string>',
    outbound_password: '<string>',
    source_ips: ['<string>'],
    did_number: '<string>',
    username: '<string>',
    password: '<string>',
    base_url: '<string>',
    tata_email: 'ops@example.com',
    tata_password: 'your-smartflo-password',
    agent_number: '<string>',
    jwt_token: '<string>',
    exe_number: '9876543232'
  })
};

fetch('https://api.vocobase.com/api/v2/telephony/connections', 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/telephony/connections",
  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([
    'name' => 'Plivo India - Sales',
    'account_sid' => '<string>',
    'auth_id' => '<string>',
    'auth_token' => '<string>',
    'api_key' => '<string>',
    'subdomain' => '<string>',
    'caller_id' => '<string>',
    'from_number' => '<string>',
    'sip_host' => '<string>',
    'outbound_username' => '<string>',
    'outbound_password' => '<string>',
    'source_ips' => [
        '<string>'
    ],
    'did_number' => '<string>',
    'username' => '<string>',
    'password' => '<string>',
    'base_url' => '<string>',
    'tata_email' => 'ops@example.com',
    'tata_password' => 'your-smartflo-password',
    'agent_number' => '<string>',
    'jwt_token' => '<string>',
    'exe_number' => '9876543232'
  ]),
  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/telephony/connections"

	payload := strings.NewReader("{\n  \"name\": \"Plivo India - Sales\",\n  \"account_sid\": \"<string>\",\n  \"auth_id\": \"<string>\",\n  \"auth_token\": \"<string>\",\n  \"api_key\": \"<string>\",\n  \"subdomain\": \"<string>\",\n  \"caller_id\": \"<string>\",\n  \"from_number\": \"<string>\",\n  \"sip_host\": \"<string>\",\n  \"outbound_username\": \"<string>\",\n  \"outbound_password\": \"<string>\",\n  \"source_ips\": [\n    \"<string>\"\n  ],\n  \"did_number\": \"<string>\",\n  \"username\": \"<string>\",\n  \"password\": \"<string>\",\n  \"base_url\": \"<string>\",\n  \"tata_email\": \"ops@example.com\",\n  \"tata_password\": \"your-smartflo-password\",\n  \"agent_number\": \"<string>\",\n  \"jwt_token\": \"<string>\",\n  \"exe_number\": \"9876543232\"\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/telephony/connections")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Plivo India - Sales\",\n  \"account_sid\": \"<string>\",\n  \"auth_id\": \"<string>\",\n  \"auth_token\": \"<string>\",\n  \"api_key\": \"<string>\",\n  \"subdomain\": \"<string>\",\n  \"caller_id\": \"<string>\",\n  \"from_number\": \"<string>\",\n  \"sip_host\": \"<string>\",\n  \"outbound_username\": \"<string>\",\n  \"outbound_password\": \"<string>\",\n  \"source_ips\": [\n    \"<string>\"\n  ],\n  \"did_number\": \"<string>\",\n  \"username\": \"<string>\",\n  \"password\": \"<string>\",\n  \"base_url\": \"<string>\",\n  \"tata_email\": \"ops@example.com\",\n  \"tata_password\": \"your-smartflo-password\",\n  \"agent_number\": \"<string>\",\n  \"jwt_token\": \"<string>\",\n  \"exe_number\": \"9876543232\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vocobase.com/api/v2/telephony/connections")

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  \"name\": \"Plivo India - Sales\",\n  \"account_sid\": \"<string>\",\n  \"auth_id\": \"<string>\",\n  \"auth_token\": \"<string>\",\n  \"api_key\": \"<string>\",\n  \"subdomain\": \"<string>\",\n  \"caller_id\": \"<string>\",\n  \"from_number\": \"<string>\",\n  \"sip_host\": \"<string>\",\n  \"outbound_username\": \"<string>\",\n  \"outbound_password\": \"<string>\",\n  \"source_ips\": [\n    \"<string>\"\n  ],\n  \"did_number\": \"<string>\",\n  \"username\": \"<string>\",\n  \"password\": \"<string>\",\n  \"base_url\": \"<string>\",\n  \"tata_email\": \"ops@example.com\",\n  \"tata_password\": \"your-smartflo-password\",\n  \"agent_number\": \"<string>\",\n  \"jwt_token\": \"<string>\",\n  \"exe_number\": \"9876543232\"\n}"

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

{
  "success": true,
  "data": {
    "connection": {
      "id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
      "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
      "provider": "plivo",
      "provider_key": "PLIVO",
      "name": "Plivo India - Sales",
      "status": "ACTIVE",
      "is_default": true,
      "phone_numbers": []
    }
  }
}

{
  "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": "FORBIDDEN",
    "message": "Access denied"
  }
}

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

Getting Started

Guides

Partner Onboarding

API Reference

Webhooks

Telephony

Create a telephony connection

Authorizations

Body

Response