SMS API

Sending SMS messages

For information about the authentication and authorization procedures that associate API calls with the required applications in your account, see Authorization.

Request:

Parameters can be passed in the request headers:

POST/GET https://api.unibell.ru/v2/sms?X-Authorization=AccessKey d8ac9959r12b43545XXXXX&destAddr=7XXXXXXXXXX&sourceAddr=MySender&shortMessage=Message text

As well as in the request body:

{
    "sourceAddr": "MySender",
    "destAddr": "7XXXXXXXXXX",
    "shortMessage": "Message text"
}

Example request using CURL:

curl --location --request POST 'https://api.unibell.ru/v2/sms?X-Authorization=AccessKey%20d8ac9959r12b43545XXXXX&destAddr=7XXXXXXXXXX&sourceAddr=MySender&shortMessage=Message text'

curl --location 'https://api.unibell.ru/v2/sms?=' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX' \
--header 'Content-Type: application/json' \
--data '{
    "sourceAddr": "MySender",
    "destAddr": "7XXXXXXXXXX",
    "shortMessage": "Message text"
}'

Parameter	Type	Description
sourceAddr	string	Sender name (Latin letters only or phone number) *The field must not contain Cyrillic characters*
destAddr	string	Phone number to which the SMS is sent, in e.164 format, for example, for the Russian Federation: 7XXXXXXXXXX 7XXXXXXXXXX
shortMessage	string	Message text

Response upon successful request execution:

{
    "status": "Created",
    "requestId": "11273"
}

Response in case destAddr is missing:

{
    "status": "Rejected",
    "error": "Missing destAddr param"
}

Parameter	Type	Description
status	string	Request status: _{Created – Message created in the system but not yet sent Rejected – Message was not accepted for sending, see error for details prohibitedForServiceError – Key does not belong to the SMS service invalidAccessKeyError – Authorization key error}
requestId	string	Unique request identifier
error	string	Error description: _{Missing destAddr param – destAddr is missing in the request Missing sourceAddr param – sourceAddr is missing in the request Missing shortMessage param – shortMessage is missing in the request Field sourceAddr must not contain Cyrillic – sourceAddr contains Cyrillic characters}

Bulk SMS message sending

Request:

POST/GET https://api.unibell.ru/v2/sms_bulk?X-Authorization=AccessKey d8ac9959r12b43545XXXXX

Request body:

{
    "sourceAddr": "MySender",
    "destAddrs": [
        "79123213232",
        "2вауц",
        "71233212323"
    ],
    "shortMessage": "Message text"
}

Example request using CURL:

curl --location 'https://api.unibell.ru/v2/sms_bulk' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX' \
--header 'Content-Type: application/json' \
--data '{
    "sourceAddr": "MySender",
    "destAddrs": [
        "79123213232",
        "2вауц",
        "71233212323"
    ],
    "shortMessage": "Message text"
}'

Parameter	Type	Description
sourceAddr	string	Sender name *The field must not contain Cyrillic characters*
destAddrs	string	List of phone numbers to which SMS messages are sent, in e.164 format, for example, for the Russian Federation: 7XXXXXXXXXX
shortMessage	string	Message text

Response body upon request execution:

{
    "status": "ok",
    "results": [
        {
            "status": "Created",
            "requestId": "11276",
            "destAddr": "79123213232"
        },
        {
            "status": "Rejected",
            "error": "Not valid destAddr",
            "destAddr": "2test"
        },
        {
            "status": "Created",
            "requestId": "11277",
            "destAddr": "71233212323"
        }
    ]
}

Parameter	Type	Description
status	string	Request status: _{Created – Message created in the system but not yet sent Enroute – Message routed and awaiting sending Delivered – Message delivered, delivery status received from operator Expired – Message lifetime expired Deleted – Message was canceled Undeliverable – Message not delivered due to reasons such as: number does not exist, no space for new SMS on the phone Accepted – Message sent, delivery status from operator not yet received Unknown – Unknown error Rejected – Message was not accepted for sending, see error for details prohibitedForServiceError – Key does not belong to the SMS service invalidAccessKeyError – Authorization key error}
results	string	Results for each recipient
error	string	Error description: _{Missing destAddr param – destAddr is missing in the request Missing sourceAddr param – sourceAddr is missing in the request Missing shortMessage param – shortMessage is missing in the request Field sourceAddr must not contain Cyrillic – sourceAddr contains Cyrillic characters Not valid destAddr – destAddr is invalid}
requestId	string	Unique request identifier
destAddr	string	Phone number to which the SMS is sent, in e.164 format, for example, for the Russian Federation: 7XXXXXXXXXX

Retrieving status

Request:

Parameters can be passed in the request headers:

GET https://api.unibell.ru/v2/sms_status?X-Authorization=AccessKey d8ac9959r12b43545XXXXX&requestId=11273

As well as in the request body:

