# Business Calling — Umney Connect API

> For AI agents: use for SIP, softphone, CDR, and Business Calling token questions.
> Access model matches Cloudflare API tokens: create a least-privilege **Business Calling** token (`voice:read`).
> Prefer customer-facing names (Business Calling). Do not invent or expose internal billing catalog IDs.
> Do not invent public dial/outbound write APIs — `voice:read` is read-focused.

## Quick facts

| Item | Value |
|---|---|
| Service | Business Calling |
| Status | Public Voice read API **live** · dashboard SIP/calls live |
| HTML docs | https://umneyconnect.com/developers/business-calling |
| OpenAPI | https://umneyconnect.com/developers/openapi-business-calling.json |
| Token guide | https://umneyconnect.com/developers/api-tokens |
| AI index | https://umneyconnect.com/llms.txt |
| Dashboard | Dashboard → SIP · Phone · Calls |
| Permissions | `voice:read` |
| Live token | `umk_live_voice_<prefix>_<secret>` |
| Test token | `umk_test_voice_<prefix>_<secret>` |
| Production API | https://umneyconnect.com/api |

## Create access

1. Enable **Business Calling** in Dashboard → Billing.
2. Dashboard → SIP: opt into Umney-hosted SIP **or** register your own trunk.
3. Dashboard → Developers → create token → product **Business Calling** → `voice:read`.
4. Store the secret server-side only — never in the softphone.

```
CONNECT_API_BASE=https://umneyconnect.com/api
VOICE_API_KEY=umk_live_voice_…
```

## Concepts

- **Umney-hosted SIP** — platform Twilio/Telnyx trunk via opt-in.
- **Own trunk** — BYO register (`host`, `username`, `password`, `port`, `udp|tcp|tls`).
- **Call (CDR)** — history row with direction, duration, result, MOS.
- **Call summary** — minutes today (UTC) + inbound answer rate (7d).
- **Softphone WS** — `/api/sip/ws?token=<dashboard JWT>`.

Umney-hosted and BYO are mutually exclusive on opt-in/register.

## Dashboard SIP & calls API (JWT — live)

| Method | Path | Purpose |
|---|---|---|
| POST | `/api/sip/register` | Register/update BYO trunk |
| GET | `/api/sip/status` | BYO status (`null` if none) |
| DELETE | `/api/sip` | Remove BYO trunk |
| GET | `/api/sip/our-sip` | Umney-hosted settings + platform readiness |
| POST | `/api/sip/our-sip/opt-in` | Opt into Umney-hosted SIP |
| POST | `/api/sip/our-sip/opt-out` | Opt out |
| GET | `/api/calls` | List CDR |
| GET | `/api/calls/summary` | Minutes + answer rate |
| GET | `/api/calls/export` | Export JSON/CSV (throttled ~5/min) |

### POST /api/sip/register

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

### GET /api/calls

Query: `limit`, `cursor`, `direction=inbound|outbound`, `result`.

```json
{
  "items": [
    {
      "id": "…",
      "fromId": "…",
      "toId": "…",
      "direction": "inbound",
      "durationSecs": 42,
      "result": "completed",
      "startedAt": "…",
      "endedAt": "…",
      "callSid": "…",
      "mosScore": 4.2
    }
  ],
  "nextCursor": null
}
```

## Softphone WebSocket

`GET` upgrade `/api/sip/ws?token=<dashboard JWT>` — Dashboard → Phone only. Do not use API tokens here.

## Public Voice API (token — live)

| Method | Path | Permission | Status |
|---|---|---|---|
| GET | `/v1/voice/calls` | voice:read | **Live** |
| GET | `/v1/voice/calls/{id}` | voice:read | **Live** |
| GET | `/v1/voice/usage` | voice:read | **Live** |
| GET | `/v1/voice/numbers` | voice:read | Planned |

```bash
curl "https://umneyconnect.com/api/v1/voice/calls?limit=50&direction=inbound" \
  -H "Authorization: Bearer $VOICE_API_KEY"
```

Do not invent dial URLs. `voice:read` is read-only.

## Carrier webhooks

Twilio/Telnyx voice webhooks hit Umney platform routes at opt-in. Not tenant `umk_*` webhooks. Tenant outbound `call.completed` webhooks are not shipped.

## Errors

- **403** — Business Calling not entitled, wrong token, or missing `voice:read`
- Opt-in vs billing mismatch — verify Billing entitlement
- Export throttled ~5/min
- Public keys: 600/min on `/api/v1/*` when Voice handlers exist

## Related

- AI Agent (phone AI): `/developers/ai-agent.md`
- Live Chat: `/developers/live-chat.md`
- Token guide: `/developers/api-tokens.md`

## Agent checklist

1. Load `/llms.txt`
2. Open this file
3. Explain: enable **Business Calling** → SIP opt-in or BYO → create Business Calling token → store secret
4. Today: JWT `/api/sip/*` and `/api/calls*`
5. Public: `/v1/voice/calls` · `/v1/voice/usage` — no inventing dial APIs
6. Do not expose internal billing catalog IDs