Using HTTP API version 0.16 (current)

Changes since the previous version (0.15):

Simplified message sending by combining all send request methods into one unified method Send.
Send method can now be used to send personalized content to each recipient based on a common template.
Transliteration parameter added to Send to automatically attempt converting Unicode characters to closest GSM approximations.
Concatenated and Unicode parameters have been removed from the Send method as they had limited purpose (raising errors in certain conditions,) caused confusion implementing requests, and it would be impractical to implement in the unified Send method. If you relied on this functionality, be advised that from now on requests that would have been rejected because of these, will go through successfully.
MSSID parameter indicating a single message identifier in requests and responses has been renamed simply to ID.
InvalidCC error code has been renamed to InvalidCountryCode for clarity.
Expired status for undelivered messages added to delivery reports.
HMAC authentication used to sign delivery report webhook requests to ensure authenticity.

Non-breaking changes introduced after launch:

Support for link shortening in API message sending.
Added functionality to manage recipient blacklist and unsubscribe information.
Added a GetQuota method to retrieve account quota information.

Usage guide for the previous version (0.15) is available here.

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.
If you are using a telephone number as your sender ID, it must be specified in full international format with a preceeding plus (+) sign in API requests, e.g., "+37120000000".
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.16/
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:

SMS Sending
Send: Sends one or more SMS messages with the given parameters. Allows for different content to different recipients, and personalized content based on a template.
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.

SMS blacklist management
GetBlacklist: Returns blacklist contents
BlacklistAdd: Add a phone number to SMS blacklist
BlacklistDelete: Delete a phone number from SMS blacklist

Account information
GetSenders: Retrieves a list of all sender IDs available to your account.
GetQuota: Retrieves account quota information.

Command description

Send

Sends one or more SMS messages with the given parameters.

Input parameters:
Recipients: Recipient number as text or multiple numbers in a JSON array. You can put country code before the numbers but it shouldn’t have a 00 or + prefix to indicate international numbers. In addition, when passed as a JSON array, several methods of specifying message content are possible. Those are described below in Message content variations.
Sender: Alphanumeric sender ID text, e.g. your brand name, or a phone number in full international format (with leading + and country code).
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) 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.)
(optional) Transliteration: Attempt to transliterate Unicode characters into the closest approximation that fits in the GSM alphabet. Defaults to 0. More about transliteration.
(optional) TransliterationFallback: If transliteration is enabled (see the Tranliteration parameter,) this indicated the fallback character to use to replace Unicode characters that aren't recognized. Defaults to '' (empty text string, i.e. the unrecognized characters are simply removed.)
(optional) ShortenLinks: Enable link shortening in SMS messages (0 = disabled, default, 1 = enabled.) If the ShortenLinksOverride parameter is not filled, all website links will be automatically parsed from message text and replaced by the shortened version. Link shortening works only on content that's provided in the Content parameter but not on per-recipient personalized message content.
(optional) ShortenLinksOverride: A JSON array containing specific links in message content that need to be replaced by shortened versions. This can be useful in case you need to shorten just one of several links or you're using nonstandard notation in your links that may not work with automated parsing. (Our platform should handle all cases when links are formed properly and have all special characters URL-encoded. If you don't use URL-encoding for your links and want to rely on the user's browser handling them as is, you will need to use this parameter.)

The response will be a JSON array with an entry per each message sent and each entry will contain these parameters:
ID: Message ID that can be used for receiving delivery reports.
CC: Country code
Phone: Recipient phone number without country code
Content: Final message content that was sent to the phone. If link shortening was used and the message had any links that were shortened, this parameter will contain the final short versions of those links.
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.
Validity: Message validity time in minutes.
ShortenLinks: Indicates if link shortening was enabled (0 = disabled, 1 = enabled)

Alternatively, if there was a problem with the request, the response will be a JSON array with these parameters:
Error: Error code if there was any problem.