{
    "requestId": "11273"
}

Example requests using CURL:

curl --location 'https://api.unibell.ru/v2/sms_status' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX' \
--header 'requestId: 11273'

curl --location --request GET 'https://api.unibell.ru/v2/sms_status' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX' \
--header 'Content-Type: application/json' \
--data '{
    "requestId": "11273"
}'

Response body upon successful request execution:

{
    "id": 9654,
    "destAddr": "7XXXXXXXXXX",
    "requestId": "11273",
    "status": "Rejected",
    "networkErrCode": 34,
    "mcc": 0,
    "mnc": 0,
    "ported": 0
}

Response in case the requestId parameter is missing:

{
    "status": "Rejected",
    "error": "Missing requestId param"
}

Parameter	Type	Description
id	integer	Unique SMS message identifier
destAddr	string	Phone number to which the SMS was sent, in e.164 format, for example, for the Russian Federation: 7XXXXXXXXXX
requestId	string	Unique request identifier
status	string	SMS sending request status: _{Created – Message created in the system but not yet sent Enroute – Message routed and awaiting sending Delivered – Message delivered, delivery status received from the operator Expired – Message lifetime expired Deleted – Message was canceled Undeliverable – Message not delivered due to reasons such as: number does not exist, no space for new SMS on the phone Accepted – Message sent, delivery status from operator not yet received Unknown – Unknown error Rejected – Mobile network rejected the message, likely due to a filter or other restriction notFound – Record for the requested requestId does not exist/not found}
networkErrCode	string	SS7 errors, see below
mcc	integer	Mobile Country Code
mnc	integer	Mobile Network Code – mobile operator code
ported	integer	Indicates whether the number has been ported: _{1 – if the number was ported 0 – if not ported}
error	string	if not ported _{Missing requestId param – requestId is missing in the request}

Retrieving message statuses via Webhook

Request source:

Webhooks will be sent from the IP addresses 185.175.44.211 and 46.148.235.62, which must be added to the ACL on the client’s web server to ensure proper interaction.

Interaction format:

Callbacks are performed over the HTTP protocol.

Data is transmitted in JSON format.

Webhook setup is performed by submitting a request to technical support.

Sending a request:

The request is sent in JSON format, which has the following structure:

{
  "ported": 0,
  "mnc": 0,
  "requestId": "35714061",
  "destAddr": "7XXXXXXXXXX",
  "id": 639073386,
  "networkErrCode": 0,
  "mcc": 0,
  "status": "Delivered"
}

Parameter	Type	Description
ported	integer	Indicates whether the number has been ported: _{1 – if the number was ported 0 – if not ported}
mnc	integer	Mobile Network Code – mobile operator code
requestId	string	Unique request identifier
destAddr	string	Phone number to which the SMS is sent, in e.164 format, for example, for the Russian Federation: 7XXXXXXXXXX
id	integer	Уникальный идентификатор SMS-сообщения
networkErrCode	string	SS7 errors, see below
mcc	integer	Mobile Country Code
status	string	SMS sending request status: _{Created – Message created in the system but not yet sent Enroute – Message routed and awaiting sending Delivered – Message delivered, delivery status received from the operator Expired – Message lifetime expired Deleted – Message was canceled Undeliverable – Message not delivered due to reasons such as: number does not exist, no space for new SMS on the phone Accepted – Message sent, delivery status from operator not yet received Unknown – Unknown error Rejected – Message was not accepted for sending, see error for details}

Error codes in the status

Possible error codes in SMS status (networkErrCode).

All unspecified codes are considered vendor-dependent and are not handled separately.

Code	Description Key	Description
1	unknownSubscriber	Unknown subscriber _{The subscriber is not registered in the network}
5	unidentifiedSubscriber	Unidentified subscriber _{Subscriber is registered, but information about them is missing or unavailable}
9	illegalSubscriber	Illegal subscriber _{Access denied due to rule violation}
11	teleserviceNotProvisioned	Telecommunication service not provisioned _{Subscriber is not subscribed to the requested service}
13	callBarred	Call barred _{Calls are prohibited for this subscriber (e.g., due to blocking or tariff restrictions)}
21	facilityNotSupported	Facility not supported _{Requested service is unavailable for the subscriber or network}
27	adsentSubscriber	Address absent _{Message not delivered due to missing sender information}
31	subscriberBusyForMT-SMS	Subscriber busy for MT-SMS _{Subscriber cannot receive SMS due to device being busy}
32	sm-DeliverFailure	SMS delivery failure _{General error related to SMS transmission}
33	messageWaitingListFull	Message waiting list full _{Subscriber device memory has no space for new messages}
34	systemFailure	System failure _{General network-side error}
35	dataMissing	Data missing _{Insufficient information to complete the operation}
36	unexpectedDataValue	Unexpected data value _{Incorrect or unexpected data provided}

On this page