1. Створіть індивідуальну/масову SMS-кампанію

Цей метод дозволяє створити:

Індивідуальні смс-кампанії на один телефонний номер.
Масові SMS-кампанії для списку телефонних номерів. Кожна кампанія містить один текст для всіх номерів одержувачів. Для однієї кампанії можна вказати до 10 000 контактів.

Обмеження:

Створення кампанії через API недоступне в режимі DEMO-облікового запису.
У режимі ТЕСТОВОЇ платформи створення кампанії можливе лише для номерів, доданих до Контактної книги.

URL запиту

POST http://one-api.bsg.world/api/campaigns/sms/send

Параметри запиту

Параметр	Необхідність	Тип	За замовчуванням	Опис
sender	Так	Рядок	Ні	Ім'я відправника SMS. від 1 до 11 символів для буквено-цифрового імені відправника (складається з латинських літер, символів, цифр, пробілів). від 1 до 15 символів для числового імені відправника/.
phones	Так	Масив		Масив одержувачів.
number	Так	ціле число	Ні	Номер телефону, на який відправляється SMS. Від 9 до 15 цифр (номер телефону вказується без +).
reference_id	Ні	рядок	Ні	зовнішній ідентифікатор SMS. Рядок довжиною до 32 символів, що містить /a-zA-Z0-9/
text	Так	рядок	Ні	Текст повідомлення, яке буде надіслано. Максимальна кількість символів для тексту повідомлення: 335 символів кирилиці. 765 символів латиницею.
validity	Ні	ціле число	72	Термін дії SMS в годинах. Ціле число від 1 до 72. За замовчуванням 72 години.
tariff_code	Ні	ціле число	0	Код тарифу, за яким будуть тарифікуватися агітаційні повідомлення. Ви можете вказати лише тариф, підключений до вашого облікового запису. Формат параметра — ціле число від 0 до 9. За замовчуванням — 0.
start_at	Ні	рядок	теперішній час	Дата та час надсилання повідомлення у форматі ISO 8601: рррр-мм-дд гг:хх:сс. Використовується лише для планування кампаній на певний час. Максимальний термін планування – 30 днів.

Приклад запиту

{

  "phones": [

    {

      "number": 12345678900,

      "reference_id": "string"

    }

  ],

  "sender": "string",

  "tariff_code": 0,

  "text": "string",

  "validity": 72,

  "start_at": "2025-01-25 09:00:00"

}

 

 

Параметри відповіді

Parameter		Type	Description
id		ціле число	Ідентифікатор створеної кампанії.
name		рядок	Автоматично створена назва кампанії.
sender		рядок	Ім'я відправника.
status		рядок	Статус кампанії. Можливі значення: creation – створенa spam - кампанія не пройшла модерацію; scheduled - кампанія запланована; sending - кампанія почала відправлятися; paused - кампанія призупинена; stopped - кампанію зупинено; done - кампанія завершена.
message_type		рядок	Тип кампанії: sms.
start_at		рядок	Дата та час початку запланованої кампанії. Формат відображення відповідно до ISO 8601: рррр-мм-дд гг:хх:сс
real_start_at		рядок	Фактична дата та час початку кампанії. Формат відображення відповідно до ISO 8601: рррр-мм-дд гг:хх:сс
finished_at		рядок	Дата й час завершення кампанії. Формат відображення відповідно до ISO 8601: рррр-мм-дд гг:хх:сс
created_at		рядок	Дата й час створення кампанії. Формат відображення відповідно до ISO 8601: рррр-мм-дд гг:хх:сс
statistics		масив	Статистика кампанії:
	delivered	ціле число	Загальна кількість повідомлень, доставлених у рамках кампанії
	sent	ціле число	Загальна кількість повідомлень, надісланих у рамках кампанії

Зразок відповіді

Якщо запит успішний:

{

  "data": {

    "id": 1,

    "name": "string",

    "sender": "string",

    "status": "creation",

    "message_type": "sms",

    "start_at": "2021-04-27 19:44:06",

    "real_start_at": "2021-04-27 19:44:06",

    "finished_at": "2021-04-27 19:44:06",

    "created_at": "2021-04-27 19:44:06",

    "statistics": {

      "delivered": 0,

      "sent": 0

    }

  }

}

2. Створіть SMS-кампанію для списку контактів із книги контактів

Цей спосіб дозволяє надсилати SMS до списку контактів із Книги контактів. Кампанія може включати персоналізовані дані з контактних полів у текст повідомлення для кожного контакту.

Для однієї кампанії можна вказати не більше 10 000 контактів.

Обмеження:

У режимі ДЕМО-облікового запису створення кампанії через API недоступне.
У режимі платформи TEST створення кампанії можливе лише для перевірених номерів.

Запит URL

POST http://one-api.bsg.world/api/campaigns/sms/send-groups

Параметри запиту

