1. Create individual/bulk SMS Campaign
The method allows you to make:
- individual SMS campaign ― to one phone number;
- bulk SMS campaign to a list of phone numbers. The bulk campaign contains one text for all recipient numbers. It is possible to specify no more than 10 000 contacts for one campaign.
Limitation:
- In the DEMO account mode, creating a campaign via API is not available.
- In the TEST platform mode, creating a campaign is possible only for numbers that are 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:
|
|
|
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:
|
|
|
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. 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 |
Campaign name: auto-generated for the created campaign |
|
|
sender |
string |
Sender name |
|
|
status |
string |
Campaign status. Possible values:
|
|
|
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, 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 } } } |
2. Create an SMS campaign for the contacts list from the Contact Book
The method allows sending an SMS to the contacts list from the Contact Book. The campaign can contain personalized data from the contact fields in the text of the message for each contact.
It is possible to specify no more than 10 000 contacts for one campaign.
Limitation:
- In the DEMO account mode, creating a campaign via API is not available.
- In the TEST platform mode, creating a campaign is possible only for the 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> |
No |
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:
|
|
text |
Yes |
string |
No |
Message text. To substitute personalized data of the recipient in the text of the message, you must specify the identifier(s) of the contact field(s) in the form {field_id}. Maximum number of characters for a message text:
|
|
validity |
No |
integer |
72 |
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 the message sending in ISO 8601 format: yyyy-mm-dd hh:mm:ss. Used only to schedule campaigns for a specific time. 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:
|
|
|
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
The method allows sending personalized SMS рассылку to a phone numbers list. 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.
Limitation:
- In the DEMO account mode, creating a campaign via API is not available.
- In the TEST platform mode, creating a campaign is possible only for the 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.
|
|
|
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 |
No |
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. 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:
|
|
|
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
The method allows you to cancel the SMS campaign sent via the API.
Cancellation is possible only for a campaign that is in the creation / paused / sending / 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:
|
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 current status. Possible values:
|
|
|
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 |
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 } } } |
Comments
0 comments
Article is closed for comments.