Possible errors:
InvalidRecipients: Incorrect recipient number (in case of a single number) or incorrectly assembled recipient array.
InvalidSender: Sender ID doesn’t exist or isn’t available
InvalidCountryCode: Incorrect or unsupported country code, if specified
ContentTooLong: Long SMS message has more than 7 content parts. (See SMS content and length.
QuotaExceeded: Account quota has been exceeded. You can retrieve the available quota amount with the GetQuota command.
InvalidShortenLink: An invalid website address was provided in the ShortenLinksOverride parameter.

Message content variations

With the unified Send method there are several variations in how message content can be passed in API requests.

The simplest: single message to one number

To send a simple message to a single number, you need only to populate the Content parameter with the necessary message content and Recipients with the recipient phone number as text.

Identical messages to multiple numbers

To send multiple identical messages to different numbers, you can populate Content with the desired content, and Recipients with a JSON array containing all recipient numbers, for example, ["37112345678", "37198765432"].

Note that the following personalized content options don't support the link shortening feature. If you require link shortening, only the content in Content will be handled to shorten these links. That may mean that you have to make multiple separate API calls per recipient.

Different message content to multiple numbers

To send multiple different messages in a single request, you will need to create a 2-dimensional JSON array for Recipients where each entry is an array containing a recipient number and their message content. For example, an array like this:

[
  ["37112345678", "Message one"],
  ["37198765432", "Message two"]
]

will send "Message one" to 37112345678 and "Message two" to 37198765432.
If an entry doesn't have any content specified, the text from the Content parameter will be used, otherwise, it will be overridden by the individual message in the entry.

Personalized message content to multiple numbers

This variation allows you to send personalized messages to multiple recipients in a single request based on a common template. For example, you could specify placeholders [Name] and {Time] in message text passed in Content like this: "Hello, [Name]! Your appointment is scheduled for [Time]." that would be populated from the Recipients array. Placeholder names must be enclosed in square brackets.

To set these values you would need to populate the array similarly to the previous variant but instead of using a text string as the second array element, you would put an associative array with keys corresponding to the placeholder names (without square brackets) and values containing the respective values to insert into message content. For this example with the Name and Time placeholders it would look like this:

[
  ["37112345678", {"Name":"Bill","Time":"9:50"}],
  ["37198765432", {"Name":"Tony","Time":"11:20"}]
]

Beware that if message template in Content has a placeholder but a recipient item doesn't have a corresponding key in their content array, the placeholder will remain visible in the final text.

Combined content types

All of the aforementioned approaches can be combined and used simultaneously, however, it is recommended not to, and it could lead to unexpected behavior. This section is intended more as an illustration of how the system would handle various content types to help you gain a deeper understanding of this process.

As an example we will reuse the content from the previous example: "Hello, [Name]! Your appointment is scheduled for [Time]."

With a Recipients array looking like this:

[
  ["37100001111", {"Name":"Bill","Time":"9:50"}],
  ["37100002222", {"Name":"Tony","Time":"11:20"}],
  ["37100003333", "Your appointment has been cancelled"],
  ["37100004444"],
  "37100005555", "37100006666"
]

The recipients will receive this content:

37100001111: Hello, Bill! Your appointment is scheduled for 9:50.
37100002222: Hello, Tony! Your appointment is scheduled for 11:20.
37100003333: Your appointment has been cancelled.
37100004444: Hello, [Name]! Your appointment is scheduled for [Time].
37100005555: Hello, [Name]! Your appointment is scheduled for [Time].
37100006666: Hello, [Name]! Your appointment is scheduled for [Time].

Message content transliteration

The Send command has an optional Transliteration parameter indicating if our API should attempt to replace Unicode characters to their closest GSM-alphabet approximation. For example, Ä becomes A, č becomes c, ñ becomes n, etc.

Note that transliteration is an automated process and unforeseen results may occur in some languages, for example, when a word radically changes its meaning depending on a diacritic being there or not.
By using the TransliterationFallback parameter you can control the behavior when unknown characters are encountered. By default they are removed from message content but you can specify something else, e.g. a question mark, to use for replacing such characters. It could also be helpful during integration testing to see if everything is working correctly.

Including unsubscribe data in message content

If you want to use our automated unsubscribe functionality to collect recipient unsubscribes, and not need to create your own unsubscribe management solution, you can use these placeholders in message content that will be populated with the respective values. These allow you to implement unsubscribing via a link, or via text message (or both).

[UNSUB-LINK]: Link to click to unsubscribe
[UNSUB-NUMBER]: Phone number that can be used to receive unsubscribe messages. This number will be populated either with one of our short codes or a long numbers depending on recipient's location.
[UNSUB-TEXT]: Text message that must be sent to unsubscribe via text message that will contain your sender ID.

Text case is not important and these placeholders can be set in lowercase as well.

For example, if your message is sent with a sender ID "BrandABC" and looks like this:

Hi, Customer, here's your exclusive offer code XYZ123. To unsubscribe please click here [unsub-link] or send "[unsub-text]" to [unsub-number].

it will be populated with the respective values and the recipient will receive a message looking similar to this:

Hi, Customer, here's your exclusive offer code XYZ123. To unsubscribe please click here https://example.com/u/1234 or send "STOP BrandABC" to 1838.

When unsubscribing with this method, the recipient unsubscribes from receiving messages from the specific sender ID. That allows you to use multiple sender IDs for separate purposes like marketing and transaction information, and not have one impacted by unsubscribing from the other. Further in this document you can also find information on managing unsubscribe lists via API.

Invalid numbers

The Send command may return a parameter Invalid, that contains a reason why the number is not valid. This reason 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 with custom content per recipient, the resulting final 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.

GetSenders

Retrieves a list of all sender IDs available to your account.

Input parameters: none

Response parameters:
Senders: An array containing all assigned sender IDs or empty array in case none are assigned.

GetQuota

Retrieves account quota information.

Input parameters: none

Response parameters:
Type: A string containing Monthly, Volume, or None respectively for a monthly quota that resets on first of month, volume quota that is simply a set number of messages you may send, or None for an unlimited account, however, except very special cases usually your account will have either a Monthly or a Volume quota just to be safe.
Total: The total message amount you have either per month, or in total.
Remaining: The remaining amount of messages you may send either in the current month, or in total.

If you have an unlimited account, both the Total and Remaining numbers will be 0.

GetDelivery

Returns the delivery report for one or more messages by their ID numbers

Input parameters:
ID: 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:
InvalidMessageID: Erroneous or not specified message ID.

GetReport

Returns full data about one or more messages by their ID numbers

Input parameters:
ID: 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:
InvalidMessageID: erroneous or not specified message ID.

Blacklist management

GetBlacklist

Returns the contents (phone numbers) of blacklist. Content is returned in pages with 10000 numbers each so you'll have to make several requests in case your blacklist is larger than that.

Input parameters:
Page: optional, integer page number.

Response contains
an associative array with these parameters:
- Page: result page number, it should be the same as the API call parameter if you specified a valid page number in the request
- PageCount: Total number of blacklist pages - you can use this in your request loop when you're retrieving the full blacklist
- Entries: an array of blacklist entries. Each entry is an array that contains parameters Number for the phone number and Time, which is the time when the number was added to the blacklist.
or
Error: Error code if there was a problem with the API call altogether.

Example response:

{
  "Page":0,
  "PageCount":1,
  "Entries":[
    {
      "Number":37100000000,
      "Time":"2023-09-12T15:07:47+00:00"
    }
  ]
}

Possible errors:
InvalidMessageID: Erroneous or not specified message ID.

BlacklistAdd

Adds a phone number to the blacklist

Input parameters:
Number: Phone number to add
Sender: Optional, alphanumeric sender ID to limit the blacklist entry to. If not present, the blacklist entry with this phone number will prevent sending messages with any of the sender IDs present in your account. If present, the specified phone number will not receive messages only from this sender ID but will continue to receive them from any other sender ID.

Response contains
an associative array with these parameters:
- OK: equals to 1 of request was successful
or
Error: Error code if there was a problem with the API call altogether.

Possible errors:
NoPhone: Phone number wasn't specified
InvalidPhone: Specified phone number was invalid
InvalidSender: Invalid sender ID specified (sender ID is not available for your account)
CannotAddToBlacklist: Number cannot be added to blacklist.

BlacklistDelete

Deletes the given phone number from the blacklist if it is present.

Input parameters:
Number: Phone number to delete
Sender: Optional, sender ID to limit this commad to. If given, only blacklist entries with the given phone/sender combo will be deleted, otherwise all blacklist entries with this phone number in your account will be deleted.

Response contains
an associative array with these parameters:
- OK: equals to 1 of request was successful
or
Error: Error code if there was a problem with the API call altogether.

Possible errors:
NoPhone: Phone number wasn't specified
InvalidPhone: Specified phone number was invalid
InvalidSender: Invalid sender ID specified (sender ID is not available for your account)

Unsubscribe management

GetUnsubscribes

Returns the list of unsubscribe entres. Content is returned in pages with 10000 numbers each so you'll have to make several requests in case your blacklist is larger than that.

Input parameters:
Page: optional, integer page number.

Response contains
an associative array with these parameters:
- Page: result page number, it should be the same as the API call parameter if you specified a valid page number in the request
- PageCount: Total number of blacklist pages - you can use this in your request loop when you're retrieving the full blacklist
- Entries: an array of blacklist entries. Each entry is an array that contains these parameters:
• Number: for the phone number;
• Time: timestamp when the number was added to the blacklist;
Sender: the sender ID the user unsubscribed from
• Source: how the unsubscribe was registered. At the moment it is SMS for unsubscribe via SMS message, Web for unsubscribe via clicking a link in the message, or API for unsubscribe entries that were added from 3rd party systems via API.
or
Error: Error code if there was a problem with the API call altogether.

Example response:

{
  "Page":0,
  "PageCount":1,
  "Entries":[
    {
      "Number":37100000000,
      "Time":"2023-09-12T15:07:47+00:00",
      "Sender":"ALPHA",
      "Source":"API"
    }
  ]
}

Possible errors:

UnsubscribeAdd

Adds a phone number to the blacklist

Input parameters:
Number: Phone number to add
Sender: Alphanumeric sender ID to unsubscribe from. Unlike with the blacklist entries, this is not optional. The specified phone number will not receive messages only from this sender ID but will continue to receive them from any other sender ID.

Response contains
an associative array with these parameters:
- OK: equals to 1 of request was successful
or
Error: Error code if there was a problem with the API call altogether.

Possible errors:
NoPhone: Phone number wasn't specified
InvalidPhone: Specified phone number was invalid
InvalidSender: Invalid sender ID specified (sender ID is not available for your account)
CannotAddToUnsubscribes: Number cannot be added to blacklist.

UnsubscribeDelete

Deletes unsubscribe entries with the given phone number and sender ID from your account. However, there is a limitation in that only unsubscribe entries with Source=API (entries added through this same API) can be deleted. In case it is required to discard unsubscribe data submitted from users, these entries can be deleted manually in the web interface.

Input parameters:
Number: Phone number
Sender: Sender ID

Response contains
an associative array with these parameters:
- OK: equals to 1 of request was successful
or
Error: Error code if there was a problem with the API call altogether.

Possible errors:
NoPhone: Phone number wasn't specified
InvalidPhone: Specified phone number was invalid
InvalidSender: Invalid sender ID specified (sender ID is not available for your account)
UnsubscribeEntryNotFound: Given number/sender combo wasn't found in the unsubscribe list.

Usage examples

Examples of API calls using various languages and technologies are provided in separate articles:
API calls using cURL

Updated on: 27/06/2024

Was this article helpful?

Thank you!