Skip to main content
For lists above 1,000 recipients, use a large SMS or call task for up to 100,000 recipients. Standard /batches and /sms-batches requests accept up to 1,000 recipients each; the examples below use those standard endpoints.

Use cases and shared workflow

Appointment confirmations, class or event reminders, order pickups and service follow-ups can use the same API workflow. Your system supplies each recipient’s message and question; Brightalk executes the call or SMS and returns the result.
  1. Configure an agent with variables and the result fields to collect.
  2. Your system creates a single call or batch from a business event, with individual data and a schedule.
  3. Brightalk executes the request and sends a signed webhook with call or SMS results.
  4. Your system uses references to update its records, then decides whether to tag, assign a human follow-up or send another message.

One agent across notification types

Create an outbound agent whose prompt and text opening use variables:
Pass a string map in variables on POST /calls, or on each recipient of POST /batches. Batch-level variables are defaults; recipient values override them. Execution data is preserved in GET /calls/{call_id} and does not overwrite CRM fields. Pass complete, formatted content in notification_text, such as “Your in-store consultation starts on December 1 at 3 PM.” Variable names are your template’s choice; variable values are not recursively expanded. Configure data collection fields such as response_intent (yes/no/undecided in response to this call’s confirmation_question, unknown left empty), follow_up_requested (boolean, whether human assistance was requested) and do_not_call (boolean). They appear under their configured identifiers in structured_results. Interpret the answer in its business context; other fields can collect a preferred appointment time or satisfaction rating. A collected opt-out value does not itself update calling suppression policy.

Create and start a batch

This POST /batches example uses one agent for an appointment confirmation and an order pickup. Replace TAIWAN_MOBILE_E164_1 and TAIWAN_MOBILE_E164_2 with the respective authorized Taiwan mobile destinations in E.164 format. It uses test_mode: true, which creates no dialing command, records no usage and deducts no credits:
Single calls need calls:write; batches need batches:write/batches:read. Use calls:read for call results and transcripts:read for transcripts. Usage needs usage:read; SMS needs sms:send/sms:read; callback inspection and redelivery need webhooks:read/webhooks:write. Existing keys do not automatically receive new scopes. Work-creating operations require Idempotency-Key; reuse a key only when retrying the same operation and payload, and use a new key for a new notification or follow-up. For real execution, remove test mode and call POST /batches/{batch_id}/start with {} and a separate idempotency key. A real batch is initially a draft; creating it alone does not place calls. Test batches finish immediately and cannot be started. Their test calls can be inspected with GET /calls?batch_id=..., including rendered_prompt and rendered_first_sentence. Testing does not pretend a person answered or fabricate a transcript.

Variables and references

Variables allow 64 keys, 2,000 characters per value and 16 KiB total UTF-8. Names use ASCII letters, digits and underscores, starting with a letter or underscore; reserved keys are rejected. Metadata allows 32 string keys and 8 KiB. Per-recipient values override batch defaults. Use missing_variables: { "mode": "reject" } to reject missing placeholders before any recipient is created. For defaults, use missing_variables: { "mode": "default", "defaults": { "action_hint": "Contact the service desk if you need help." } }. An uncovered placeholder still rejects the entire request. Keep agent variable names stable after accepting a batch; the agent configuration is still read at dial time. Existing built-in date/time and CRM placeholders retain their behavior. recipient.external_id remains a reusable CRM identity across calls and notifications. Use non-unique reference_id for a business record such as an appointment, order or support ticket, and metadata for site/workflow reporting. Notification data belongs in variables; putting it in recipient.company or other CRM fields still writes CRM data.

Scheduling and retries

A batch can contain one recipient. Single calls accept the same integration options and schedule. A start time is the earliest eligible time; capacity, windows and the organization’s calling policy still apply. Windows use the specified timezone and weekdays and cannot cross midnight. Batch retry_policy accepts max_retries (0–5), delay_minutes (1–1,440), and on (no_answer, busy). Only an attempt with no connection evidence qualifies. Each retry uses a new call ID with retry_of_call_id and retry_root_call_id; it retains variables, references, metadata and the calling window. Pause/cancel prevents remaining retries. Recipient counters describe the initial attempt; follow all attempt callbacks for the recipient’s final outcome. retry_pending_calls and retry_attempts expose retry progress.

Verify signed callbacks

Provide a final public HTTPS callback URL and a secret of at least 32 printable characters. Secrets are encrypted and omitted from reads. Event types are call.completed, batch.completed, sms.completed, and sms_batch.completed, with stable id, type, created_at, test_mode, and data fields. Phone callbacks wait for result processing when appropriate; unconnected/cancelled calls can report immediately. Transcript API URLs still need transcripts:read authentication. Headers:
Compute HMAC-SHA256 over the timestamp, a dot, and the raw HTTP body bytes. Do not parse and reserialize the JSON before verification:
Reject timestamps more than five minutes old. Deduplicate by event ID, persist work, and return 2xx. Delivery is at least once; ordering across calls is not guaranteed. Ten failed attempts exhaust an event. Inspect GET /webhook-events/{event_id} or requeue an exhausted event with POST /webhook-events/{event_id}/retry and {}. This never repeats a call or SMS. Redirects and private/metadata addresses are blocked; only HTTPS on port 443 is accepted.

Report usage by site and workflow

