Each API request response returns an array consisting of three fields, one of which is code. This field contains the request processing status and can serve as a guide for further actions by the client application. The following table shows the API codes and their meanings:
| Code | Description |
|---|---|
| 0 | Operation completed successfully. |
| 1 | Validation error of the transmitted data during the creation or update of any entity. The data field contains information on which fields are filled incorrectly. Correct the errors and repeat the request with new data. |
| 2 | The specified record was not found. Most likely it has been deleted, the record ID is incorrect, or the user trying to access this record does not have the necessary permissions. |
| 3 | Unidentified application error. Contact support and provide details of the request during which it was received. |
| 4 | Incorrect module parameter specified. Check the correctness of the parameter in the API documentation. |
| 5 | Incorrect method parameter specified. Check the correctness of the parameter in the API documentation. |
| 6 | Incorrect format parameter specified. Check the correctness of the parameter in the API documentation. |
| 8 | Login error. Occurs in cases where:
message field. |
| 9 | Error accessing the specified API method. |
| 10 | Error saving data on the server directly during this operation. This error is usually associated with simultaneous access to data from multiple clients or changes to data saving conditions during saving. |
| 11 | Some required parameters are missing from the request. Check the correctness of the parameters in the API documentation and complete the request with the necessary parameters. |
| 12 | The input parameter of the request does not meet the established conditions or limitations. This error code occurs when a parameter violates restrictions during the execution of a request. It is similar to an attribute validation error but can be obtained in requests that do not create or modify data. |
| 13 | Attempt to make a request to an API server that does not serve this user. If this code is received, the correct domain can be obtained in the data field. |
| 14 | This error occurs if the user's account is blocked or deleted. |
| 15 | Error during the execution of any operation not related to data update. Details of this error are specified in the message field of the API response. |
| 30 | Exceeded permissible request rate limit. This error occurs when there are too frequent calls to the same API method within a certain period. Reduce the request frequency if this error occurs. |
| 98 | The operation was not fully completed but only with some data. This code is usually returned during any mass operations, where some elements were not processed due to errors or restrictions, but some elements were processed. If this code is received, information about which elements were processed and which were not, along with the errors, can be obtained in the data field. |
| 99 | None of the elements of the mass operation were processed. Detailed information about errors in each specific element can be obtained in the data field, and a general error description in the message field. |
| 100 | This code is not an error and means that the operation was sent for background execution. In this case, the data field contains the ID of the background operation, which can be tracked using the API TaskQueue/GetStatus. |
| 999 | General service error. Details can be obtained in the message field. |
ID – a unique identifier that allows unambiguous identification of the desired object: campaign, group, etc.
Contact Card – a record in the Contact Book containing customer data such as full name, email, date of birth, and other information. Must contain a phone number.
Sender ID (alphanumeric name) – displayed as the sender of SMS on the recipient's phone instead of a phone number.
There are several requirements for sender IDs.
Shared Sender ID (SMS sender) – one of the service signatures used when sending a message if the user has no signatures or the selected signature is not available for sending to the specified phone number.
Recipient (subscriber) – a mobile network user to whose number the SMS message is sent.
Short Link – a shortened (alternative) URL for accessing a web page.
Using a short link instead of a regular one minimizes unintended URL distortion – the short link is easier to remember, copy, or enter manually.
Statistical data is provided in a convenient form: you can see the number of clicks for the last 2 hours, day, week, 30 days, or all time (for more details, see the section on short links).
Short links are also convenient to use in SMS. They allow you to reduce the cost of sending due to the smaller number of characters in the message.
When using a short link created in our service, you can enable the recipient tracking feature to see who clicked on the link.
Personal Link (recipient tracking link) – a special short link created using our service that allows tracking which specific recipients of the SMS campaign clicked on it. The link is unique for each individual SMS recipient.
Recipient Tracking Feature – a tool for collecting statistics on recipients who clicked on the short link included in the message.
This is a convenient and effective means for analyzing the target audience and evaluating the effectiveness of the SMS campaign.
The feature is available for SMS messages containing hyperlinks. To activate the feature, in the SMS Sending Form, click the button to replace the regular link with a short one and check if the "track recipients" option is selected.
Delivery Report (DLR) – information from the mobile operator about the status of SMS delivery to the recipient.
SMS Campaign – allows you to group multiple recipients of a single SMS and analyze the results of the SMS campaign.
Single Campaign – sending a message to one number.
Mass Campaign – sending a message to two or more numbers.
Functional (service) Campaign – includes functional or, in other words, service system messages, such as messages with a phone number confirmation code from forms.
Template Campaign – a type of SMS campaign that uses a special message form containing placeholders that are replaced with personalized text for each recipient.
Template Example
Placeholders are placed in curly braces {}.
| Template text with placeholders | Text that will be delivered to the recipient |
|---|---|
| Hello, {name}! Your balance on {date} is {balance}{currency}. | Hello, Ivan! Your balance on 12.09.2019 is 15.50 UAH. |
| {name}, the car has arrived ({carNumber}). Driver's phone: {driverPhone}. | Alexey, the car has arrived (AA 4444). Driver's phone: 099 999 99 99. |
| We remind you that you have an appointment at {place}. Appointment date: {date}. | We remind you that you have an appointment at Clinic on 11.11.2019 at 11:30. |
Form – a convenient tool for collecting client data, conducting electronic surveys, forming a database of numbers for mailing, and many other tasks.
With Forms, your clients can subscribe to SMS mailings, news, promotions, etc.
Thanks to the flexible and intuitive field constructor, you can easily create a Form that is most effective for your tasks.
In addition, you can customize the Form's design: choose the color of the text, buttons, background, etc. For more details on creating Forms, see the “Forms” section.
| Status | Final | Description |
|---|---|---|
NEW | no | New message, not yet sent. |
ENQUEUD | no | Queued for sending. |
ACCEPTD | no | Sent from the system and accepted by the operator for further forwarding to the recipient. |
UNDELIV | yes | Not delivered to the recipient. |
REJECTD | yes | Rejected by the operator for one of many reasons – incorrect recipient number, prohibited text, sender signature not registered, etc. |
PDLIVRD | no | Not all segments of the message delivered to the recipient (this status can only be for messages, not segments). Some operators return a report only on the first delivered segment, so such a message will transition to the status set for the first segment after the expiration of its lifetime. |
DELIVRD | yes | Fully delivered to the recipient. |
EXPIRED | yes | Delivery failed as the waiting period expired without the message being delivered to the recipient. Typically, delivery is impossible if the recipient's phone is turned off, out of network coverage, or the device memory is full. The maximum waiting time for delivery is 1 day from the moment of sending. |
DELETED | yes | Deleted due to some restrictions on the operator's side and not delivered to the recipient. |
In every server-side language, there is a function that returns a string where all non-alphanumeric characters, except - _ ., are replaced with a percent sign (%) followed by two hexadecimal digits, and spaces are encoded as a plus sign (+). The string is encoded in the same way as POST data from web forms, that is, as application/x-www-form-urlencoded. This differs from RFC 3986 encoding in that, for historical reasons, spaces are encoded as a plus sign (+).