Using HTTP API version 0.15
This API version has been superseded by version 0.16 described here. Version 0.15 will be available, supported, and fully functional, and will receive bugfixes in the future but no new functionality will be introduced in it.
The information we require to activate your account and API access to it is:
your server IP address (multiple addresses, wildcard substitution, and subnets are possible.)
An HTTP address for a webhook to pass the SMS delivery reports to. If delivery reports aren't necessary, this address can be omitted.
After we have this information we will provide you with an API key that you can use.
Note that if you have, for example, more than one environment you want to send SMS from, e.g., a development/testing server and a production server, you can implement two separate API accounts and have two separate API keys, if necessary.
The length of a standard SMS message is 160 characters from the GSM alphabet (as described here - SMS content and length). Longer SMS-es are possible by sending the message in separate parts, however, each of these parts will be charged as a standalone SMS.
When sending a multipart SMS, each part, however, is slightly shorter than the standard 160 symbols - a single part of a multipart SMS can be up to 153 symbols in length, i.e. a 160 symbol SMS can be sent as a single SMS, but a 170 symbol SMS will be sent as 2 messages, the first one 153 symbols in length, the second one - 17.
As the GSM alphabet contains only a small subset of all possible symbols, it is possible to send Unicode SMS messages including any characters that can be represented in the UCS-2 encoding, however, in doing this, note that maximum SMS length for a single part decreases to 70 symbols and a single part's length within a multipart SMS decreases to 67 symbols (each symbol takes up 2 bytes.)
Also, note that within the GSM alphabet, some symbols take up the place of two symbols, e.g., the euro sign €, square brackets [], etc.
In theory, it is possible to send a multipart SMS with up to 255 parts, however, due to compatibility issues between various carriers and phones, the SMS length is limited to max 7-part messages.
When sending a message via Traffic, you can specify any number or text as the sender ID (i.e., what will appear in the recipient phone as the sender of the message.) It may be your phone number, your brand name, or any other text you can think of. There are some limitations, though:
Sender IDs must be previously requested from us - upon request, they will be added to your account and only then can you use them.
Sender IDs must be between 3 and 11 characters in length for an alphanumeric sender ID or 3-14 characters in length for numeric sender ID (phone number).
Only 0-9, a-z, A-Z, and underscode(_) characters are allowed in an alphanumeric sender ID by the GSM standard. It is technically possible to use other characters but it may result in various errors, e.g., messages not being shown to users, messages shown under other sender’s names, messages being delivered repeatedly, sender ID being shown incorrectly etc.
Take care not to choose a sender ID that might result in a valid phone number when sender ID is transposed into numbers (e.g., 2 = ABC, 3 = DEF, etc.) Many phones will do it if you try to call or reply to an alphanumeric sender ID.
Depending on the agreement between you and SIA "Sales.lv", your account may have either a monthly quota for post-paid accounts or an SMS volume quota for pre-paid accounts. The monthly quota is set in agreement with both parties and is intended for preventing accidental sending of a large number of SMS-es.
The volume quota for pre-paid accounts depends on the paid amount.
After messages have been sent out, you can receive the delivery reports via webhook.
API address is https://traffic.sales.lv/API:0.15/
All requests should be made as HTTP POST requests with application/x-www-form-urlencoded media type.
Every request has these mandatory parameters (names are case-sensitive):
APIKey: API key allocated to you
Command: Name of the command
Other parameters depending on which command you are calling
The data returned from every command is serialized as JSON.
If there was an error with the request, you will receive an Error parameter with the relevant error code.
These error codes could be returned for any command:
InvalidAPIVersion: Address contains erroneous API version (the version according to this specification should be 0.12)
NoAPIKey: API key isn't specified or the APIKey parameter was empty
InvalidAPIKey: API key is invalid or doesn't exist
UnauthorizedIP: The request comes from an IP address that isn't authorized for use with this API key
CommandNotSpecified: Command isn't specified (Command parameter was empty)
CommandNotImplemented: The specified command doesn't exist or isn't available at this time
SystemError: Some other system error
This version of the API implements these commands:
SendOne: Sends a single SMS with the given parameters
SendMultiple: Sends multiple SMS messages with individually specified content for each recipient. (Can be used for sending single messages, as well.)
SendBatch: Creates a new SMS batch with the given parameters. Recipient numbers should be added afterwards with the AddBatchRecipients command.
AddBatchRecipients: Adds recipient numbers to an already created batch. Can be called multiple times GetSenders: returns a list with all available sender IDs (alphanumeric source IDs that show up as the sender of the SMS)
GetDelivery: Returns the delivery report for one or more messages by their ID numbers.
GetReport: Returns full data about one or more messages by their ID numbers.
Sends a single SMS message with the given parameters.
Input parameters:
Number: Recipient number. You can put country code before the number but it shouldn’t have a 00 or + prefix (as for internation numbers).
Sender: Alphanumeric sender ID text, e.g. your brand name.
Content: SMS content encoded in UTF-8 (for standard and for Unicode messages both.)
(optional) SendTime: Time, when sending should be started, encoded as a Unix timestamp. If not specified, messages will be sent immediately.
(optional) CC: Default country code to use for numbers where it isn't contained in the number. Defaults to whatever is specified in your account settings. If the number will contain a country code, this will not be used for the specific recipient
(optional) Concatenated: 0/1 - if it's 0, but the content is too long for a single-part SMS, an error will be returned. If it's 1, the SMS will be sent as a concatenated (long) multipart SMS, if necessary. If omitted, it will be determined automatically. (Notice that a multipart SMS will be charged per each part, e.g., a 3 part SMS will be charged as 3 SMS-es.
(optional) Unicode: 0/1 - if this is 0, but the message contains non-GSM alphabet symbols, an error will be returned. If it's 1, the SMS will be sent as a Unicode SMS, if necessary. If omitted, it will be determined automatically.
(optional) Validity: Validity period (in minutes) of the SMS message, i.e., the time after which the mobile operator gives up and stops retrying delivery in case the phone number is valid but isn't immediately reachable. Defaults to 1440 (24 hours.)
The response will contain these parameters:
MSSID: Message ID that can be used for receiving delivery reports.
Length: Number of SMS parts
Unicode: Unicode indication (0 = message sent in GSM alphabet, 1 = message sent in UCS-2)
LongSMS: Multipart message indication (0 = single-part SMS, 1 = multipart message.)
Invalid: Reason why the message could have been erroneous
Network: Mobile network the number belongs to, more about it at the end of this document.
- or -
Error: Error code if there was any problem. If there wasn't any errors, this parameter will be omitted.
Possible errors:
InvalidNumber: Recipient number incorrect
InvalidSender: Sender ID doesn’t exist or isn’t available
NoContent: No content specified
InvalidCC: Incorrect or unsupported country code, if specified
ContentTooLong: Content is too long - either the content is just too long or, if Concatenated = 0, content is longer than a single SMS part.
ContentContainsInvalidCharacters: If Unicode=0 and message contains non-GMS alphabet characters, this error will be returned
MonthlyQuotaExceeded: Monthly quota for your account exceeded
Sends multiple SMS messages in a single API call with individually specified content for each recipient. (Can be used for sending single messages, as well.)
Input parameters:
Sender: Alphanumeric sender ID text, e.g. your brand name.
Content: JSON array, where every element contains recipient number and message to be sent to that number. Message content should be in UTF-8 (for both standard and Unicode messages). For example:
(optional) SendTime: Time, when sending should be started, encoded as a Unix timestamp. If not specified, messages will be sent immediately.
(optional) CC: Default country code to use for numbers where it isn't contained in the number. Defaults to whatever is specified in your account settings. If the number will contain a country code, this will not be used for the specific recipient
(optional) Concatenated: 0/1 - if it's 0, but the content is too long for a single-part SMS, an error will be returned. If it's 1, the SMS will be sent as a concatenated (long) multipart SMS, if necessary. If omitted, it will be determined automatically. (Notice that a multipart SMS will be charged per each part, e.g., a 3 part SMS will be charged as 3 SMS-es.
(optional) Unicode: 0/1 - if this is 0, but the message contains non-GSM alphabet symbols, an error will be returned. If it's 1, the SMS will be sent as a Unicode SMS, if necessary. If omitted, it will be determined automatically.
The response will contain an associative array having message IDs (MSSID) as keys and these fields in the values:
MSSID: SMS ID that can be used for receiving delivery reports
CC: Country code of number;
Phone: Phone number;
Content: Message content;
Unicode: Unicode indication (0 = GSM alphabet, 1 = UCS-2);
LongSMS: Multipart message indication (0 = single-part SMS, 1 = multipart SMS);
Invalid: Reason why message could have been erroneous. If the phone number or message is fine, this field will be empty.
Length: Length of message (number of message parts);
Network: Mobile network the number belongs to, more about it at the end of this document.
or
Error: Error code if there was a problem with the API call altogether.
Possible errors:
InvalidSender: Sender ID doesn't exist, is incorrect or is not available
InvalidContent: Content not specified or there was some other problem with message content.
InvalidCC: Incorrect or unsupported country code (if specified)
QuotaExceeded: Montly or volume quota exceeded.
creates a new SMS batch with the given parameters. Recipient numbers should be added afterwards with the AddBatchRecipients command.
Input parameters:
Sender: Alphanumeric Sender ID text.
Content: SMS content encoded in UTF-8
(optional) SendTime: Time, when sending should be started, encoded as a Unix timestamp. If not specified, SMS-es will be sent as soon as the recipient list is received.
(optional) CC: Default country code to use for numbers where it isn't contained in the number. Defaults to whatever is specified in your account settings. If the number will contain a country code, this code will not be used for the specific recipient and the code in the phone number takes precedence.
(optional) Concatenated: 0/1 - if it's 0, but the content is too long for a single-part SMS, an error will be returned. If it's 1, the SMS will be sent as a concatenated (long) multipart SMS, if necessary. If omitted, it will be determined automatically. (Notice that a multipart SMS will be charged per each part, e.g., a 3 part SMS will be charged as 3 SMS-es.
(optional) Unicode: 0/1 - if this is 0, but the message contains non-GSM alphabet symbols, an error will be returned. If it's 1, the SMS will be sent as a Unicode SMS, if necessary. If omitted, it will be determined automatically.
The response will contain these parameters:
BatchID: Batch ID, that must be used when adding recipient numbers to the batch with AddBatchRecipients.
Error: Error code, if there was a problem with the command in general. If there was no error, this parameter will be omitted.
Possible errors:
InvalidSender: This sender ID is erroneous, doesn't exist or isn't available
NoContent: SMS content wasn't specified (content was empty)
InvalidCC: Erroneous or unsupported country code
ContentTooLong: Content was too long - either the content is too long for a multipart SMS or, if the Concatenated parameter contained 0, it was too long for a single-part SMS
ContentContainsInvalidCharacters: If the Unicode parameter was 0 and message content has non-GSM alphabet characters, this error will be returned
QuotaExceeded: Quota was exceeded
Adds recipient numbers to an already created batch. Can be called multiple times GetSenders: returns a list with all available sender IDs (alphanumeric source IDs that show up as the sender of the SMS)
Input paramaters:
BatchID: Batch ID returned from SendBatch.
Recipients: JSON array with recipient numbers, e.g. "[3712987654321, 37129999999, ...]"
The response will contain these parameters:
MSSID: Associative array where the key will be the phone number and the value will be the SMS ID. In case if there was a problem with this specific recipient, the value will be an error code.
Error: Error code, if there was a problem with the command in general. If there was no error, this parameter will be omitted,
If any number is repeated several times in the recipient list, it will have only one entry in the MSSID list with a single SMS ID and the recipient will receive only one SMS.
Possible errors:
As MSSID values:
-1: Any other error;
-2: Incorrect number - doesn't conform to the number format for the
specific country;
-3: Incorrect number - number is technically correct but isn't registered to a mobile network or is registered to a network where SMS messaging is not possible. This currently works for a limited amount of countries. This error could be returned also if the number is registered but isn't a mobile phone number.
-4: quota exceeded
In the Error parameter:
InvalidBatchID: Batch ID doesn't exist or isn't available
InvalidRecipients: Recipient list cannot be parsed
QuotaExceeded: Quota exceeded. The error is returned only if the quota is already exceeded prior to this command. If quota is exceeded after sending SMS to a part of these recipients, every number over the quota will have the -4 error.
Retrieves a list of all sender IDs assigned to your account.
Input parameters: none
Response parameters:
Senders: An array containing all assigned sender IDs or empty array in case none are assigned.
Returns the delivery report for one or more messages by their ID numbers
Input parameters:
MSSID: A single message ID or a JSON array with multiple message IDs.
Response contains
an associative array with message IDs as keys and values as delivery reports
or
Error: Error code if there was a problem with the API call altogether.
Possible errors:
InvalidMSSID: Erroneous or not specified message ID.
Returns full data about one or more messages by their ID numbers
Input parameters:
MSSID: A single message ID or a JSON array with multiple message IDs.
Response contains an associative array with message IDs as keys and values containing:
ID: Message identifier;
CC: Country code for number;
Phone: Phone number;
Content: SMS content;
Unicode: Unicode indication (0 = GSM alphabet, 1 = UCS-2);
LongSMS: Multipart indicator (0 = single-part SMS, 1 = multipart SMS);
Length: Length of message (number of parts);
Status: SMS delivery status, one of the statuses described towards the end of the document;
SendTime: Time when message was sent;
DLRTime: Time when delivery report was received. (This is time when the report was received, not when the message was actually delivered or rejected.)
Validity: Validity period (in minutes) of the SMS message, i.e., the time after which the mobile operator gives up and stops retrying delivery in case the phone number is valid but isn't immediately reachable. Defaults to 1440 (24 hours.)
or:
Error: Error code if there was a problem with the API call altogether.
Possible errors:
InvalidMSSID: erroneous or not specified message ID.
Commands SendOne, SendMultiple, and AddBatchRecipients may return a parameter Invalid, that contains a reason why the number is not valid. These reasons could be:
Number: incorrect number format (e.g., Latvian number does not contain 8 digits);
CC: Number contains an invalid country code or country code is not supported at all. It also could indicate that sending to this country code is not permitted for your account.
MNP: Number doesn’t belong to any known mobile operator.
ContentLength: for messages where content is specified individually for each recipient, e.g., when sending with SendMultiple, the content for this particular number is too long.
Network: It is impossible to send the message to the network this number belongs to. E.g., if it isn’t a supported mobile operator or an operator that can actually accept SMS.
Such messages are not counted towards the account total and don't affect the account balance.
To indicate that a number belongs to a particular mobile network, message response contain an additional parameter Network that contains one of these codes:
In Latvia:
LMT: LMT
TELE2LV: Tele2 Latvia
BITELV: Bite Latvia
In Estonia:
TELE2EE: Tele2 Eesti
EMT: Telia Eesti, formerly EMT
ELISA: Elisa Eesti
In Lithuania:
TELE2LT: Tele2 Lietuva
OMNITEL: Telia Lietuva, formerly Omnitel
BITELT: Bite Lietuva
Additional network codes can be encountered and are subject to change in the future depending on network operator actions. However, these listed are the major operators in these and are not going to change.
Examples of API calls using various languages and technologies are provided in separate articles:
API calls using cURL
Before we start
The information we require to activate your account and API access to it is:
your server IP address (multiple addresses, wildcard substitution, and subnets are possible.)
An HTTP address for a webhook to pass the SMS delivery reports to. If delivery reports aren't necessary, this address can be omitted.
After we have this information we will provide you with an API key that you can use.
Note that if you have, for example, more than one environment you want to send SMS from, e.g., a development/testing server and a production server, you can implement two separate API accounts and have two separate API keys, if necessary.
General SMS information
The length of a standard SMS message is 160 characters from the GSM alphabet (as described here - SMS content and length). Longer SMS-es are possible by sending the message in separate parts, however, each of these parts will be charged as a standalone SMS.
When sending a multipart SMS, each part, however, is slightly shorter than the standard 160 symbols - a single part of a multipart SMS can be up to 153 symbols in length, i.e. a 160 symbol SMS can be sent as a single SMS, but a 170 symbol SMS will be sent as 2 messages, the first one 153 symbols in length, the second one - 17.
As the GSM alphabet contains only a small subset of all possible symbols, it is possible to send Unicode SMS messages including any characters that can be represented in the UCS-2 encoding, however, in doing this, note that maximum SMS length for a single part decreases to 70 symbols and a single part's length within a multipart SMS decreases to 67 symbols (each symbol takes up 2 bytes.)
Also, note that within the GSM alphabet, some symbols take up the place of two symbols, e.g., the euro sign €, square brackets [], etc.
In theory, it is possible to send a multipart SMS with up to 255 parts, however, due to compatibility issues between various carriers and phones, the SMS length is limited to max 7-part messages.
Alphanumeric sender IDs
When sending a message via Traffic, you can specify any number or text as the sender ID (i.e., what will appear in the recipient phone as the sender of the message.) It may be your phone number, your brand name, or any other text you can think of. There are some limitations, though:
Sender IDs must be previously requested from us - upon request, they will be added to your account and only then can you use them.
Sender IDs must be between 3 and 11 characters in length for an alphanumeric sender ID or 3-14 characters in length for numeric sender ID (phone number).
Only 0-9, a-z, A-Z, and underscode(_) characters are allowed in an alphanumeric sender ID by the GSM standard. It is technically possible to use other characters but it may result in various errors, e.g., messages not being shown to users, messages shown under other sender’s names, messages being delivered repeatedly, sender ID being shown incorrectly etc.
Take care not to choose a sender ID that might result in a valid phone number when sender ID is transposed into numbers (e.g., 2 = ABC, 3 = DEF, etc.) Many phones will do it if you try to call or reply to an alphanumeric sender ID.
General system information
Depending on the agreement between you and SIA "Sales.lv", your account may have either a monthly quota for post-paid accounts or an SMS volume quota for pre-paid accounts. The monthly quota is set in agreement with both parties and is intended for preventing accidental sending of a large number of SMS-es.
The volume quota for pre-paid accounts depends on the paid amount.
Receiving delivery reports
After messages have been sent out, you can receive the delivery reports via webhook.
API information
API address is https://traffic.sales.lv/API:0.15/
All requests should be made as HTTP POST requests with application/x-www-form-urlencoded media type.
Every request has these mandatory parameters (names are case-sensitive):
APIKey: API key allocated to you
Command: Name of the command
Other parameters depending on which command you are calling
The data returned from every command is serialized as JSON.
If there was an error with the request, you will receive an Error parameter with the relevant error code.
These error codes could be returned for any command:
InvalidAPIVersion: Address contains erroneous API version (the version according to this specification should be 0.12)
NoAPIKey: API key isn't specified or the APIKey parameter was empty
InvalidAPIKey: API key is invalid or doesn't exist
UnauthorizedIP: The request comes from an IP address that isn't authorized for use with this API key
CommandNotSpecified: Command isn't specified (Command parameter was empty)
CommandNotImplemented: The specified command doesn't exist or isn't available at this time
SystemError: Some other system error
This version of the API implements these commands:
SendOne: Sends a single SMS with the given parameters
SendMultiple: Sends multiple SMS messages with individually specified content for each recipient. (Can be used for sending single messages, as well.)
SendBatch: Creates a new SMS batch with the given parameters. Recipient numbers should be added afterwards with the AddBatchRecipients command.
AddBatchRecipients: Adds recipient numbers to an already created batch. Can be called multiple times GetSenders: returns a list with all available sender IDs (alphanumeric source IDs that show up as the sender of the SMS)
GetDelivery: Returns the delivery report for one or more messages by their ID numbers.
GetReport: Returns full data about one or more messages by their ID numbers.
Command description
SendOne
Sends a single SMS message with the given parameters.
Input parameters:
Number: Recipient number. You can put country code before the number but it shouldn’t have a 00 or + prefix (as for internation numbers).
Sender: Alphanumeric sender ID text, e.g. your brand name.
Content: SMS content encoded in UTF-8 (for standard and for Unicode messages both.)
(optional) SendTime: Time, when sending should be started, encoded as a Unix timestamp. If not specified, messages will be sent immediately.
(optional) CC: Default country code to use for numbers where it isn't contained in the number. Defaults to whatever is specified in your account settings. If the number will contain a country code, this will not be used for the specific recipient
(optional) Concatenated: 0/1 - if it's 0, but the content is too long for a single-part SMS, an error will be returned. If it's 1, the SMS will be sent as a concatenated (long) multipart SMS, if necessary. If omitted, it will be determined automatically. (Notice that a multipart SMS will be charged per each part, e.g., a 3 part SMS will be charged as 3 SMS-es.
(optional) Unicode: 0/1 - if this is 0, but the message contains non-GSM alphabet symbols, an error will be returned. If it's 1, the SMS will be sent as a Unicode SMS, if necessary. If omitted, it will be determined automatically.
(optional) Validity: Validity period (in minutes) of the SMS message, i.e., the time after which the mobile operator gives up and stops retrying delivery in case the phone number is valid but isn't immediately reachable. Defaults to 1440 (24 hours.)
The response will contain these parameters:
MSSID: Message ID that can be used for receiving delivery reports.
Length: Number of SMS parts
Unicode: Unicode indication (0 = message sent in GSM alphabet, 1 = message sent in UCS-2)
LongSMS: Multipart message indication (0 = single-part SMS, 1 = multipart message.)
Invalid: Reason why the message could have been erroneous
Network: Mobile network the number belongs to, more about it at the end of this document.
- or -
Error: Error code if there was any problem. If there wasn't any errors, this parameter will be omitted.
Possible errors:
InvalidNumber: Recipient number incorrect
InvalidSender: Sender ID doesn’t exist or isn’t available
NoContent: No content specified
InvalidCC: Incorrect or unsupported country code, if specified
ContentTooLong: Content is too long - either the content is just too long or, if Concatenated = 0, content is longer than a single SMS part.
ContentContainsInvalidCharacters: If Unicode=0 and message contains non-GMS alphabet characters, this error will be returned
MonthlyQuotaExceeded: Monthly quota for your account exceeded
SendMultiple
Sends multiple SMS messages in a single API call with individually specified content for each recipient. (Can be used for sending single messages, as well.)
Input parameters:
Sender: Alphanumeric sender ID text, e.g. your brand name.
Content: JSON array, where every element contains recipient number and message to be sent to that number. Message content should be in UTF-8 (for both standard and Unicode messages). For example:
[
[26480847, “Hello”],
[21234567, “Hello”],
[29876543, “Hello, world!”]
](optional) SendTime: Time, when sending should be started, encoded as a Unix timestamp. If not specified, messages will be sent immediately.
(optional) CC: Default country code to use for numbers where it isn't contained in the number. Defaults to whatever is specified in your account settings. If the number will contain a country code, this will not be used for the specific recipient
(optional) Concatenated: 0/1 - if it's 0, but the content is too long for a single-part SMS, an error will be returned. If it's 1, the SMS will be sent as a concatenated (long) multipart SMS, if necessary. If omitted, it will be determined automatically. (Notice that a multipart SMS will be charged per each part, e.g., a 3 part SMS will be charged as 3 SMS-es.
(optional) Unicode: 0/1 - if this is 0, but the message contains non-GSM alphabet symbols, an error will be returned. If it's 1, the SMS will be sent as a Unicode SMS, if necessary. If omitted, it will be determined automatically.
The response will contain an associative array having message IDs (MSSID) as keys and these fields in the values:
MSSID: SMS ID that can be used for receiving delivery reports
CC: Country code of number;
Phone: Phone number;
Content: Message content;
Unicode: Unicode indication (0 = GSM alphabet, 1 = UCS-2);
LongSMS: Multipart message indication (0 = single-part SMS, 1 = multipart SMS);
Invalid: Reason why message could have been erroneous. If the phone number or message is fine, this field will be empty.
Length: Length of message (number of message parts);
Network: Mobile network the number belongs to, more about it at the end of this document.
or
Error: Error code if there was a problem with the API call altogether.
Possible errors:
InvalidSender: Sender ID doesn't exist, is incorrect or is not available
InvalidContent: Content not specified or there was some other problem with message content.
InvalidCC: Incorrect or unsupported country code (if specified)
QuotaExceeded: Montly or volume quota exceeded.
SendBatch
creates a new SMS batch with the given parameters. Recipient numbers should be added afterwards with the AddBatchRecipients command.
Input parameters:
Sender: Alphanumeric Sender ID text.
Content: SMS content encoded in UTF-8
(optional) SendTime: Time, when sending should be started, encoded as a Unix timestamp. If not specified, SMS-es will be sent as soon as the recipient list is received.
(optional) CC: Default country code to use for numbers where it isn't contained in the number. Defaults to whatever is specified in your account settings. If the number will contain a country code, this code will not be used for the specific recipient and the code in the phone number takes precedence.
(optional) Concatenated: 0/1 - if it's 0, but the content is too long for a single-part SMS, an error will be returned. If it's 1, the SMS will be sent as a concatenated (long) multipart SMS, if necessary. If omitted, it will be determined automatically. (Notice that a multipart SMS will be charged per each part, e.g., a 3 part SMS will be charged as 3 SMS-es.
(optional) Unicode: 0/1 - if this is 0, but the message contains non-GSM alphabet symbols, an error will be returned. If it's 1, the SMS will be sent as a Unicode SMS, if necessary. If omitted, it will be determined automatically.
The response will contain these parameters:
BatchID: Batch ID, that must be used when adding recipient numbers to the batch with AddBatchRecipients.
Error: Error code, if there was a problem with the command in general. If there was no error, this parameter will be omitted.
Possible errors:
InvalidSender: This sender ID is erroneous, doesn't exist or isn't available
NoContent: SMS content wasn't specified (content was empty)
InvalidCC: Erroneous or unsupported country code
ContentTooLong: Content was too long - either the content is too long for a multipart SMS or, if the Concatenated parameter contained 0, it was too long for a single-part SMS
ContentContainsInvalidCharacters: If the Unicode parameter was 0 and message content has non-GSM alphabet characters, this error will be returned
QuotaExceeded: Quota was exceeded
AddBatchRecipients
Adds recipient numbers to an already created batch. Can be called multiple times GetSenders: returns a list with all available sender IDs (alphanumeric source IDs that show up as the sender of the SMS)
Input paramaters:
BatchID: Batch ID returned from SendBatch.
Recipients: JSON array with recipient numbers, e.g. "[3712987654321, 37129999999, ...]"
The response will contain these parameters:
MSSID: Associative array where the key will be the phone number and the value will be the SMS ID. In case if there was a problem with this specific recipient, the value will be an error code.
Error: Error code, if there was a problem with the command in general. If there was no error, this parameter will be omitted,
If any number is repeated several times in the recipient list, it will have only one entry in the MSSID list with a single SMS ID and the recipient will receive only one SMS.
Possible errors:
As MSSID values:
-1: Any other error;
-2: Incorrect number - doesn't conform to the number format for the
specific country;
-3: Incorrect number - number is technically correct but isn't registered to a mobile network or is registered to a network where SMS messaging is not possible. This currently works for a limited amount of countries. This error could be returned also if the number is registered but isn't a mobile phone number.
-4: quota exceeded
In the Error parameter:
InvalidBatchID: Batch ID doesn't exist or isn't available
InvalidRecipients: Recipient list cannot be parsed
QuotaExceeded: Quota exceeded. The error is returned only if the quota is already exceeded prior to this command. If quota is exceeded after sending SMS to a part of these recipients, every number over the quota will have the -4 error.
GetSenders
Retrieves a list of all sender IDs assigned to your account.
Input parameters: none
Response parameters:
Senders: An array containing all assigned sender IDs or empty array in case none are assigned.
GetDelivery
Returns the delivery report for one or more messages by their ID numbers
Input parameters:
MSSID: A single message ID or a JSON array with multiple message IDs.
Response contains
an associative array with message IDs as keys and values as delivery reports
or
Error: Error code if there was a problem with the API call altogether.
Possible errors:
InvalidMSSID: Erroneous or not specified message ID.
GetReport
Returns full data about one or more messages by their ID numbers
Input parameters:
MSSID: A single message ID or a JSON array with multiple message IDs.
Response contains an associative array with message IDs as keys and values containing:
ID: Message identifier;
CC: Country code for number;
Phone: Phone number;
Content: SMS content;
Unicode: Unicode indication (0 = GSM alphabet, 1 = UCS-2);
LongSMS: Multipart indicator (0 = single-part SMS, 1 = multipart SMS);
Length: Length of message (number of parts);
Status: SMS delivery status, one of the statuses described towards the end of the document;
SendTime: Time when message was sent;
DLRTime: Time when delivery report was received. (This is time when the report was received, not when the message was actually delivered or rejected.)
Validity: Validity period (in minutes) of the SMS message, i.e., the time after which the mobile operator gives up and stops retrying delivery in case the phone number is valid but isn't immediately reachable. Defaults to 1440 (24 hours.)
or:
Error: Error code if there was a problem with the API call altogether.
Possible errors:
InvalidMSSID: erroneous or not specified message ID.
Invalid numbers
Commands SendOne, SendMultiple, and AddBatchRecipients may return a parameter Invalid, that contains a reason why the number is not valid. These reasons could be:
Number: incorrect number format (e.g., Latvian number does not contain 8 digits);
CC: Number contains an invalid country code or country code is not supported at all. It also could indicate that sending to this country code is not permitted for your account.
MNP: Number doesn’t belong to any known mobile operator.
ContentLength: for messages where content is specified individually for each recipient, e.g., when sending with SendMultiple, the content for this particular number is too long.
Network: It is impossible to send the message to the network this number belongs to. E.g., if it isn’t a supported mobile operator or an operator that can actually accept SMS.
Such messages are not counted towards the account total and don't affect the account balance.
Mobile network codes
To indicate that a number belongs to a particular mobile network, message response contain an additional parameter Network that contains one of these codes:
In Latvia:
LMT: LMT
TELE2LV: Tele2 Latvia
BITELV: Bite Latvia
In Estonia:
TELE2EE: Tele2 Eesti
EMT: Telia Eesti, formerly EMT
ELISA: Elisa Eesti
In Lithuania:
TELE2LT: Tele2 Lietuva
OMNITEL: Telia Lietuva, formerly Omnitel
BITELT: Bite Lietuva
Additional network codes can be encountered and are subject to change in the future depending on network operator actions. However, these listed are the major operators in these and are not going to change.
Usage examples
Examples of API calls using various languages and technologies are provided in separate articles:
API calls using cURL
Updated on: 11/01/2023
Thank you!