| Help Center Go to tyntec.com Log in Breadcrumb SMS Send SMS & OTP SMS SMS API | Send SMS & OTP SMS 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. Step One: Set headers Step Two: Send a simple message Step Three: Check the delivery report (DLR) Step Four: Fine tune your request To send SMS messages, you make HTTP requests to the tyntec’s SMS API. Endpoints Endpoint URL Purpose Reference https://api.tyntec.com/messaging/v1/sms sending messages Send SMS https://api.tyntec.com/messaging/v1/messages polling for delivery reports Message Status Step One: Set headers 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: Content-Type: application/json Accept: application/json apikey: YOUR_API_KEY Step Two: Send a simple message 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: POST https://api.tyntec.com/messaging/v1/sms { "from": "mybiz", "to": "+123456789", "message": "Hello world!" } The initial response is synchronous and is of the schema RestMessageResponse. It tells you whether your submission was accepted or not: { "requestId": "57d2a198-cbdf-478c-8da0-c164b4ce5ac5", "status": "ACCEPTED", "submitDate": "2020-05-11T11:46:41+00:00", "href": "https://api.tyntec.com/messaging/v1/messages/57d2a198-cbdf-478c-8da0-c164b4ce5ac5", "from": "mybiz", "to": "+123456789", "parts": [ { "partId": "373900-1589197601244+123456789", "submitDate": "2020-05-11T11:46:41+00:00" } ], "size": 1 } But it doesn’t say anything about the delivery of your message yet, right? Step Three: Check the delivery report (DLR) 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: { "requestId": "baceb729-ddc9-4b7f-834f-f0cc29121069", "status": "DELIVERED", "submitDate": "2020-05-11T11:52:19+00:00", "doneDate": "2020-05-11T11:52:23+00:00", "href": "https://api.tyntec.com/messaging/v1/messages/baceb729-ddc9-4b7f-834f-f0cc29121069", "from": "mybiz", "to": "+123456789", "ttid": "51", "mccmnc": "23001", "parts": [ { "deliveryState": "DELIVERED", "statusText": "00480065006c006c006f", "partId": "373900-1589197938567+123456789", "submitDate": "2020-05-11T11:52:19+00:00", "doneDate": "2020-05-11T11:52:23+00:00", "errorCode": "0000" } ], "size": 1 } 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: { "to": "+123456789", "from": "mybiz", "message": "Hello world!", "callbackUrl": "https://YOUR_SERVER/messages", "callbackMethod": "POST" } 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: GET https://api.tyntec.com/messaging/v1/messages/baceb729-ddc9-4b7f-834f-f0cc29121069 A response to this query is of the schema RestMessageResponse (the same schema as a webhook report, see the example above). Step Four: Fine tune your request 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. { "to": "+123456789", "from": "mybiz", "message": "Your code is 123456. It will expire after 5 minutes.", "validity": "5" } 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: Character set Singlepart SMS Multipart SMS GSM-7 160 characters 153 characters UCS-2 (Unicode) 70 characters 67 characters 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: 'trate': 0.4 … 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: 'mrate': 0.1 … 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: 'sendDateTime': '2120-05-03T09:30:00' 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. Doc Center Introduction WhatsApp Business Support Inbox SMS Overview Quick Start Send SMS & OTP SMS API Reference Use Cases Features GSM Error Codes Pricing & Coverage Other Protocols Integrations FAQs Viber Business Voice Phone Verification Authentication ICMS Interactive Text Pricing & Coverage My tyntec Tutorials Integrations FAQs PRODUCTS SMS OTP SMS Support Inbox Engagement Platform Conversations WhatsApp Business Viber Business RCS WeChat Google Business Messages Telegram Phone Verification Authentication | 2FA 2FA Smart Contracts Voice RESOURCES Documentation Docs | SMS Docs | Support Inbox Docs | WhatsApp Docs | Viber Business Docs | Portability Check Docs | Authentication API Reference Developers Integrations Tutorials My tyntec Sign Up Webinars FAQs Support Pricing Pricing Calculator CASES Success Stories Automotive Education Fashion Financial Services Food & Beverage Healthcare Insurances Logistics Retail & eCommerce Real Estate Travel & Hospitality Telecom Operators PARTNERS Find a Partner Become a Partner Operator Partnerships COMPANY About tyntec Management & Board Newsroom Presse (German Press) Careers Events tyntec Offices Contact Sales REACH US +49 231 477 90 090 +14155237745 +6531581252 sales@tyntec.com +49 89 202451100 Terms and Conditions Support and Service Level Agreements Acceptable Use Policy Data Privacy Statement Disclaimer GDPR Compliance Imprint © 2021 tyntec. All rights reserved