usage:read is required. Periods use execution creation time, include the start and exclude the end, and span at most 93 days. Up to three metadata keys may group results; metadata accepts a JSON string map filter. Missing dimensions are null. Only public API executions are included; test executions are excluded. In-progress usage can arrive later. Voice usage is read from authoritative billing records: positive billable seconds divided by 60, with no per-call upward increment. Unanswered zero-duration attempts generate no voice minutes; billable voicemail is included. The report uses the same eligibility rules as settlement: test, playground, failed, cancelled, canceled and skipped statuses are excluded even when a usage row’s billable flag is true. Eligible rows follow the account and exact billing-period bounds, including historical rows with a different or missing subscription ID. voice_credit_accounting is settled_period_proportional_minutes; one voice credit has the unit minutes. For each reconciled, settled subscription period, voice_credits_deducted allocates the actual ledger consumption using group billable minutes / all account billable minutes in that subscription period. The denominator includes other sites and non-API calls, even when this request filters metadata or execution dates. Purchases and administrative adjustments are excluded. voice_credit_periods provides the period, denominator, settled debit and allocation status for reconciliation. voice_unallocated_billable_minutes reports minutes without a reconciled settlement yet. Their future debit is unknown: period credits_deducted and organization_billable_minutes are null, and the status is pending_settlement, or unreconciled when a settled snapshot disagrees with its ledger debit. A settled period with no credit consumption has an actual zero deduction. Group allocations use 12 decimal places of precision; combining groups can leave a small precision difference. Late usage or corrections recalculate reporting shares. This allocation supports your own site billing while Brightalk continues to settle the shared account; metadata does not create separate balances or tenant isolation.

SMS API

After verifying call.completed, your system can use reference_id to find the original record and call POST /sms for an unanswered recipient. Give this follow-up its own Idempotency-Key, reuse that key when retrying the same follow-up, then use sms.completed to update delivery status. When call retries are enabled, choose the follow-up timing according to your business rules and track it using the original call or business notification ID. Each call attempt has its own event ID; deduplicate the follow-up action as well as individual callback events. GET /sms/account (sms:read) inspects credits, the SMS module, sender name and multipart capability. Carrier approval cannot be inferred from a balance: registration_status is contact_support, and an unknown sender number is null. POST /sms accepts Taiwan mobile E.164 phone_number, message, references, metadata, optional schedule, webhook and test mode. POST /sms-batches accepts the same common fields and 1–1,000 recipients, each with optional variables, metadata and references. Both require sms:send and Idempotency-Key. Read delivery state with GET /sms/{sms_id} and GET /sms-batches/{batch_id} (sms:read). scheduled/queued are not delivery; sent means carrier acceptance, and delivered requires a delivery receipt. Unknown acceptance or delivery never implies an automatic resend. Once accepted, the same idempotency key and payload replay the stored 202 response before message preparation or short-link provisioning. Sender or provider changes cannot invalidate that acceptance. Use the GET endpoints for current status; a replay preserves the original acceptance snapshot. A different payload with the same key returns 409.

SMS length and credits

Each segment costs 1 credit. Count the final outgoing text after adding the carrier title and organization [sender] prefix, resolving variables and replacing the final short URL. The response’s message is the frozen text; segments is its part count.
  • 71 characters cost 2 credits: with UCS-2 encoding, Chinese and Latin letters, digits, punctuation, spaces and line breaks each count as one. 71–132 characters cost 2 credits; 133–198 cost 3.
  • Special characters affect the count: GSM ^, {, }, [, ], ~, | and \ each consume 2 billable units (septets), and escape pairs stay together at segment boundaries. Line breaks, underscores _ or backticks (U+0060) switch to UCS-2: 70 characters for one part or 66 per multipart segment. The 912-unit maximum does not guarantee room for 912 characters containing GSM extensions.
  • Sending paths have different limits: campaigns, Automations, and public API POST /sms and POST /sms-batches support multipart SMS. Manual one-to-one sends and MCP brightalk_send_sms are single-part only and reject more than 70 UTF-16 code units or 159 ASCII bytes. This legacy path counts ASCII bytes rather than the table’s GSM units.
  • Emoji are unsupported: remove emoji before sending; non-BMP characters are rejected.
MCP brightalk_create_sms and brightalk_create_sms_batch follow the public API’s multipart rules. brightalk_preview_sms previews only the single-part contact-send path. Check account capabilities with GET /sms/account first. credits_reserved is the unsettled reservation; credits_deducted is the net ledger deduction, including releases/refunds. Neither a reservation nor a deduction proves delivery. Set expires_at to the latest time a scheduled request may enter the carrier campaign queue. It must follow schedule.start_at; by default it is one hour after the later of request creation and schedule.start_at. Choose an explicit deadline when the calling window opens later. Temporary queue refusals expose an error_code and retry with backoff; ten queue attempts or expiry ends the request as failed, including outside the calling window, and makes its result callback eligible. Expiry reports schedule_expired. After queuing, the existing carrier dispatch and delivery-validity rules apply.

Other integration questions

GET /telephony exposes configured caller IDs, shared trunk limits and inbound reserves without SIP credentials. It does not guarantee dedicated capacity or expose every provider limit. For 300 recipients averaging 60 seconds each and four usable lines, a lower-bound estimate is 75 minutes before windows, contention and retries. Caller IDs, languages and voices remain configured in the dashboard; this API does not accept arbitrary caller IDs or guarantee a particular Taiwanese voice. Contact Brightalk about additional capacity. Automation runs continue to accept only input fields declared by their automation definition; GET /automations lists input_fields. The existing remote MCP endpoint is https://api.brightalk.ai/mcp; see MCP for authentication and client setup. This guide describes the REST integration; MCP tools have their own input schemas. Carrier registration, content approval, displayed sender numbers and recording/privacy notices must be confirmed against the applicable onboarding agreement. Module enablement and credit balances do not substitute for carrier approval. Batch SMS responses include a compact messages list with each message ID, reference and status; use these IDs to retrieve individual delivery details.