Voice API Integration Guide: Audio, Phones, Campaigns and Recordings

Audio upload, file lookup, recorded speech and TTS

Separate prerecorded audio from text-to-speech before designing a voice workflow. Confirm encoding, sample rate, channels, duration, volume and usage rights before upload. Retain stable file identifiers rather than associating business records only by filename.

For file-based voice messages, verify that the audio is available and appropriate for the destination language. For TTS messages, test sanitised text, variable substitution, numbers and specialist terms by listening to actual playback. A successful submission does not establish acceptable pronunciation or content suitability.

For voice verification, define expiry, repeated requests and what happens after an unanswered call. Use distinct retry, contact-time and permission rules for different message purposes instead of increasing retries to compensate for an unresolved fault.

Checks

• Check format, pronunciation and rendered variables with small samples.
• Test unavailable files, rejected content and unsupported languages.
• Define access and retention rules for audio and source text.

Create and query phones, reset passwords and initiate calls

Before creating a phone, confirm the assigned account or agent group, credential delivery and permitted networks. Query responses should expose only necessary data. Password resets require explicit permission, auditing and secure delivery rather than general logs or group messages.

Associate the phone, agent and internal business record when initiating a call. Confirm identifiers for acceptance, ringing, connection and termination. After a password reset or deactivation, verify how existing registrations and active calls are treated.

Checks

• Distinguish creation, registration and actual calling capability.
• Test duplicate creation, unauthorised reset and expired credentials.
• Keep an audit trail without storing plaintext passwords.

Single and batch lookup for phone, campaign and code records

Single and batch phone-record queries support troubleshooting and reconciliation. Campaign and verification-call queries should also preserve request and returned identifiers, with explicit filters, pagination, timezone and retention rules.

A call record may change after its first query. Store the last reconciliation time and revisit incomplete records according to the agreed final-state rules. An absent record is not immediate proof that no attempt occurred, and acceptance is not proof of connection.

Checks

• Test pagination, date boundaries, delayed records and duplicates.
• Link business identifiers to the phone or voice-task reference.
• Define recovery and review for unknown states.

Create, modify, redial and control voice campaigns

Before creating a voice campaign, confirm number provenance, purpose, recipient permission, contact times and frequency caps. Validate the audio or TTS workflow with a small authorised sample before moving to a broader recipient set.

When querying campaign lists and details, verify state, recipient counts, result summaries and pagination. Modification, redial, start, pause and cancellation require agreed state constraints. In particular, establish whether attempts already in progress continue after a pause or cancellation.

Agent-group information can help establish conditions for a task involving human assistance. Check capacity, agent availability and transfer support separately; the existence of a group does not establish that transfer will succeed.

Checks

• Test create, list, detail, edit, redial, start, pause and cancel.
• Verify duplicate requests, state conflicts and partial failures.
• Provide an immediate pause and investigation route for abnormal calling.

Voice status push events and final reconciliation

Validate the source of voice status events and keep stable event identifiers. Durably record an event before returning the agreed acknowledgement. Process duplicate, reordered and delayed events consistently so repeated delivery does not inflate campaign counts.

Use documented status and termination definitions. Request acceptance, ringing, connection, completed playback and business success describe different stages. Recover missing events using the agreed query workflow when the receiver is unavailable.

Checks

• Test receiver timeouts, restarts, invalid signatures and repeats.
• Retain both source occurrence time and local receipt time.
• Reconcile summaries against final records rather than raw event counts.

Recording URLs, CC recording streams and bulk deletion

Before retrieving a recording URL or CC recording stream, confirm whether recording is enabled, the required notice or permission and the permitted audience. Expiring download URLs are not permanent public website links. Streams also require access control, rate limits and auditing.

Before deleting recordings in bulk, check business retention and dispute-handling requirements. Confirm the exact selection, backup treatment and irreversibility. Validate a small batch first, record item-level failures and investigate any copies that remain accessible.

Retain only necessary recordings and restrict download and redistribution. Prefer call identifiers and redacted descriptions for troubleshooting. Share an authorised extract only when it is actually needed.

Checks

• Test expiring links, revoked permission and post-deletion access.
• Maintain a retention policy and recording-access audit.
• Verify bulk deletion results and the treatment of copies.

Perform voice-specific acceptance tests

Listen to real test calls and record the conditions. Depending on the agreed workflow, cover two-way audio, volume, delay, spoken numbers, DTMF and termination causes. Different devices, regions and networks may behave differently.

Set budget and contact caps, alerts and a pause control before launch. Retest critical flows after changes to audio, TTS content, phone credentials or campaign policy, and keep a workable rollback procedure.

Checks

• Use authorised test numbers for end-to-end reconciliation.
• Assign incident ownership and recovery steps.
• Increase traffic based on observed production results.