Надсилання

Надсилання масових SMS за допомогою POST /v1/batches

POST/v1/batches

Надіслати до 10 000 номерів в одному запиті. Вся вартість списується з балансу одразу.

Тіло запиту

  • toarray of stringsнеобов'язково

    Номери для одного спільного тексту. Використовуйте або to з text, або messages.

  • textstringнеобов'язково

    Спільний текст, обов’язковий з to.

  • messagesarray of objectsнеобов'язково

    Один {to, text} для кожного отримувача для персональних текстів.

  • namestringнеобов'язково

    Мітка для консолі, до 100 символів.

  • referencestringнеобов'язково

    Ваш власний ідентифікатор, до 100 символів, повертається для пакету та кожного повідомлення.

  • send_atstringнеобов'язково

    Час у форматі ISO 8601, від 2 хвилин до 45 днів вперед.

curl https://bulksmsapi.cc/v1/batches \
  -H "Authorization: Bearer $BULKSMSAPI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: spring-sale-0412" \
  -d '{
    "name": "Spring sale",
    "text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
    "to": [
      "+14155550123",
      "+447400123456",
      "+4915123456789"
    ]
  }'
202 AcceptedJSON
{
  "id": "bat_6TQ2W8M1ZK4N",
  "object": "batch",
  "name": "Spring sale",
  "status": "queued",
  "source": "api",
  "encoding": "GSM-7",
  "recipients": 3,
  "max_segments": 1,
  "cost": "0.02741",
  "refunded": "0.00000",
  "currency": "USD",
  "counts": { "scheduled": 0, "queued": 3, "sent": 0, "delivered": 0, "failed": 0, "canceled": 0 },
  "send_at": null,
  "reference": null,
  "created_at": "2026-11-07T09:31:40.102Z",
  "completed_at": null,
  "set_aside": []
}

Номери, які виключені

Кожен номер очищується та оцінюється окремо. Номери, які не можна надіслати, виключаються з пакету, не списуються та перелічуються в set_aside з причиною:

reasonЗначення
invalid_numberНе читається як + та від 7 до 15 цифр після очищення.
duplicateЦей номер вже з’являвся раніше в запиті.
unsupported_countryНомер не належить до країни з визначеною ціною.
too_longПерсональний текст потребує більше 10 сегментів.
empty_textПерсональний текст порожній.
suppressedНомер знаходиться у вашому списку ненадсилання.

Якщо не залишилося жодного номера, запит завершується з кодом першої причини (наприклад, invalid_number), і нічого не списується.

Персональний текст для кожного номера

Використовуйте messages, щоб надати кожному отримувачу його власний текст: імена, час, суми. Кожен текст підраховується та оцінюється окремо, тому пакет може містити односегментні та двосегментні повідомлення.

curl https://bulksmsapi.cc/v1/batches \
  -H "Authorization: Bearer $BULKSMSAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment reminders, 14 May",
    "send_at": "2026-05-13T16:00:00Z",
    "messages": [
      { "to": "+14155550123", "text": "Hi Ana, your dental check-up is tomorrow at 09:30." },
      { "to": "+14155550178", "text": "Hi Sam, your dental check-up is tomorrow at 11:00." }
    ]
  }'

Планування

З send_at пакет та його повідомлення чекають у статусі scheduled та переходять у чергу в зазначену хвилину. Вартість списується під час прийняття запиту, тому запланований пакет завжди має свої кошти. Запланований пакет можна скасувати до його початку.

POST/v1/batches/{id}/cancel

Скасовує запланований пакет: кожне повідомлення стає скасованим, а повна вартість повертається на баланс як один рядок повернення. Пакет, який розпочався, відповідає кодом 409 not_cancelable.

curl -X POST https://bulksmsapi.cc/v1/batches/bat_6TQ2W8M1ZK4N/cancel \
  -H "Authorization: Bearer $BULKSMSAPI_KEY"

Отримання та перелік пакетів

GET/v1/batches/{id}

Пакет із поточними лічильниками за статусами. Отримуйте оновлення через запити або використовуйте вебхуки.

GET/v1/batches

Пакети облікового запису, від найновіших до найстаріших, з обмеженням (від 1 до 100) та starting_after (bat_ id).

Поля пакету

  • idstring

    bat_ та 12 символів після нього.

  • statusstring

    заплановано, в черзі, відправляється, завершено або скасовано.

  • sourcestring

    api або консоль.

  • encodingstring

    GSM-7 або UCS-2, якщо текст потребує Unicode.

  • recipientsinteger

    Номери, прийняті до пакету.

  • max_segmentsinteger

    Найбільша кількість сегментів серед текстів.

  • coststring

    Загальна сума, списана з балансу, USD.

  • refundedstring

    Загальна сума, повернена до балансу за невдалі або скасовані повідомлення.

  • countsobject

    Повідомлення за статусами: заплановано, в черзі, відправлено, доставлено, невдало, скасовано.

  • send_atstring or null

    Запланований час, якщо є.

  • completed_atstring or null

    Коли останнє повідомлення досягло фінального статусу.

Більші списки

Розділіть списки понад 10,000 номерів на кілька запитів, кожен зі своїм Idempotency-Key (наприклад, ідентифікатор списку та номер частини). Повідомлення передаються мережі по порядку зі швидкістю до 1,200 на хвилину на обліковий запис, тому кампанія з 50,000 номерів буде відправлена менш ніж за годину. Консоль приймає до 50,000 номерів на кампанію з вставки або CSV-файлу.

Надсилання масових SMS за допомогою POST /v1/batches | BulkSMSAPI Docs