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 accountFinanciallyBlocked — The customer is blocked by the balance/Blocking by IP address
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 accountFinanciallyBlocked — The customer is blocked by the balance/Blocking by IP address
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
100	RejectedByIpBlockedException	Blocking by IP address
101	RejectedByFinBlockedException	Financial lockdown
102	SmsTemplateRejectedException	The template was not found

SMS error codes

Code	Name	Description
0	No error	No errors. Subscriber exists and is available
1	Unknown subscriber	The subscriber’s phone number does not exist, is inactive, or is no longer in use
2	Unknown subscriber – NR Changed	Number Portability error. May occur after multiple number portings
5	Unidentified subscriber	MSC cannot recognize the subscriber’s IMSI. Possible causes: HLR not updated or MSC failure
6	Absent subscriber for SMS	Subscriber’s device is unavailable for receiving SMS (phone is off or out of coverage)
7	Unknown equipment	Message rejected because the subscriber’s device is unrecognized
8	Roaming not allowed	Message rejected due to authentication or filtering error while roaming
9	Illegal subscriber	Message rejected due to authentication or filtering error
10	Bearer Service not provisioned	Subscriber’s plan does not support SMS
11	Teleservice not provisioned	Subscriber cannot receive SMS. Reasons: service not activated, subscriber roaming without SMS activation, or operator failed to enable SMS exchange
12	Illegal equipment	Message not delivered due to a phone or SIM error; device or network does not support SMS
13	Call barred	Subscriber blocked: zero/negative balance, operator restriction, damaged SIM, or incorrect PIN/PUK
21	Facility not supported	Subscriber’s plan or device does not support SMS service
27	Absent subscriber	Subscriber’s device not registered on the network (off or out of coverage)
28	Incompatible MS terminal error	SMS function not supported by the subscriber’s mobile device
31	Subscriber busy for SM MT	Subscriber’s device temporarily unavailable for SMS delivery
32	Equipment failure	Receiving device does not support SMS or the relevant function
33	MS memory capacity exceeded	Receiving device does not have enough memory to receive the message
34	GSM system failure	MSC rejected the message due to SS7 protocol failure or network error
35	GSM Data Error – data missing	GSM data missing
36	GSM Data Error	Incorrect GSM data
45	Subscriber busy	Subscriber currently cannot perform GSM operations
100	RejectedByIpBlockedException	Blocked by IP address
101	RejectedByFinBlockedException	Financial block
102	SmsTemplateRejectedException	Message template not found
500	Invalid destination address	Invalid recipient number
501-506	Routing error	Routing error
507	SystemFailure	General system failure
508	ThrottledException	Request or message limit exceeded (rate limit)
509	Invalid parameter length	Invalid message or parameter length
510	Invalid destination address	Invalid destination address
511	Loop detection error	Routing loop detected (cyclical sending)
512	Invalid source address	Invalid sender address
513	System error	Internal system error
999	Unspecified error	Unspecified error (general code without detailed cause)