Placing Calls: Single and Batch

This page covers the complete sending practice — from a single trial call to batch tasks — plus the semantics of batch processing and failure retry.

Prerequisites

• A template that has passed review (see Using the Voice Console)
• During testing, add numbers to the test whitelist (see Using the Voice Console)

Choose a Send Channel

Both channels go through the same call pipeline and share the same result semantics.

Numbers and Countries

• Recipient numbers use E.164 format (country calling code + local number, without + in the request), e.g. 8613800138000; see the code table at Country/Region Codes
• The call country is determined by the template: no country code is needed in the send request; the recipient number's calling code must match the template country, otherwise 120003 is returned
• A single API request accepts at most 1000 recipients; Console tasks support larger batch imports

Templates and Variables

• Template variables use ordinal placeholders such as {1} and {2}, with values passed per number: {"to": "8613800138000", "variables": ["John", "A12345"]}
• The variable order must match the placeholders; omit variables for templates without variables
• The playback count can be overridden per send on top of the template default

Scheduled Sending

• Set scheduling.type = SCHEDULED and provide startTime/endTime (ISO 8601 with timezone, e.g. 2026-11-20T09:00:00+08:00)
• Window constraints: the start must be later than the current time, the end later than the start, and the window spans at most 8 days; the platform completes the outbound calls within the window
• Time fields are allowed only on scheduled tasks

Redial Policy

Calls that do not connect can be redialed automatically (the retry object):

Redialing improves the chance of connecting, but every actual call is billed; for time-sensitive scenarios, disable redial or keep it minimal.

Hang-up SMS

After a call ends, a follow-up SMS can be sent to the recipient (the hangupSms object; its presence enables the feature):

• templateId: the hang-up SMS template (independent of voice templates; create and review it first)
• sendType: ON_CONNECTED send after the call is answered (default) / ALL all calls / ON_UNANSWERED not connected / BY_DURATION by answered duration
• durationLimitSeconds: the duration threshold in seconds when using BY_DURATION

Batch Processing Semantics

• Before acceptance: the platform validates the whole batch (number formats, count limits, cross-field rules) — a validation failure rejects the entire batch (HTTP 400 or 010003)
• After acceptance: calls are placed one by one; a single failure does not affect the other numbers in the batch
• On acceptance the API returns callId (the task identifier) and acceptedCount (the number of accepted recipients)

Invalid and Duplicate Numbers

• Numbers with illegal formats are rejected before acceptance; make sure the E.164 format and calling code are correct
• Duplicate numbers within a batch each receive their own call; deduplicate before sending

Idempotency and Retry

• bulkId is for reconciliation linkage only (echoed back as-is in the response) and is not an idempotency key: duplicate submissions trigger new calls and new charges
• After an API timeout, do not blindly resend: first query with the returned callId (or look up the bulkId in records) to check whether the task was accepted, and retry only if it was not
• Recommended client-side idempotency: generate a unique bulkId per business event, and deduplicate by callId + mobile once results arrive (CDR push or the query API)

FAQ

Accepted (000000) but the recipient did not get the call?

The call may be waiting for a redial after a failed attempt, the recipient's phone may be off or busy, or the route may be faulty. See send records for per-call status and Error Codes for release code meanings.

When does a validation failure return HTTP 400, and when does it return 010003?

Single-field format/value problems (e.g. a number that is not E.164, more than 1 messages entry) return the standard HTTP 400 error body; cross-field/business rule problems (e.g. an invalid scheduled window or incomplete hang-up SMS fields) return HTTP 200 + code=010003.

Related Resources

• Send API full parameters
• Viewing Results: Send Records and CDR Push
• FAQ