Business Calling API — Umney Connect Developers

Overview

Business Calling is Umney-hosted SIP capacity (Twilio or Telnyx) plus bring-your-own trunk. Create a Business Calling API token with voice:read so backends can read call and capacity resources on the public Voice API when those handlers ship—same least-privilege model as a Cloudflare API token.

Item	Value
Service	Business Calling
Status	Public Voice read API generally available · dashboard SIP/calls live
Permissions	voice:read
Live token shape	umk_live_voice_<prefix>_<secret>
Test token shape	umk_test_voice_<prefix>_<secret>
Dashboard	Dashboard → SIP · Phone · Calls
OpenAPI	/developers/openapi-business-calling.json
Docs (AI)	/developers/business-calling.md

Public tokens call GET /api/v1/voice/calls|usage today. Dial/outbound write APIs are not public—do not invent them. Softphone uses dashboard JWT WebSocket, not umk_* tokens.

Get started

Enable Business Calling in Dashboard → Billing.
Open Dashboard → SIP: opt into Umney-hosted SIP, or register your own trunk (host, username, password, port, transport).
Use Dashboard → Phone for the softphone and Dashboard → Calls for history.
Dashboard → Developers → create an API token. Product: Business Calling. Permission: voice:read. Environment: live or test.
Store the secret server-side only—never in the softphone or browser bundle.

API tokens

An API token lets an agent read Business Calling resources only—not Live Chat session minting, email, or billing.

Authorization: Bearer umk_live_voice_<prefix>_<secret>
# or
X-API-Key: umk_live_voice_<prefix>_<secret>

API base: https://umneyconnect.com/api

Permission	Allows
voice:read	Read calls, numbers, and usage on the public Voice API (when live)

Full token guide: /developers/api-tokens

Concepts

Resource	Description
Umney-hosted SIP	Platform Twilio/Telnyx trunk provisioned for the workspace (opt-in)
Own trunk	BYO SIP registration (host/username/password/port/udp\|tcp\|tls)
Call (CDR)	Call history row: direction, duration, result, MOS, timestamps
Call summary	Minutes today (UTC) and inbound answer rate (7d)
Softphone WS	Dashboard JWT WebSocket at /api/sip/ws for the phone client
Carrier webhooks	Twilio/Telnyx voice ingress to Umney — not tenant umk_* webhooks

Dashboard SIP & calls API (available now)

Uses the signed-in workspace session (JWT). Prefer customer-facing Dashboard labels when guiding operators.

Method	Path	Purpose
POST	/api/sip/register	Register/update BYO SIP trunk
GET	/api/sip/status	BYO trunk status (null if none)
DELETE	/api/sip	Remove BYO trunk
GET	/api/sip/our-sip	Umney-hosted SIP settings + platform readiness
POST	/api/sip/our-sip/opt-in	Opt into Umney-hosted SIP (clears BYO if present)
POST	/api/sip/our-sip/opt-out	Disable Umney-hosted SIP
GET	/api/calls	List CDR (cursor, limit, direction, result)
GET	/api/calls/summary	Dashboard minutes + inbound answer rate
GET	/api/calls/export	Export JSON/CSV (throttled)

POST /api/sip/register

{
  "host": "sip.example.com",
  "username": "trunk-user",
  "password": "optional-on-update",
  "port": 5060,
  "transport": "udp"
}

GET /api/calls (query)

?limit=50&cursor=<callId>&direction=inbound|outbound&result=<result>
# Response: { items: [{ id, fromId, toId, direction, durationSecs, result,
#   startedAt, endedAt, callSid, mosScore }], nextCursor }

Umney-hosted and BYO trunks are mutually exclusive on opt-in/register: enabling one removes the other. Opt-in responses may include one-time SIP credentials—store securely; later GETs mask secrets.

Softphone WebSocket

Upgrade to WebSocket at /api/sip/ws?token=<dashboard JWT>. Used by Dashboard → Phone. Do not put Business Calling API tokens in the softphone client.

Public Voice API (token — live)

Requires a Business Calling umk_* token with voice:read. Lists the same CDR data as JWT GET /api/calls.

Method	Path	Permission	Status	Dashboard equivalent
GET	/v1/voice/calls	voice:read	Live	GET /api/calls
GET	/v1/voice/calls/{id}	voice:read	Live	Single CDR
GET	/v1/voice/usage	voice:read	Live	GET /api/calls/summary
GET	/v1/voice/numbers	voice:read	Planned	Provisioned DIDs

GET /v1/voice/calls

curl "https://umneyconnect.com/api/v1/voice/calls?limit=50&direction=inbound" \
  -H "Authorization: Bearer $VOICE_API_KEY"
# { "data": [ { id, fromId, toId, direction, durationSecs, result, … } ],
#   "meta": { "limit": 50, "nextCursor": null } }

Do not invent dial, hangup, or outbound write URLs. voice:read is read-only.

Carrier webhooks

Twilio and Telnyx voice webhooks hit Umney platform routes configured at opt-in. Tenants do not point those carriers at umk_* tokens. Tenant outbound call.completed webhooks are not shipped yet—do not document them as live.

Errors and limits

403 — Business Calling not entitled, wrong product token, or missing voice:read
Opt-in vs entitlement mismatch — SIP may show enabled while billing access is false (check Billing)
GET /api/calls/export — throttled (about 5/min)
Public /api/v1/* rate limit: 600/min per key when Voice handlers exist

Agent recipe

# 1. Enable Business Calling in Billing
# 2. Dashboard → SIP → Umney-hosted opt-in OR BYO register
# 3. Developers → create token → product "Business Calling" → voice:read
CONNECT_API_BASE=https://umneyconnect.com/api
VOICE_API_KEY=umk_live_voice_…

# 4. Today: JWT GET /api/calls · /api/sip/our-sip · /api/sip/status
# 5. Public: GET /v1/voice/calls · /v1/voice/usage — do not invent dial APIs
# 6. Never put the token in the softphone
# 7. Prefer customer-facing names — do not expose internal billing catalog IDs