← Back to Conversation API SKILL.md

Batch API Reference

The Batch API sends a single message definition to up to 1000 recipients in one API call, with per-recipient ${parameter} substitution. Also supports bulk contact creation/deletion and consent records.

Sections: SDK Reference | When to Use | Base URLs | API Endpoints | Request Structure | Top-Level Fields | Per-Recipient Fields | Managing Batches | Bulk Contacts | Callbacks | Common Pitfalls | Links

SDK Reference

• Node.js
• Python
• Java
• .NET

When to Use

• Sending the same (or parameterized) message to many recipients at once
• Bulk-creating or deleting contacts
• Bulk-inserting consent records
• Scheduling a message blast for future delivery

For single-recipient messaging, use the standard messages:send endpoint instead.

Base URLs (Separate from Conversation API)

Must match the region of your Conversation API app.

API Endpoints

All endpoints prefixed with /v1/projects/{project_id}.

CORRECT Request Structure

ONE message at top level + recipient_and_params array:

{
  "app_id": "YOUR_APP_ID",
  "message": {
    "text_message": {
      "text": "Hello ${user}! Your code is ${code}"
    }
  },
  "recipient_and_params": [
    {
      "recipient": {
        "identified_by": {
          "channel_identities": [
            { "channel": "SMS", "identity": "+1234567890" }
          ]
        }
      },
      "parameters": { "user": "Jane", "code": "123" }
    },
    {
      "recipient": {
        "identified_by": {
          "channel_identities": [
            { "channel": "SMS", "identity": "+0987654321" }
          ]
        }
      },
      "parameters": { "user": "John", "code": "456" }
    }
  ]
}

WRONG — do NOT use a messages array. The Batch API uses ONE message + many recipients.

Top-Level Request Fields

Per-Recipient Fields

Managing Batches

• Cancel: DELETE /v1/projects/{project_id}/messages with batch_id in body
• Get status: GET /v1/projects/{project_id}/messages/{batch_id}
• Statuses: READY, SCHEDULED, PROCESSED, CANCELLED

See Batch Messages API.

Bulk Contacts

POST /v1/projects/{project_id}/contacts with contacts array (up to 1000). Created asynchronously. See Batch Contacts API.

Callbacks

• BATCH_STATUS_UPDATE webhook trigger for batch-level status changes
• MESSAGE_DELIVERY for per-message delivery receipts (includes _batch_id in metadata)
• Failed receipts include batch_id and message_index

Common Pitfalls

1. Wrong structure: ONE message + recipient_and_params array. NOT a messages array.
2. Wrong base URL: Uses conversationbatch.api.sinch.com, NOT conversation.api.sinch.com.
3. _batch_id is reserved: Auto-injected into delivery receipts. Don't use in your own metadata.
4. Parameter syntax: Use ${parameter_name} in string fields. Keys must match parameters object.
5. Asynchronous: 200 means accepted, NOT delivered. Listen to webhooks for actual status.
6. send_after rounding: Scheduled >1 min out rounds UP to next 5-min mark. Max 7 days.
7. Cancellation is async: Always returns 200. Can only cancel before send_after. Immediate batches cannot be cancelled.
8. Rate limits still apply: 800 req/s per project. Large batches are queued and processed at configured rate.

Links

• Batch API Overview
• Batch Messages
• Batch Contacts
• Batch Consents