Параметр	Необхідність	Тип	За замовчуванням	Опис
groups[]	Так	Масив<int>		Масив списків з контактами з адресної книги. Ідентифікатор списку з контактами, яким потрібно надіслати SMS.
sender	Так	рядок	Ні	Ім'я відправника SMS:  від 1 до 11 символів для буквено-цифрового імені відправника (складається з латинських літер, символів, цифр і пробілів); від 1 до 15 символів для цифрового імені відправника.
text	Так	рядок	Ні	Текст повідомлення. Для заміни персоналізованих даних одержувача в тексті повідомлення вкажіть ідентифікатор(и) поля(ів) контакту у формі {field_id}. Максимальна кількість символів для тексту повідомлення: 335 символів кирилиці; 765 символів латиницею.
validity	Ні	ціле число	72	Термін дії SMS в годинах. Ціле число від 1 до 72. За замовчуванням 72 години.
tariff_code	Ні	ціле число	0	Номер тарифу, за яким будуть тарифікуватися агітаційні повідомлення. Ви можете вказати лише тариф, підключений до вашого облікового запису. Ціле число від 0 до 9. За замовчуванням 0.
start_at	Ні	рядок	Теперішній час	Дата та час надсилання повідомлення у форматі ISO 8601: рррр-мм-дд гг:хх:сс. Використовується лише для планування кампаній на певний час. Максимальний термін планування – 30 днів. Якщо користувач не вказав значення, встановлюється значення зараз (кампанія без затримки).

Приклад запиту

{

  "groups": [

1

  ],

  "sender": "string",

  "text": "string",

  "tariff_code": 0,

  "validity": 72,

  "start_at": "2025-01-25 09:00:00"

}

 

Параметри відповіді

Parameter		Type	Description
id		ціле число	Ідентифікатор створеної кампанії.
name		рядок	Автоматично створена назва кампанії.
sender		рядок	Ім'я відправника.
status		рядок	Статус кампанії. Можливі значення: creation – створенa spam - кампанія не пройшла модерацію; scheduled - кампанія запланована; sending - кампанія почала відправлятися; paused - кампанія призупинена; stopped - кампанію зупинено; done - кампанія завершена.
message_type		рядок	Тип кампанії: sms.
start_at		рядок	Дата та час початку запланованої кампанії. Формат відображення відповідно до ISO 8601: рррр-мм-дд гг:хх:сс
real_start_at		рядок	Фактична дата та час початку кампанії. Формат відображення відповідно до ISO 8601: рррр-мм-дд гг:хх:сс
finished_at		рядок	Дата й час завершення кампанії. Формат відображення відповідно до ISO 8601: рррр-мм-дд гг:хх:сс
created_at		рядок	Дата й час створення кампанії. Формат відображення відповідно до ISO 8601: рррр-мм-дд гг:хх:сс
statistics		масив	Статистика кампанії:
	delivered	ціле число	Загальна кількість повідомлень, доставлених у рамках кампанії
	sent	ціле число	Загальна кількість повідомлень, надісланих у рамках кампанії

Зразок відповіді

Якщо запит успішний, ви отримаєте відповідь:

{

  "data": {

    "id": 1,

    "name": "string",

    "sender": "string",

    "status": "creation",

    "message_type": "sms",

    "start_at": "2021-04-27 19:44:06",

    "real_start_at": "2021-04-27 19:44:06",

    "finished_at": "2021-04-27 19:44:06",

    "created_at": "2021-04-27 19:44:06",

    "statistics": {

      "delivered": 0,

      "sent": 0

    }

  }

}

 

}

3. Створіть персоналізовану SMS-кампанію

Цей спосіб дозволяє надсилати персоналізовані SMS-кампанії на список телефонних номерів. Персоналізована кампанія містить різний текст повідомлення для всіх номерів одержувачів.

Для однієї кампанії можна вказати не більше 10 000 контактів.

Обмеження:

У режимі ДЕМО-облікового запису створення кампанії через API недоступне.
У режимі ТЕСТОВОЇ платформи створення кампанії можливе лише для номерів, які додані до Контактної книги.

URL запиту

POST http://one-api.bsg.world/api/campaigns/sms/send-individual

Параметри запиту

Параметир		Необхідність	Тип	За замовчуванням	Опис
messages		Так	масив	Ні	Масив об’єктів повідомлень (до 10 000 номерів на одну кампанію одночасно):
	phone	Так	ціле число	Ні	Номер телефону, на який відправляється SMS. Від 9 до 15 цифр (номер телефону вказується без +)
	sender	Так	рядок	Ні	Ім'я відправника SMS: від 1 до 11 символів для буквено-цифрового імені відправника (складається з латинських літер, символів, цифр і пробілів); від 1 до 15 символів для цифрового імені відправника.
	text	Так	рядок	Ні	Текст повідомлення. Максимум 335 символів кирилицею, 765 символів латиницею.
	reference_id	Ні	рядок	Ні	зовнішній ідентифікатор SMS. Рядок до 32 символів, що містить /a-zA-Z0-9/.
