AutoCall TTS API — Overview

Public REST API for the AutoCall TTS module — automated outbound calling with natural-sounding TTS voices + DTMF actions + voices library.

Authentication: Bearer Token (user session). Base URL: https://app.zorio.vn/api/autocall/ (provisioned per customer).

Scope

The AutoCall API covers these groups:

• Campaign management (Campaigns).
• Scripts + DTMF actions (playback / playback_then_hangup / switch_script / queue / repeat_script / hangup).
• Leads + Variables ( placeholders inside the template).
• Voices + Media files (Tier A premium realtime, Tier B local pre-rendered).
• Reports — KPIs / Trend / Comparison / Hangup / Heatmap / DTMF / Funnel / Export.
• Webhook events.

Tier A / Tier B

• Tier A: premium realtime — TTS via a premium provider, billed per character. You bring your own API key.
• Tier B: local unlimited — uses the pre-rendered vi-VN-female-01 audio library, no per-character cost. Recommended default for high-volume use.

Glossary

Term	Meaning
Campaign	Outbound TTS campaign bound to 1 script + lead list + caller-ID configuration + dial pacing
Script	TTS script containing a template_text with variables + a DTMF action tree
DTMF	Keypad digits the called party presses after hearing the TTS (0-9, *, #) — Zorio captures them for branching
DTMF action	Behavior when the called party presses a key — playback / playback_then_hangup / switch_script / queue / repeat_script / hangup
Lead	A phone number to call + the variable payload used in the TTS render
Variable	A variable defined by the customer that represents dynamic data in the script (e.g. customer_name, appointment_date, callback_date)
Voice	A specific voice (e.g. vi-VN-female-01 for Tier B, Roger for Tier A premium TTS provider)
Media file	An audio file uploaded for direct playback (no TTS) — used for fixed intros, music on hold, IVR fallback
Tier A	Realtime TTS via a premium provider — high quality, billed per character
Tier B	Pre-rendered audio library — no fee, high throughput, fixed voice
Attempt	A single dial of one lead — may be retried on busy / no_answer
Hangup cause	Standard Q.850 reason code for call termination — see Hangup codes

End-to-end workflow

1. Login                  POST /api/auth/login        → Bearer token
2. Create script          POST /api/autocall/scripts  → ID + template_text + dtmf_actions
3. Create campaign        POST /api/autocall/campaigns → bind script_id + caller_id_group_id
4. Import leads           POST /api/autocall/campaigns/{id}/leads
5. Launch                 POST /api/autocall/campaigns/{id}/start
6. Realtime monitoring    Webhook autocall.lead.* delivered to your URL
7. View reports           GET  /api/autocall/campaigns/{id}/reports/...
8. Pause / Resume / Stop  POST /api/autocall/campaigns/{id}/pause | resume | stop

Authentication

Use a Bearer Token (user session) — see Authentication for details.

Authorization: Bearer <token>
Accept: application/json

Required permission: autocall_api_access (granted to the admin role by default). Some sensitive endpoints (e.g. start campaign) additionally require autocall_manage_campaign.

Endpoint groups

Group	Documentation
Campaigns	Open page
Scripts + DTMF actions	Open page
Leads + Variables	Open page
Voices + Media files	Open page
Reports	Open page
AutoCall webhook events	Open page

General conventions

Pagination

Every list endpoint uses ?page=1&per_page=50 (max 200). Standard paginated response — see General conventions.

Response shape

{ "data": {} }                              // single resource
{ "current_page": 1, "data": [], ... }      // list paginated
{ "message": "...", "errors": {} }          // 422 validation

Timezone

ISO 8601 with offset (2026-06-30T07:30:45+00:00). The backend returns timestamps with microseconds (.000000Z) — requests accept either format.

Phone numbers

• Stored in the DB in E.164 without the leading + (e.g. 84987654321).
• Request bodies accept 0xxx or 84xxx — the backend normalizes them automatically.
• Responses return the original format the client sent (preserved).

Rate limit

Endpoint group	Limit
/api/autocall/*	120 req/min/token
/api/autocall/campaigns/{id}/leads (bulk import)	30 req/min/token
/api/autocall/campaigns/{id}/start	5 req/min/token

See Rate limit + Idempotency for details.

HTTP Status Codes

HTTP	When
200	OK
201	Created (new campaign / script / lead)
202	Accepted (campaign start enqueued, audio render in progress)
401	Missing / invalid / expired token
403	Missing autocall_api_access or autocall_manage_campaign permission
404	Resource does not exist within the account
409	State machine violation (e.g. start a campaign that is already running)
422	Validation error — see errors[] for field details
429	Rate limit hit
500	Server error

Base URL

	URL
Production	https://app.zorio.vn/api/autocall/ (provisioned per customer)

FAQ

Q1: Which Vietnamese voice is best?

A: Tier B ships vi-VN-female-01 pre-rendered — high quality, no fee, high throughput. Tier A offers more voices via the provider — list them via GET /api/autocall/voices.

Q2: What is the maximum number of leads per campaign?

A: No hard limit. We recommend ≤ 100,000 leads per campaign so the engine processes them smoothly.

Q3: Where do I receive the DTMF data when the called party presses a key?

A: Subscribe to the autocall.lead.dtmf_pressed webhook — it fires every keypress. The payload includes digit + lead_id + script_id.

Q4: Audio render is failing — how do I troubleshoot?

A: Check in this order:

1. Is voice_id still status=active in /api/autocall/voices?
2. Does the Tier A provider have a valid key and remaining quota?
3. For Tier B: is the voice_id pre-rendered in the audio library?
4. Does the template contain any variable that has not been defined in Variables?

Q5: Can I transfer to a live agent when the called party presses a DTMF key?

A: Yes — set action_type=queue in the DTMF action and provide target_queue_name. The call is transferred into the queue and an available agent picks it up.