Telephony

Managed numbers (Plivo)

Get phone numbers without your own SIP carrier. Buy managed numbers through Plivo (KYC/compliance handled in-platform), or connect your own Plivo account (BYO) to import numbers you already own.

Managed numbers are bought and billed through Bolcho and require an accepted compliance application. BYO connects your own Plivo credentials — you keep billing with Plivo and just import numbers.

GET/telephony/plivo/account agents:read

Get Plivo account

BYO Plivo connection status.

bash

curl https://api.bolchoai.in/v1/telephony/plivo/account \
  -H "Authorization: Bearer $BOLCHO_API_KEY"

Response

json

{ "connected": true, "authIdMasked": "MA••••1234", "accountName": "Acme", "cashCredits": 12.4 }

POST/telephony/plivo/account workspace:admin

Connect BYO Plivo

Connect your own Plivo account by auth id + token.

Body

authId*	string	Plivo Auth ID.
authToken*	string	Plivo Auth Token.

bash

curl -X POST https://api.bolchoai.in/v1/telephony/plivo/account \
  -H "Authorization: Bearer $BOLCHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "authId": "string",
  "authToken": "string"
}'

Response

json

{ "connected": true, "authId": "MA…", "accountName": "Acme", "cashCredits": 12.4 }

DELETE/telephony/plivo/account workspace:admin

Disconnect BYO Plivo

Disconnect your Plivo account.

bash

curl -X DELETE https://api.bolchoai.in/v1/telephony/plivo/account \
  -H "Authorization: Bearer $BOLCHO_API_KEY"

Response

json

{ "ok": true }

GET/telephony/plivo/account/numbers agents:read

List BYO numbers

Numbers owned in your connected Plivo account (with an imported flag).

bash

curl https://api.bolchoai.in/v1/telephony/plivo/account/numbers \
  -H "Authorization: Bearer $BOLCHO_API_KEY"

GET/telephony/plivo/search agents:read

Search numbers

Search buyable numbers (managed) or your BYO inventory.

Query parameters

mode	enum	managed \| byo (default managed).
country	string	ISO country (default IN).
type	string	Number type.
pattern	string	Digits/prefix to match.
region	string	Region filter.

bash

curl https://api.bolchoai.in/v1/telephony/plivo/search \
  -H "Authorization: Bearer $BOLCHO_API_KEY"

POST/telephony/plivo/buy workspace:admin

Buy a managed number

Purchase a managed number (requires accepted compliance + sufficient credits).

Body

number*	string	The number to buy.
agentId	uuid	Assistant to answer inbound.
label	string	Friendly label.

bash

curl -X POST https://api.bolchoai.in/v1/telephony/plivo/buy \
  -H "Authorization: Bearer $BOLCHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "string",
  "agentId": "00000000-0000-0000-0000-000000000000",
  "label": "string"
}'

Response

json

{ "id": "…", "number": "+91…", "provider": "plivo", "managed": true, "rentStatus": "active" }

POST/telephony/plivo/import workspace:admin

Import a BYO number

Import a number you already own in your connected Plivo account.

Body

number*	string	The number to import.
agentId	uuid	Assistant to answer inbound.
label	string	Friendly label.

bash

curl -X POST https://api.bolchoai.in/v1/telephony/plivo/import \
  -H "Authorization: Bearer $BOLCHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "string",
  "agentId": "00000000-0000-0000-0000-000000000000",
  "label": "string"
}'

Response

json

{ "id": "…", "number": "+91…", "provider": "plivo", "managed": false }

PATCH/telephony/plivo/numbers/{id} agents:write

Assign a number

Set the inbound/outbound assistants or label for a Plivo number.

Path parameters

id*

uuid

Number id.

Body

inboundAgentId	uuid \| null	Assistant that answers inbound.
outboundAgentId	uuid \| null	Assistant used for outbound.
label	string	Friendly label.

bash

curl -X PATCH https://api.bolchoai.in/v1/telephony/plivo/numbers/$ID \
  -H "Authorization: Bearer $BOLCHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "inboundAgentId": "00000000-0000-0000-0000-000000000000",
  "outboundAgentId": "00000000-0000-0000-0000-000000000000",
  "label": "string"
}'

Response

json

{ "ok": true }

DELETE/telephony/plivo/numbers/{id} workspace:admin

Release a number

Release a Plivo number (managed numbers are handed back to Plivo).

Path parameters

id*

uuid

Number id.

bash

curl -X DELETE https://api.bolchoai.in/v1/telephony/plivo/numbers/$ID \
  -H "Authorization: Bearer $BOLCHO_API_KEY"

Response

json

{ "ok": true }

GET/telephony/plivo/compliance agents:read

Get compliance status

Managed-mode KYC/compliance state and the documents still required.

bash

curl https://api.bolchoai.in/v1/telephony/plivo/compliance \
  -H "Authorization: Bearer $BOLCHO_API_KEY"

Response

json

{ "status": "under_review", "businessName": "Acme", "documents": [ { "slot": "Proof of Incorporation", "name": "incorp.pdf" } ], "requiredSlots": [] }

POST/telephony/plivo/compliance/refresh agents:read

Refresh compliance

Re-poll Plivo for the latest compliance/application status.

bash

curl -X POST https://api.bolchoai.in/v1/telephony/plivo/compliance/refresh \
  -H "Authorization: Bearer $BOLCHO_API_KEY"

Response

json

{ "status": "accepted" }

POST/telephony/plivo/compliance workspace:admin

Submit compliance docs

Submit KYC documents (multipart). Each file's field name is the requirement slot it satisfies (e.g. "Proof of Incorporation"), plus the text fields below.

Body

Send as multipart/form-data with the file in the file field.

Body

businessName*	string	Registered business name (form field).
documentTypes	string	JSON map { slot: documentTypeId }.
meta	string	JSON map of fields applied to all docs.

bash

curl -X POST https://api.bolchoai.in/v1/telephony/plivo/compliance \
  -H "Authorization: Bearer $BOLCHO_API_KEY" \
  -F "file=@/path/to/file" \
  -F "businessName=string" \
  -F "documentTypes=string" \
  -F "meta=string"

Response

json

{ "status": "submitted", "applicationId": "…" }

POST/telephony/plivo/dial calls:write

Place an outbound call

Dial a destination from a Plivo number and connect the assistant. Waits for pickup unless async:true.

Body

fromNumberId*	uuid	The Plivo number to call from.
to*	string	Destination number.
agentId	uuid	Assistant to run (defaults to the number's assistant).
variableValues	object	Per-call {{variable}} values for this callee — override the assistant's defaults in the prompt and first message.
customerName	string	Names the customer record for this number.
async	boolean	Return as soon as the call is created (status "queued") instead of waiting up to 45s for pickup. Poll GET /calls/{id} for the outcome.

bash

curl -X POST https://api.bolchoai.in/v1/telephony/plivo/dial \
  -H "Authorization: Bearer $BOLCHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fromNumberId": "00000000-0000-0000-0000-000000000000",
  "to": "string",
  "agentId": "00000000-0000-0000-0000-000000000000",
  "variableValues": {},
  "customerName": "string",
  "async": true
}'

Response

json

{ "ok": true, "status": "answered", "callId": "…", "to": "+91…" }

// with async: true
{ "ok": true, "status": "queued", "callId": "…", "to": "+91…" }