> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Personalized phone and SMS notifications

> Reuse an agent for appointments, events, pickups and service follow-ups, with individual variables, signed callbacks and workflow reporting.

For lists above 1,000 recipients, use a [large SMS or call task](https://docs.brightalk.ai/en/guides/large-tasks.md) 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.

| Use case | Personalized content | Results to collect |
| - | - | - |
| Appointment confirmation | Service, appointment time, location and rescheduling instructions | Whether the customer will attend or needs a different time |
| Class and event reminder | Event name, start time and joining instructions | Attendance intent and requests for help |
| Order pickup | Order number, pickup location and deadline | Pickup intent and follow-up requests |
| Service follow-up | Completed service, questions and contact instructions | Whether human assistance is needed and next steps |

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:

```text theme={null}
Hello {{customer_name}}, this is {{organization_name}}.
{{notification_text}}
{{action_hint}}
{{confirmation_question}}
```

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:

```json theme={null}
{
  "agent_id": "11111111-1111-4111-8111-111111111111",
  "name": "Daily customer notifications",
  "reference_id": "notifications-20261201",
  "metadata": { "site_id": "north-branch", "workflow_id": "customer-notifications" },
  "variables": { "organization_name": "Northside Service" },
  "missing_variables": { "mode": "reject" },
  "recipients": [
    {
      "external_id": "customer-123",
      "reference_id": "appointment-456",
      "name": "Ming Wang",
      "phone_number": "TAIWAN_MOBILE_E164_1",
      "variables": {
        "customer_name": "Ming Wang",
        "notification_text": "Your in-store consultation starts on December 1 at 3 PM.",
        "action_hint": "Contact the appointment desk if you need to reschedule.",
        "confirmation_question": "Will you be able to attend as scheduled?"
      }
    },
    {
      "external_id": "customer-789",
      "reference_id": "pickup-A1001",
      "name": "Jamie Lin",
      "phone_number": "TAIWAN_MOBILE_E164_2",
      "variables": {
        "customer_name": "Jamie Lin",
        "notification_text": "Your order A1001 is ready for pickup until December 5.",
        "action_hint": "Bring your pickup notice to the service counter.",
        "confirmation_question": "Will you collect it before the deadline?"
      }
    }
  ],
  "schedule": {
    "start_at": "2026-12-01T09:00:00+08:00",
    "calling_window": {
      "time_zone": "Asia/Taipei",
      "weekdays": ["monday", "tuesday", "wednesday", "thursday", "friday"],
      "start_time": "09:00",
      "end_time": "18:00"
    }
  },
  "retry_policy": { "max_retries": 2, "delay_minutes": 15, "on": ["no_answer", "busy"] },
  "webhook": {
    "url": "https://your-platform.example/brightalk/results",
    "secret": "replace-with-at-least-32-random-characters"
  },
  "test_mode": true
}
```

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:

```text theme={null}
Brightalk-Event-Id: <事件 ID>
Brightalk-Timestamp: <Unix 秒數>
Brightalk-Signature: v1=<hex HMAC-SHA256>
```

Compute HMAC-SHA256 over the timestamp, a dot, and the raw HTTP body bytes. Do not parse and reserialize the JSON before verification:

```javascript theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyBrightalk(rawBody, headers, secret) {
  const timestamp = headers["brightalk-timestamp"];
  const signature = headers["brightalk-signature"];
  if (!/^\d+$/.test(timestamp ?? "")) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  if (!/^v1=[a-f0-9]{64}$/.test(signature ?? "")) return false;
  const expected = createHmac("sha256", secret)
    .update(timestamp + ".").update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(signature.slice(3), "hex"));
}
```

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

```text theme={null}
GET /usage?start_at=2026-12-01T00:00:00%2B08:00&end_at=2027-01-01T00:00:00%2B08:00&group_by=site_id,workflow_id
```

`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.

| Content | One part (1 credit) | Longer messages |
| - | - | - |
| Chinese, full-width symbols or line breaks | 70 characters | 66 characters per part, up to 6 parts (396 characters); 1 credit per part |
| GSM text | 160 billable units | 152 billable units per part, up to 6 parts (912 units); 1 credit per part |

* **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](https://docs.brightalk.ai/en/mcp.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.