Voice apps, PBX apps, clients and pricing

A voice app decides what happens on a call: fetch CoXML, send events to your call-control webhook, run a hosted AI agent, or run a flow. PBX apps are ready-made IVRs, ring groups and voicemail boxes. Client tokens let the browser and mobile voice SDKs make and take calls. Pricing shows what the project pays.

All paths are relative to https://api.contactivity.io/v1/projects/{project_id}. Authentication, errors, paging and idempotency work as described in the overview. AI agent versions, tests and analytics are in ai-agents.md; flow versions in flows.md.

PATCH requests change only the fields you send; the result is checked like a create. Request bodies refuse unknown fields (400 unknown_parameter).

Voice apps

The voice app object

Create or update a voice app

Every URL must be a public http(s) URL.

Errors: 400 invalid_parameter (param names the field, including agent and flow fields), 400 unknown_parameter, 400 invalid_json, 404 not_found. Deleting an app that a route or a PBX app uses returns 409 conflict.

curl https://api.contactivity.io/v1/projects/$PROJECT_ID/voice-apps \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"kind": "coxml", "name": "Main menu", "voice_url": "https://example.com/voice"}'

curl https://api.contactivity.io/v1/projects/$PROJECT_ID/voice-apps \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"kind": "ai_agent", "name": "Receptionist", "webhook_url": "https://example.com/agent-events",
       "agent": {"instructions": "You are the receptionist for Acme Dental.", "greeting": "Hi, how can I help?"}}'

PBX apps

The PBX app object

Create or update a PBX app

name (1-100 characters) and kind are required on create; kind cannot be changed. A config you send replaces the stored one whole. Unknown config fields are refused.

An action is {"type", "target"}. type is extension (an extension or SIP username of this project), trunk, number (E.164, not blocked), sip_uri, pbx_app, voice_app, voicemail (a voicemail PBX app) or hangup (empty target). Ring group members take only extension, trunk, number or sip_uri.

A greeting is {"say"?, "voice"?, "play_url"?}: text up to 1000 characters, a voice id (1-64 letters, digits, _, ., -) and/or a public https audio URL.

Errors: 400 invalid_parameter (param names the field, e.g. name, kind, strategy, options[0].digits, members[1].target), 400 unknown_parameter, 400 invalid_json, 404 not_found. Deleting an app that a route or another PBX app points at returns 409 conflict.

curl https://api.contactivity.io/v1/projects/$PROJECT_ID/pbx-apps \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "Main IVR", "kind": "ivr", "config": {
        "greeting": {"say": "Press 1 for sales, 2 for support."},
        "options": [{"digits": "1", "action": {"type": "extension", "target": "101"}},
                    {"digits": "2", "action": {"type": "number", "target": "+15551234567"}}]}}'

Voicemail messages

GET /pbx-apps/{app_id}/messages lists messages newest first: id (a recording id), from, to, duration_secs, created_at and download_url (signed, valid 10 minutes, or null). DELETE …/messages/{id} archives the message (the audio is kept; ?archived=true lists archived messages).

Clients (in-app calling)

Access tokens

Mint a token on your server and hand it to the browser or mobile SDK. It signs in as client:<identity>, so calls to client:<identity> ring it.

Response 201: {"token": "ctk1.…", "identity", "expires_at"}. Errors: 400 invalid_parameter (param identity, ttl, voice_app_id, push_credential_id).

DELETE /clients/{identity}/tokens ends every unexpired token of the identity and returns {"revoked": <count>}. Devices already registered stay until their registration is refreshed.

curl https://api.contactivity.io/v1/projects/$PROJECT_ID/clients/tokens \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"identity": "alice", "ttl": 600}'

Client settings

GET/PATCH /clients/settings: ring_time (10-180 seconds a call to a client rings) and voice_app_id (default app for calls clients place; "" clears it). Errors: 400 invalid_parameter (param ring_time, voice_app_id).

Push credentials

Your APNs key or Firebase service account, used to wake the mobile SDK for incoming calls. Secrets are stored encrypted and never returned.

The object returned is {"id": "pcr_…", "kind", "name", "team_id", "key_id", "bundle_id", "project_id", "sandbox", "created_at"}. Errors: 400 invalid_parameter (param name, kind, private_key, service_account, or no param for a bad APNs id), 404 not_found (delete). DELETE archives the credential: it is no longer used to wake devices.

Pricing

GET /pricing returns the project's price list: currency, billing_increment, regions (voice rates for +1 numbers by region and direction), international (prefix rates; the longest matching prefix applies), custom_rates (your organization's rates, which replace standard prices for matching prefixes), number_fees, number_rates and number_rates_source (standard or custom), blocked_prefixes, ai_rates_per_min and ai. Amounts are money objects ({"amount": "0.009000", "currency": "USD"}, 6 decimals); each rate has its own increment (e.g. 60/60: per 60 seconds, rounded up).

GET /pricing/check?to=+442071234567&direction=outbound&duration=120 prices one call:

The response has to, direction, duration, then either blocked: true (outbound to a blocked destination), or custom, custom_prefix, billing_increment, billed_seconds and available. When available is true it also has rate_per_min and cost as money objects. Errors: 400 invalid_parameter (param to, direction, duration).

curl "https://api.contactivity.io/v1/projects/$PROJECT_ID/pricing/check?to=%2B442071234567&duration=120" \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY"