FAQ

The most frequent integration questions. If yours isn't here, reach out to Zorio support.

Auth & API Tokens

What if I lose my token?

A token is shown only once at creation; it can't be retrieved. Go to Admin Console → API Tokens → Revoke the old token → create a new one. Update your CRM with the fresh token.

Do tokens expire?

User-session tokens don't auto-expire by default — they only go away on manual revoke by an admin. The industry-standard advice is to rotate every 90 days. You can rotate yourself: create a new token → update the CRM → revoke the old one.

Can I use OAuth2 instead of Bearer tokens?

OAuth2 is not supported yet. Currently only Bearer (user session) is available.

Is there a sandbox to test before production integration?

Each customer is provisioned their own account. Use the provisioned account for testing — there's no shared sandbox.

PBX

Click-to-call isn't working?

Check in this order:

1. Does the token have pbx_api_access permission?
2. Does from_extension exist and have status=active in the account?
3. Is to_phone formatted as ^[0-9+]+$?
4. If you passed trunk_id — does the trunk have status=active?
5. If no trunk was passed — has the admin configured outbound routing?
6. Is the webhook receiver online (to receive ringing / answered / hangup events)?

How do I click-to-call with a per-customer caller ID?

Pass the caller_id field in the body. The number must belong to the account's active caller-IDs — fetch them with GET /api/pbx/caller-ids.

Recording URL expires in 30 minutes — what if a customer needs to download it later?

Call GET /api/pbx/cdr/{uuid} again to receive a new signed URL (TTL 30' from the request time). The old URL is expired; a new request mints a different URL.

When to use pbx.call.hangup vs pbx.cdr.created?

• pbx.call.hangup: fires in real time as the call ends, before recording_url is available.
• pbx.cdr.created: fires after the CDR pipeline finishes, with recording_url and a more detailed result classification.

CRMs that need real-time → subscribe to pbx.call.hangup. CRMs that need full data + recording → subscribe to pbx.cdr.created.

Can I filter a webhook to a specific extension?

Not yet. The webhook receives ALL PBX events for the account. Filter on the receiver side with data.extension.

Telesales

How many leads can a single campaign hold?

No hard cap. Recommendation: ≤ 100,000 leads per campaign to keep dashboard reports snappy.

Can leads be duplicated?

Not by default — the system dedupes by (campaign_id, phone). If you need duplicates (e.g. same campaign, different strategy), create two separate campaigns.

What disposition values are available?

There's a default catalog seeded for every new account ("Scheduled callback" / "No answer" / "Busy" / "Rejected" / ...). Customers can add new dispositions via the API or Admin Console.

Do I get a webhook when an agent scores a call?

Subscribe to telesales.call.disposed — it fires immediately after the agent sets the outcome.

AutoCall TTS

Tier A vs Tier B — which to pick?

• Tier A: higher voice quality, real-time (each call is rendered fresh), charged per character. Good for dynamic text (e.g. announcing a customer-specific amount).
• Tier B: uses a pre-rendered audio library, no per-character charge, high throughput. Good for fixed text or high volume.

Recommended default: B for > 1,000 calls/day.

Which voices support Vietnamese?

Tier B ships a pre-rendered vi-VN-female-01 for Vietnamese. Tier A has more voices through the premium TTS vendor — list them with GET /api/autocall/voices.

Where do I get DTMF input?

Subscribe to autocall.lead.dtmf_pressed — it fires every time the caller presses a key. The payload includes digit, lead_id, and script_id.

Webhook

My receiver sometimes doesn't get events?

Check in this order:

1. In Admin Console → Webhook deliveries — are any entries marked failed / deadletter?
2. Is the receiver verifying HMAC correctly (using the RAW body, not parsed JSON)?
3. Does the receiver return 200 within < 5s (check your server metrics)?
4. Is the URL's TLS cert valid (test with curl https://your-url/)?

The same event arrives multiple times — is this a bug?

No. Zorio retries when the receiver returns non-2xx or times out. The receiver MUST dedupe by X-Zorio-Delivery (UUID).

I switched the webhook URL mid-stream — where do queued events go?

Events still in the retry queue go to the new URL after the update. Events already in deadletter are not retried automatically — an admin needs to replay them manually.

Webphone SDK

Which browsers does the SDK support?

Chrome 88+, Edge 88+, Firefox 78+, Safari 14+. IE11 is NOT supported.

My iframe won't load — Mixed Content?

The page hosting the iframe MUST be HTTPS. The webphone iframe must also be HTTPS. If an HTTP page embeds an HTTPS iframe — the browser blocks it for security.

The webphone loses registration after a few minutes?

SDK v7+ has auto-reconnect + re-register supervisor. If you still lose registration:

• Check the events log for an auto_reconnect emission.
• Is there a network proxy blocking WebSocket (ws://)?
• Is your TLS wildcard cert still valid?

How do I customize the webphone UI?

The SDK ships with a default vanilla-DOM UI. To customize:

• Level 1: override CSS via :root variables.
• Level 2: use renderer: 'headless' — the SDK only emits events and you render your own UI.

Misc

Is there a portal-wide rate limit?

Yes. Default 60 req/min/token across endpoints, with click-to-call capped at 10 req/min. Exceed → HTTP 429 with a Retry-After header.

Is the API versioned?

Currently there's only v1 (the current URLs). When a breaking change ships, /api/v2/... will run alongside it. The roadmap announces breaking changes at least 6 months in advance.

Is there an OpenAPI spec / Postman collection to import?

The OpenAPI spec is in preparation — it will be published at /openapi/ in Phase 2.

I want to deploy a receiver in Vietnam — where are the Zorio servers?

Zorio servers are hosted in Vietnam (HCMC + Hanoi). Deploying a receiver in the same Vietnam region keeps webhook latency under 50ms.

Bug reports / integration support?

• Email: contact your admin for the official support channel.
• When reporting a bug — always include X-Request-Id (if available) or call_uuid + timestamp.