Hi there!

So you have set up the SMS service in your Business Center and you are going to implement sending SMS messages in your app. This article will give you basic guidelines on how to do it with the REST API.

To send SMS messages, you make HTTP requests to the tyntec’s SMS API.

Authorize your API calls by adding the HTTP header apikey with your API key that you’ve got from your Business Center.

Important: You use a trial API key for testing and a different API key when you go live!

The REST API accepts data in the JSON format (Content-Type: application/json) and responds with JSON data as well (Accept: application/json). Setting these headers is optional, however, you need to set them if your HTTP client has other defaults.

The complete headers look like this:

To send a simple SMS, you provide the sender ID (from), a recipient number (to) and the content of the message (message)… and that’s it!

Note: In some countries, a sender ID must be registered first, if you want to use a custom alphanumeric ID (such as your brand name) instead of your business phone number. If you would like to use a custom ID, ask us via a ticket to check this for you.

The simplest request with only required parameters looks as follows:

The initial response is synchronous and is of the schema RestMessageResponse. It tells you whether your submission was accepted or not:

But it doesn’t say anything about the delivery of your message yet, right?

You can find out about the delivery status of sent messages in two ways: you can either poll the REST API for it, or you can get notified with a callback on your webhook (preferred).

On your webhook

Assuming you’ve subscribed your webhook in your Business Center, you can make your app ready to handle delivery reports.

Tip: You may use our webhook-starter to get started in Node.js!

Reports are also of the schema RestMessageResponse and they look like this:

Note: The example above is of a trial period. When you go live, the report will also contain the pricing members price, priceEffective and currency.

Important: Your app should verify that the callback request is authorized by checking the HTTP headers (you can define them when you subscribe your webhook in the Business Center).

Alternatively to subscription in your Business Center, you may provide a callback URL and a callback HTTP method in your requests (handy in case you need to use various webhooks during testing).

Such request might look like this:

By polling

Can’t you set up a webhook for callbacks? Or you don’t want to?

Then you may poll the Message Status endpoint for the delivery report using the requestId of a sent message. To avoid recomposition of the URL, use the value of the href member of the initial response right away.

A polling query looks like this:

A response to this query is of the schema RestMessageResponse (the same schema as a webhook report, see the example above).

Let’s have a look at several optional parameters, which you can use to fine tune your requests.

Tip: Also check out the complete set of SMS parameters in our API reference.

OTP & time-critical messages

OTP messages are handy when you need user verification to add an extra layer of security, such as verification of the ownership of a phone number, transaction authorization or One-Time Password delivery.

In such cases we recommend to restrict the validity period to minutes.

This says: If the message can’t be delivered in 5 minutes, give up, because later delivery attempts are not safe or don’t make sense.

Multipart messages

When you send a message that is too long, it gets automatically split into several parts that are transferred (and billed) as individual messages. The character count for the split depends on the character set that is used to transfer the message:

This says: If you’re sending a message in Unicode which is 71 characters long, it is split into two parts, where the first part has 67 characters and the second part has 4 characters.

You may forbid sending messages that would have far too many parts by setting the partLimit parameter. If the message would be split into more parts than you allow, the request will result in a 400 error instead of sending the message.

And how about having fewer parts with smart encoding?

Smart encoding

You always input your message text in UTF-8. When the text contains characters, which aren’t in the GSM-7 character set, Unicode is used automatically. But this means that the messages can be shorter and potentially may have more parts!

This is where the tyntec’s smart transcoding feature comes in: the service can compress your message by replacing extra Unicode characters with characters available in GSM-7.

You allow the service to do this by saying what percentage of the original text the service may modify (if it helps), and what kind of replacement should be used:

• Transcoding rate – replace extra characters with equivalents (like “ü” → “u”), suitable for replacement of accented characters, for example:

… says: 40 % of the text may be modified by replacing extra characters with equivalents, if and only if it will result in fewer parts, otherwise go with the original in Unicode.

• Miss rate – replace extra characters with periods (“.”), suitable for punctuation replacement, for example:

… says: 10 % of the text may be modified by replacing extra characters with periods, if and only if it will result in fewer parts, otherwise go with the original in Unicode.

Note: Keep the default encoding setting (AUTO) to have this feature enabled.

Additionally, you can tell the transcoder whether it may uppercase the text (upperCased). Some scripts (like Greek) may not have lowercase equivalents in GSM-7, but they may have uppercase equivalents.

Message scheduling

Need to plan the time for sending SMS ahead for your marketing campaign? No problem!

Just tell the API when in the future your message shall be sent:

Note: Remember that the server is on the UTC time! You may, of course, add a time zone.

Ooops… trouble?

If you run into problems with delivery, note the requestId (and partIds for multipart messages) of the messages in question and mention the id(s) to our support team, when you open a ticket. It is usually a good idea to retest, whether a problem occurs on more phone numbers, and to give our support team several samples with various phone numbers.