1. Create Individual/Bulk SMS Campaign

This method enables you to create:

Individual SMS campaigns for a single phone number.
Bulk SMS campaigns for a list of phone numbers. Each campaign contains one text for all recipient numbers. You can specify up to 10,000 contacts for one campaign.

Limitations:

Campaign creation via API is not available in DEMO account mode.
In TEST platform mode, campaign creation is only possible for numbers added to the Contact Book.

Request URL

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

Request Parameters

Parameter	Required	Type	Default	Description
sender	Yes	string	No	SMS Sender name. from 1 to 11 characters for the Sender's alphanumeric name (consists of Latin letters, symbols, numbers, spaces). from 1 to 15 characters for the Sender numeric name/.
phones	Yes	array		Recipients array.
number	Yes	integer	No	The phone number to which the SMS is sent. From 9 to 15 digits (phone number is specified without +).
reference_id	No	string	No	SMS external ID. String up to 32 characters long containing /a-zA-Z0-9/
text	Yes	string	No	The text of the message to be sent. Maximum number of characters for a message text: 335 characters Cyrillic. 765 characters Latin.
validity	No	integer	72	SMS validity period in hours. Integer from 1 to 72. By default 72 hours.
tariff_code	No	integer	0	Code of tariff at which the campaign messages will be billed. You can only specify the tariff connected to your account. The parameter format is an integer from 0 to 9. The default is 0.
start_at	No	string	now	Date and time of the message sending in ISO 8601 format: yyyy-mm-dd hh:mm:ss. Used only for scheduling campaigns for a specific time. The maximum date for scheduling is 30 days.

Request Sample

{

  "phones": [

    {

      "number": 12345678900,

      "reference_id": "string"

    }

  ],

  "sender": "string",

  "tariff_code": 0,

  "text": "string",

  "validity": 72,

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

}

Response Parameters

Parameter		Type	Description
id		integer	Created campaign ID.
name		string	Auto-generated campaign name.
sender		string	Sender name.
status		string	Campaign status. Possible values: creation - created; spam - campaign did not pass moderation; scheduled - campaign is scheduled; sending - campaign began to be sent; paused - campaign is paused; stopped - campaign is stopped; done - campaign is completed.
message_type		string	Campaign type: sms.
start_at		string	Date and time of the scheduled campaign start. Display format according to ISO 8601: yyyy-mm-dd hh:mm:ss
real_start_at		string	Actual date and time the campaign started. Display format according to ISO 8601: yyyy-mm-dd hh:mm:ss
finished_at		string	Date and time the campaign is completed. Display format according to ISO 8601: yyyy-mm-dd hh:mm:ss
created_at		string	Date and time the campaign is created. Display format according to ISO 8601: yyyy-mm-dd hh:mm:ss
statistics		array	Campaign statistics:
	delivered	integer	Total number of messages delivered within the campaign
	sent	integer	Total number of messages sent within the campaign

Response Sample

If the request is successful:

