# Vobiz Applications Endpoints

> Configure Vobiz Voice Applications (webhook URLs for answer/hangup callbacks) and SIP Endpoints (soft-phones, IP phones, browser clients).

- **Type:** Skill
- **Install:** `agentstack add skill-vobiz-ai-agent-skills-vobiz-applications-endpoints`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vobiz-ai](https://agentstack.voostack.com/s/vobiz-ai)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vobiz-ai](https://github.com/vobiz-ai)
- **Source:** https://github.com/vobiz-ai/Agent-Skills/tree/main/skills/vobiz-applications-endpoints

## Install

```sh
agentstack add skill-vobiz-ai-agent-skills-vobiz-applications-endpoints
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Vobiz Applications & Endpoints skill

Two related but distinct concepts:

- **Application**: a named container that holds the `answer_url`/`hangup_url` webhooks. Phone numbers and endpoints get **attached** to an application so calls fire the configured webhooks.
- **Endpoint**: a SIP user account (`username` + `password` + `alias`) for soft-phones, browser WebRTC clients, or IP desk-phones to register with Vobiz.

Base URL: `https://api.vobiz.ai`. Auth headers on every request: `X-Auth-ID` + `X-Auth-Token`.

## Application vs Endpoint - which do I need?

- Inbound call to a **phone number (DID)** → create an **Application**, then **attach the number** to it.
- A **person or device** that needs to place/receive calls (browser, softphone, desk phone, AI agent) → create an **Endpoint**, then attach an Application to the endpoint for its call-handling logic.
- Both: number routes inbound to an Application; that Application's VobizXML can `Dial` the endpoint's `sip_uri` to ring the device.

## Application endpoints

| Op | Path | Notes |
|---|---|---|
| Create | `POST /api/v1/Account/{auth_id}/Application/` | Body: `{app_name, answer_url, answer_method, hangup_url?, hangup_method?, ...}`. Returns `app_id`. |
| List | `GET /api/v1/Account/{auth_id}/Application/` | Paginated: `limit` (default 20, max 100), `offset` (default 0). |
| Get | `GET /api/v1/Account/{auth_id}/Application/{app_id}/` | |
| Update | `POST /api/v1/Account/{auth_id}/Application/{app_id}/` | (yes, POST not PUT.) Partial update; omitted fields unchanged. |
| Delete | `DELETE /api/v1/Account/{auth_id}/Application/{app_id}/` | `204` on success; `409` if numbers are still attached. |

### Attach / detach a number (different path - under numbers, not Application)

| Op | Path |
|---|---|
| Attach | `POST /api/v1/Account/{auth_id}/numbers/{number}/application` body `{application_id}` |
| Detach | `DELETE /api/v1/Account/{auth_id}/numbers/{number}/application` |

`{number}` is the E.164 number **URL-encoded** (`+` → `%2B`, e.g. `%2B14155551234`).

## Endpoint endpoints

| Op | Path | Notes |
|---|---|---|
| Create | `POST /api/v1/Account/{auth_id}/Endpoint/` | Body: `{username, password, alias, application}` - `application` is the numeric `app_id`. Returns `endpoint_id` + `sip_uri`. |
| List | `GET /api/v1/Account/{auth_id}/Endpoint/` | Filters: `username__contains/__exact/__startswith`, `alias__contains/__exact`, `application_id__exact`, `application_id__isnull`, `sub_account`, plus `limit`/`offset`. |
| Get | `GET /api/v1/Account/{auth_id}/Endpoint/{endpoint_id}/` | Adds `sip_registration` block when `sip_registered == "true"`. |
| Update | `POST /api/v1/Account/{auth_id}/Endpoint/{endpoint_id}/` | (yes, POST not PUT.) `202` on success, empty body. |
| Delete | `DELETE /api/v1/Account/{auth_id}/Endpoint/{endpoint_id}/` | `204` on success. Disconnects registered devices immediately. |

## Default-app semantics

- `default_number_app: true` → any newly created number that has **no** `app_id` is auto-routed to this application.
- `default_endpoint_app: true` → any newly created endpoint with **no** `application` is auto-routed to this application.
- `default_app` is a separate read-mostly flag for the account-level default application.
- Setting a new default does not retroactively re-route numbers/endpoints created earlier - it only affects ones created afterward without an explicit app.

## Public SIP URI

- Each application exposes a `sip_uri` (e.g. `sip:@sip.vobiz.ai`). `public_uri: false` by default.
- Set `public_uri: true` only when an external SIP system must reach the application's `sip_uri` directly (e.g. routing from a third-party PBX/carrier into your app). Leave it `false` for ordinary DID-driven inbound flows.

## Pitfalls

- **Path casing**: capital `Account` + capital `Application`/`Endpoint`. Lowercase segments 404. (Attach/detach is the exception: it uses lowercase `numbers`.)
- **Update is POST, not PUT/PATCH** - Vobiz convention for both Application and Endpoint.
- **SIP username**: documented constraint is alphanumeric only; treat `-`/`_`/spaces as risky (may 400). It is unique per account - a duplicate username returns a validation error (`409`/`400`). Username is **immutable** after creation; to rename, delete and recreate.
- **Locked endpoint fields**: `username`, `endpoint_id`, `domain`, `allow_same_domain`, `allow_other_domains`, `allow_phones`, `allow_apps` cannot be changed via update. To change them, recreate the endpoint.
- **Password is write-only** - never returned in any response. After a password change, every SIP client must re-register with the new credential or it drops.
- **`sip_registered` is a string** (`"true"`/`"false"`), not a boolean - compare against the string.
- **Deleting an app in use**: returns `409` if phone numbers are still attached. Detach all numbers first, then delete.
- **Attaching an already-linked number**: attaching overwrites the previous application binding (re-points routing); it does not error. Detach is idempotent-ish - detaching an unlinked number is a no-op/clears nothing.
- **Fallback**: `fallback_answer_url` fires only when `answer_url` is unreachable, times out, or returns invalid VobizXML. It must itself return valid XML. With no fallback set, the call drops on `answer_url` failure.
- **`hangup_url` defaults to `answer_url`** when omitted at create time - your answer handler may receive hangup callbacks unless you set a distinct `hangup_url`.
- **An endpoint binds to exactly one application** - swap it via update (`application` field).
- **WebRTC auth is SIP credentials, not JWT** - browser clients register with the endpoint `username`/`password`. There is no JWT-token API in v1.

## Recipes

### Create app → attach number → route inbound

1. `POST .../Application/` with `app_name`, `answer_url`, `answer_method` → capture `app_id`.
2. `POST .../numbers/%2B/application` with `{ "application_id": "" }`.
3. Inbound calls to that number now fetch `answer_url` for VobizXML.
4. Verify with `GET .../Application/{app_id}/` and inspect the number's binding.

### Create endpoint → attach app → ring a device from a call

1. `POST .../Endpoint/` with `username`, `password`, `alias`, `application: ` → capture `endpoint_id` + `sip_uri`.
2. Register a softphone/browser/desk phone with the username/password against `sip.vobiz.ai`.
3. In the inbound Application's VobizXML, `Dial` the endpoint's `sip_uri` to ring the device.
4. Confirm registration via `GET .../Endpoint/{endpoint_id}/` → `sip_registered: "true"`.

### Rotate an endpoint password safely

1. `POST .../Endpoint/{endpoint_id}/` with new `password`.
2. Push the new credential to every SIP client and force re-registration (old credential stops working).

## When to search docs

- "How do I configure a Pipecat / LiveKit / Vapi / ElevenLabs handler?" → `integrations/*`
- "Browser calling with WebRTC" → `integrations/webrtc-application-setup`
- "Inbound call routing / DID binding" → `applications/attach-number`
- "VobizXML elements (Dial, Gather, etc.)" → voice XML reference docs

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vobiz-ai](https://github.com/vobiz-ai)
- **Source:** [vobiz-ai/Agent-Skills](https://github.com/vobiz-ai/Agent-Skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-vobiz-ai-agent-skills-vobiz-applications-endpoints
- Seller: https://agentstack.voostack.com/s/vobiz-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.