Developer Docs

Table of contents

Send SMS to Contacts list

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.

To send SMS to Contacts list, make a request to this URL::

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

Request pаrаmeters:

ParameterRequiredTypeDefaultDescription
groups[]Yesarray <int>NoAn array of lists with contacts from the address book. The ID of the list with the contacts to which the SMS should be sent.
senderYesstringNoSMS Sender name:

  • 1 to 11 characters for the Sender alphanumeric name (consists of Latin letters, symbols, numbers, spaces)

  • 1 to 15 characters for the Sender numeric name
textYesstringNoMessage 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:
  • 335 characters Cyrillic

  • 765 characters Latin
validityNointeger72SMS validity period in hours.
Integer from 1 to 72. By default 72 hours.
tariff_codeNointeger0Number 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_atNostringnowDate 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:

ParameterTypeDescription
idintegerCreated campaign ID
namestringCampaign name: auto-generated for the created campaign
senderstringSender name
statusstringCampaign 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.
mesage_typestringCampaign type: sms
start_atstringDate and time of the campaign start (scheduled). Format ISO 8601: yyyy-mm-dd hh:mm:ss
real_start_atstringActual date and time the campaign started. Format ISO 8601: yyyy-mm-dd hh:mm:ss
finished_atstringDate and time the campaign is completed. Format ISO 8601: yyyy-mm-dd hh:mm:ss
created_atstringDate and time the campaign is created. Format ISO 8601: yyyy-mm-dd hh:mm:ss
statisticsarrayCampaign statistics:
deliveredintegerTotal number of messages delivered within the campaign
sentintegerTotal number of messages sent within the campaign

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