validity		Ні	ціле число	72	Термін дії SMS. Термін дії SMS в годинах. Ціле число від 1 до 72. За замовчуванням 72 години.
tariff_code		Ні	ціле число	0	Номер тарифу, за яким будуть тарифікуватися агітаційні повідомлення. Ви можете вказати лише тариф, підключений до вашого облікового запису. Формат параметра — ціле число від 0 до 9. За замовчуванням — 0.
start_at		Ні	рядок	Нинішній час	Дата та час надсилання повідомлення у форматі ISO 8601: рррр-мм-дд гг:хх:сс. Використовується лише для планування кампаній на певний час. Максимальний термін планування – 30 днів. Якщо користувач не вказав значення, встановлюється значення зараз (кампанія без затримки).

Приклад запиту

{

  "messages": [

    {

      "phone": 12345678900,

      "text": "Hello! How are you?",

      "sender": "testsms",

      "reference_id": "Test98765"

    }

  ],

  "tariff_code": 0,

  "validity": 72,

  "start_at": "2025-01-25 09:00:00"

}

 

 

 

 

Параметри відповіді

Parameter		Type	Description
id		ціле число	Ідентифікатор створеної кампанії.
name		рядок	Автоматично створена назва кампанії.
sender		рядок	Ім'я відправника.
status		рядок	Статус кампанії. Можливі значення: creation – створенa spam - кампанія не пройшла модерацію; scheduled - кампанія запланована; sending - кампанія почала відправлятися; paused - кампанія призупинена; stopped - кампанію зупинено; done - кампанія завершена.
message_type		рядок	Тип кампанії: sms.
start_at		рядок	Дата та час початку запланованої кампанії. Формат відображення відповідно до ISO 8601: рррр-мм-дд гг:хх:сс
real_start_at		рядок	Фактична дата та час початку кампанії. Формат відображення відповідно до ISO 8601: рррр-мм-дд гг:хх:сс
finished_at		рядок	Дата й час завершення кампанії. Формат відображення відповідно до ISO 8601: рррр-мм-дд гг:хх:сс
created_at		рядок	Дата й час створення кампанії. Формат відображення відповідно до ISO 8601: рррр-мм-дд гг:хх:сс
statistics		масив	Статистика кампанії:
	delivered	ціле число	Загальна кількість повідомлень, доставлених у рамках кампанії
	sent	ціле число	Загальна кількість повідомлень, надісланих у рамках кампанії

Приклад відповіді

Якщо запит успішний, ви отримаєте відповідь:

{

  "data": {

    "id": 1,

    "name": "string",

    "sender": "string",

    "status": "creation",

    "message_type": "sms",

    "start_at": "2021-04-27 19:44:06",

    "real_start_at": "2021-04-27 19:44:06",

    "finished_at": "2021-04-27 19:44:06",

    "created_at": "2021-04-27 19:44:06",

    "statistics": {

      "delivered": 0,

      "sent": 0

    }

  }

}

 

4. Скасувати SMS-кампанію

Цей метод дозволяє скасувати SMS-кампанію, надіслану через API. Скасування можливе лише для кампанії, яка перебуває в статусі створення, призупинено, надсилання або заплановано.

URL запиту

PATCH http://one-api.bsg.world/api/campaigns/{id}/stop

Параметри запиту

Параметр	Необхідність	Тип	За замовчуванням	Опис
id	Так	Ціле число	Ні	Ідентифікатор кампанії, створеної за допомогою POST: POST /api/campaigns/sms/send POST /api/campaigns/sms/send-groups POST /api/campaigns/sms/send-individual

Параметри відповіді

Parameter		Type	Description
id		ціле число	Ідентифікатор створеної кампанії.
name		рядок	Автоматично створена назва кампанії.
sender		рядок	Ім'я відправника.
status		рядок	Статус кампанії. Можливі значення: creation – створенa spam - кампанія не пройшла модерацію; scheduled - кампанія запланована; sending - кампанія почала відправлятися; paused - кампанія призупинена; stopped - кампанію зупинено; done - кампанія завершена.
message_type		рядок	Тип кампанії: sms.
start_at		рядок	Дата та час початку запланованої кампанії. Формат відображення відповідно до ISO 8601: рррр-мм-дд гг:хх:сс
real_start_at		рядок	Фактична дата та час початку кампанії. Формат відображення відповідно до ISO 8601: рррр-мм-дд гг:хх:сс
finished_at		рядок	Дата й час завершення кампанії. Формат відображення відповідно до ISO 8601: рррр-мм-дд гг:хх:сс
created_at		рядок	Дата й час створення кампанії. Формат відображення відповідно до ISO 8601: рррр-мм-дд гг:хх:сс
statistics		масив	Статистика кампанії:
	delivered	ціле число	Загальна кількість повідомлень, доставлених у рамках кампанії
	sent	ціле число	Загальна кількість повідомлень, надісланих у рамках кампанії

Приклад відповіді

{

  "data": {

    "id": 1,

    "name": "string",

    "sender": "string",

    "status": "creation",

    "message_type": "sms",

    "start_at": "2021-04-27 19:44:06",

    "real_start_at": "2021-04-27 19:44:06",

    "finished_at": "2021-04-27 19:44:06",

    "created_at": "2021-04-27 19:44:06",

    "statistics": {

      "delivered": 0,

      "sent": 0

    }

  }

}

 

 

 }

 }

}