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, 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. Flow versions are in Flows.

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 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"}'

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, download_url (signed, valid 10 minutes, or null) and transcription (id, status, text; null when the box does not transcribe). DELETE …/messages/{id} archives the message (the audio is kept; ?archived=true lists archived messages).

With transcribe on, each message is transcribed like a recording with transcription: true and charged per audio minute at the transcription rate, on top of the recording. The email_to email then waits for the transcript and includes it; after 2 minutes it goes out without it ("Transcript unavailable"). One email per message. Projects in restricted data mode get the short "sign in to listen" email, never the transcript.

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, products, then the sip_trunking prices at the top level: 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, and recording (recording per minute, recording_storage per minute-month, recording_storage_free_days, live_transcription per minute, increment, and custom when your organization has its own price; see Recording and storage). 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).

products has one entry per product. sip_trunking and programmable_voice each have regions, international and custom_rates; programmable_voice_sip, byoc_sip_trunking and byoc_programmable_voice have one rate_per_min for every destination and direction, with increment and custom (true when your organization has its own rate).

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

The response has to, direction, duration, product, 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 when product, to, direction or duration is not valid.

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