Question 1

Meaning of SMS delivery reports

Accepted Answer

When sending SMS messages, we show and overview of message delivery status displaying the number of messages delivered successfully, undelivered or buffered (not yet delivered). This article is an attempt to clarify the meaning of these status reports.

Delivered

These are messages that were passed on to the operator and were successfully delivered to recipients' phones. This status report actually indicates message receipt on the subscriber's phone, with some exceptions like the United States, Canada and some other countries where it indicates successful delivery to the mobile operator. In Europe, Asia, Africa, South America it is the actual receipt on the phone, though.

If this delivery report has been received but the user claims not having gotten the message, it is overwhelmingly likely that the issue is on the phone-side: blocked sender, disabled notifications, or even phone software glitches.

Buffered

This is an intermediate status that appears when the message has been sent but we haven't yet received a final delivery status. This status can be displayed for quite a long time in situations when the mobile operator cannot immediately reach the recipient and attempts message delivery at a later time until the message expires. Some of the common reasons are:

Phone switched off;
Phone outside network range;
Full memory, although that is a rarer issue in modern smartphone age;
Prepaid card balance empty

In all these cases the message delivery has

Question 2

Using HTTP API version 0.16 (current)

Accepted Answer

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 func

Question 3

Using HTTP API version 0.15

Accepted Answer

|| 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.

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, bu

Question 4

Usage examples: cURL

Accepted Answer

Here are some example API calls using cURL. These examples use the current API version (0.15), but legacy versions are similar enough that there should only be minor differences for supported commands.

cURL --data* parameters automatically set the Content-Type header to the required application/x-www-form-urlencoded so that is omitted from the examples. It could be set with the -H parameter, if necessary.

SendOne

Sends a single SMS message per API call.

Request:

curl -X POST https://traffic.sales.lv/API:0.15/ \ --data-urlencode "APIKey=YOURAPIKEY" \ --data-urlencode "Command=SendOne" \ --data-urlencode "Number=37199999999" \ --data-urlencode "Sender=YOURNAME" \ --data-urlencode "Content=Hello there"

Successful response:

  "MSSID":"123456789012",
  "CC":"371",
  "Phone":"99999999",
  "Length":"1",
  "Unicode":"0",
  "LongSMS":"0",
  "Invalid":false,
  "Network":"LMTLV",
  "Validity":1440
}```
##### Unsuccessful response:

{ "Error":"InvalidNumber" }```

SendMultiple

Sends multiple SMS messages in a single API call/

Request:

curl -X POST https://traffic.sales.lv/API:0.15/ \ --data-urlencode "APIKey=YOURAPIKEY" \ --data-urlencode "Command=SendMultiple" \ --data-urlencode "Sender=YOURNAME" \ --data-urlencode "Content=[[\"+37112341234\"\,"Lorem ipsum dolor sit amet\"],[\"+37198769876","consectetur adipscing elit.\"]]\"

Successful response:

```{ "37112341234"

Question 5

Receiving message delivery reports via webhook

Accepted Answer

You can specify an HTTP(S) address in your account settings for a webhook that will be called from our side whenever a new delivery report comes in for a message sent through your API account.

|| You may want to whitelist our addresses in order to be able receive these requests, depending on how tightly your firewall is locked down. The address you specified for your will receive HTTP POST requests with these parameters:

MSSID: SMS ID, received from SendOne, SendMultiple, or AddBatchRecipients commands.
DLR: Delivery report, one of these values:
Delivered: SMS was delivered successfully.
Sent: SMS was sent but it is not yet known if it was delivered.
Buffered: SMS has been passed on but is still waiting for delivery (or delivery report is not yet received.)
Undelivered: Not possible to deliver the message
Error: Error of our system or the operator.
Other: Other unknown delivery report. Error and Other reports shouldn’t normally occur at all.
Expired (0/1): If the message wasn't delivered (Undelivered status report,) indicates if it was because the message expired (the recipient phone number is valid but wasn't rechable during message validity period.)
HMAC: Authentication code for report verification

Detailed description about the meaning specific delivery reports can be found here: Meaning of SMS delivery reports

Question 6

SMS content and length

Accepted Answer

How long can an SMS message be?

It depends on message content. If the message contains only characters specified in the so-called GSM alphabet - Latin uppercase and lowercase letters, numbers common punctuation and some diacritics, an SMS message can have up to 160 characters (several characters like the euro symbol €, square and curly brackets - [ ] { }, tilde ~, backslash \, caret ^ and vertical bar | take up two spots so each use of these characters will decrease the remaining characters by 2.

This is usually enough for messages in languages like English or even Finnish where the additional diacritics are still covered by the GSM alphabet.

If, and as often is the case, these characters are not enough, Unicode encoding is employed which allows use of almost any character at the expense of decreasing the possible message length to 70 characters.

What about longer messages?

Indeed, longer messages are possible and are often used. This is done with so-called long or concatenated SMS messages which, behind the scenes, are simply several ordinary messages with indication of how the phone should assemble them to appear seamlessly to the user as one long message. However, accommodating this indicator has some impact on message length: the length for each part in a GSM alphabes message is just 153 characters as apposed to 160, and in.

Frequently Read Articles

Browse All Categories