{

  "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. Create an SMS Campaign for the Contacts List from the Contact Book

This method enables the sending of SMS to the contacts list from the Contact Book. The campaign can include personalized data from the contact fields in the message text for each contact.

It is possible to specify no more than 10,000 contacts for one campaign.

Limitations:

In the DEMO account mode, creating a campaign via API is not available.
In TEST platform mode, campaign creation is possible only for verified numbers.

Request URL

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

Request Parameters

Parameter	Required	Type	Default	Description
groups[]	Yes	array<int>		An array of lists with contacts from the address book. The ID of the list with the contacts to which the SMS should be sent.
sender	Yes	string	No	SMS Sender name: f from 1 to 11 characters for the Sender alphanumeric name (consists of Latin letters, symbols, numbers, and spaces); from 1 to 15 characters for the Sender numeric name.
text	Yes	string	No	Message text. To substitute personalized data of the recipient in the message text, specify the identifier(s) of the contact field(s) in the form {field_id}. Maximum number of characters for a message text: 335 characters Cyrillic; 765 characters Latin.
validity	No	integer	72	SMS validity period in hours. Integer from 1 to 72. The default is 72 hours.
tariff_code	No	integer	0	Number of tariff at which the campaign messages will be billed. You can only specify the tariff connected to your account. Integer from 0 to 9. The default is 0.
start_at	No	string	now	Date and time of the message sending in ISO 8601 format: yyyy-mm-dd hh:mm:ss. Used only for scheduling campaigns for a specific time. The maximum date for scheduling is 30 days. If not specified by the user, the value is set to now (campaign without delay).

Request Sample

{

  "groups": [

1

  ],

  "sender": "string",

  "text": "string",

  "tariff_code": 0,

  "validity": 72,

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

}

Response Parameters

Parameter		Type	Description
id		integer	Created campaign ID
name		string	Campaign name: auto-generated for the created campaign
sender		string	Sender name
status		string	Campaign status. Possible values: creation - created; spam - campaign did not pass moderation; scheduled - campaign is scheduled; sending - campaign began to be sent; paused - campaign is paused; stopped - campaign is stopped; done - campaign is completed.
message_type		string	Campaign type: sms
start_at		string	Date and time of the campaign start (scheduled). Format ISO 8601: yyyy-mm-dd hh:mm:ss
real_start_at		string	Actual date and time the campaign started. Format ISO 8601: yyyy-mm-dd hh:mm:ss
finished_at		string	Date and time the campaign is completed. Format ISO 8601: yyyy-mm-dd hh:mm:ss
created_at		string	Date and time the campaign is created. Format ISO 8601: yyyy-mm-dd hh:mm:ss
statistics		array	Campaign statistics:
	delivered	integer	Total number of messages delivered within the campaign
	sent	integer	Total number of messages sent within the campaign

Response Sample

If the request is successful, you will receive a response:

{

  "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. Create a Personalized SMS Campaign

This method allows sending personalized SMS campaigns to a list of phone numbers. The personalized campaign contains different message text for all recipient numbers.

It is possible to specify no more than 10, 000 contacts for one campaign.

Limitations:

In the DEMO account mode, creating a campaign via API is not available.
In TEST platform mode, campaign creation is possible only for numbers that are added to the Contact Book.

Request URL

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

Request Parameters

Parameter		Required	Type	Default	Description
messages		Yes	array	No	Array of message objects (Up to 10,000 numbers per campaign at a time):
	phone	Yes	integer	No	The phone number to which the SMS is sent. From 9 to 15 digits (phone number is specified without +)
	sender	Yes	string	No	SMS Sender name: from 1 to 11 characters for the Sender alphanumeric name (consists of Latin letters, symbols, numbers, and spaces); from 1 to 15 characters for the Sender numeric name.
	text	Yes	string	No	Message text. Maximum 335 characters Cyrillic, 765 characters Latin.
	reference_id	No	string	No	SMS external ID. String up to 32 characters containing /a-zA-Z0-9/.
validity		No	integer	72	SMS validity period. SMS validity period in hours. Integer from 1 to 72. By default 72 hours.
tariff_code		No	integer	0	Number of tariff at which the campaign messages will be billed. You can only specify the tariff connected to your account. The parameter format is an integer from 0 to 9. The default is 0.
start_at		No	string	now	Date and time of message sending in ISO 8601 format: yyyy-mm-dd hh:mm:ss. Used only to schedule campaigns for a specific time. The maximum date for scheduling is 30 days. If not specified by the user, the value is set to now (campaign without delay).

Request Sample

{

  "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"

}

Response Parameters

Parameter		Type	Description
id		integer	Created campaign ID.
name		string	Campaign name: auto-generated for the created campaign.
sender		string	Sender name.
status		string	Campaign status. Possible values: creation - created; spam - campaign did not pass moderation; scheduled - campaign is scheduled; sending - campaign began to be sent; paused - campaign is paused; stopped - campaign is stopped; done - campaign is completed.
message_type		string	Campaign type: sms.
start_at		string	Date and time of the campaign start (scheduled). Format ISO 8601: yyyy-mm-dd hh:mm:ss.
real_start_at		string	Actual date and time the campaign started. Format ISO 8601: yyyy-mm-dd hh:mm:ss.
finished_at		string	Date and time the campaign is completed. Format ISO 8601: yyyy-mm-dd hh:mm:ss.
created_at		string	Date and time the campaign is created. Format ISO 8601: yyyy-mm-dd hh:mm:ss.
statistics		array	Campaign statistics:
	delivered	integer	Total number of messages delivered within the campaign
	sent	integer	Total number of messages sent within the campaign

Response Sample

If the request is successful, you will receive a response:

{

  "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. Cancel SMS Campaign

This method allows you to cancel an SMS campaign sent via the API. Cancellation is possible only for a campaign that is in the creation, paused, sending, or scheduled status.

Request URL

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

Request Parameters

Parameter	Required	Type	Default	Description
id	Yes	integer	No	The ID of the campaign created using POST: POST /api/campaigns/sms/send POST /api/campaigns/sms/send-groups POST /api/campaigns/sms/send-individual

Response Parameters

Parameter		Type	Description
id		integer	ID of the task created for a bulk campaign
name		string	Campaign name
sender		string	SMS Sender name
status		string	Campaign status. Possible values: creation - created; spam - campaign did not pass moderation; scheduled - campaign is scheduled; sending - campaign began to be sent; paused - campaign is paused; stopped - campaign is stopped; done - campaign is completed.
message_type		string	Campaign type: sms
start_at		string	Date and time of the campaign start (scheduled). Format ISO 8601: yyyy-mm-dd hh:mm:ss
real_start_at		string	Actual date and time the campaign started. Format ISO 8601: yyyy-mm-dd hh:mm:ss
finished_at		string	Date and time the campaign is completed. Format ISO 8601: yyyy-mm-dd hh:mm:ss
created_at		string	Date and time the campaign is created. Format ISO 8601: yyyy-mm-dd hh:mm:ss
statistics		array	Campaign statistics:
	delivered	integer	Total number of messages delivered within the campaign
	sent	integer	Total number of messages sent within the campaign

Response Sample

{

  "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

    }

  }

}

}

Articles in this section

SMS API

1. Create Individual/Bulk SMS Campaign

2. Create an SMS Campaign for the Contacts List from the Contact Book

3. Create a Personalized SMS Campaign

4. Cancel SMS Campaign

Comments

Articles in this section

1. Create Individual/Bulk SMS Campaign

2. Create an SMS Campaign for the Contacts List from the Contact Book

3. Create a Personalized SMS Campaign

4. Cancel SMS Campaign

Related articles