Sinch Api Batch Send

---
name: sinch-api-batch-send
description: Send a batch of messages to up to 1000 recipients via Sinch Batch API
---

# Send Batch Messages

Send a single message definition to up to 1000 recipients in one API call using the Sinch Conversation Batch API. Supports per-recipient parameter substitution (e.g. ${name}).

**IMPORTANT: Execute this command directly. Do NOT generate script files. Perform the API call immediately.**

## Input

- `--message` / `-m`: Message text; use ${param} for per-recipient substitution - required
- `--recipients` / `-r`: Comma-separated E.164 numbers, or path to file with one number per line - required
- `--channel` / `-c`: Channel (SMS, RCS, etc.) - optional, default SMS
- `--params` / `-p`: Optional JSON object or file mapping recipient index to parameters for substitution

Arguments: $ARGUMENTS

## Instructions

**Execute these steps directly - do not write code or scripts:**

0. If $ARGUMENTS empty: ask for message text (with ${variable} placeholders if needed), recipient list (comma-separated or file), and channel. Otherwise parse.

1. Validate: --message (non-empty, may contain ${var}), --recipients (1-1000 identities). Parse recipients into array. Build recipient_and_params: each recipient has recipient.identified_by.channel_identities and optional parameters object for ${} substitution.

2. Get CONVERSATION_* env vars (project, region, app, key id/secret). Batch API base: https://{region}.conversationbatch.api.sinch.com. If missing, report "Sinch API is not configured."

3. Request body: app_id, message (e.g. text_message with text), recipient_and_params array. Do NOT use a "messages" array - Batch API expects one message + recipient_and_params.

4. POST https://{region}.conversationbatch.api.sinch.com/v1/projects/{projectId}/messages with OAuth2 Bearer token and JSON body.

5. On success: display "✅ Batch submitted" with batch_id and recipient count. Handle errors (400, 401, 429) with clear messages.

6. Handle all errors gracefully.

## Examples

```
/sinch-api-batch-send --message="Hello ${name}, your code is ${code}" --recipients=+15551234567,+15559876543 --params='{"0":{"name":"Alice","code":"111"},"1":{"name":"Bob","code":"222"}}'
/sinch-api-batch-send -m "Hi!" -r +15551111111,+15552222222 --channel=SMS
```

## API Reference

- **Base URL**: https://{region}.conversationbatch.api.sinch.com (us, eu, br)
- **Endpoint**: POST /v1/projects/{project_id}/messages
- **Documentation**: https://developers.sinch.com/docs/conversation/batch/

## Notes

- Max 1000 recipients per request. One message object; recipient_and_params array.
- Use ${parameter} in message text; supply parameters per recipient in recipient_and_params[].parameters.