Tags: API, English

SMS API Essentials – Developer Guide #01

3 November, 2020
Reading time: 9 min 19 sec

Are you starting to work with SMSAPI API? Please read the first part of the developer guide and let us walk you through five simple steps towards your first SMS sent via API. All explained by our Product Manager – Jakub Kluz.

Our brand name, SMSAPI, carries a long history, as it’s 13-years old. Funny thing is, it was coined by our founders, who were developers themselves. They wanted to emphasize, that the platform they were creating was designed especially for IT people.

Fast forward to today: next to our exceptionally stable, reliable API, we have also a web-based version. Its iconic blue colour is a trademark of our brand. The Customer Portal is used by people not proficient in programming every day. Most of them are not even aware of the meaning of the second part of our name – they just want to send bulk SMS.

Still, our API is constantly upgraded, moderinized and expanded. It’s a cornerstone of many of our internal products. More importantly, it’s actively used by our clients like iQueue, Insly and ProTrainUp. We want to help companies that need an effective, quick and reliable communication solution to start using API.

I’m fully aware that the decision “Let’s pick SMSAPI and their API to send text messages” was probably made by some other department (if your company has such structure) or even more spontaneously (“whoa, this API looks good and has a neat documentation”). After all, the developer will have to fire up his or her IDE (or Emcsa via Sendmail), make coffee and dig through it all.

This series is meant for all struggling with the first steps. I’ll show you how to use our API. Let me start by pinpointing the most essential and basic things you have to do to: send your first SMS via API.

Step 1: Create and verify a SMSAPI account

Needless to say, it’s a first and most crucial step to start your work – creating an account. Watch a quick screencast to see how to do it quickly.

Registration and verification of an SMSAPI account

Of course, if you already have an account to work on, you can skip forward or just create a sub-user for yourself. Don’t forget to charge it, to have some points for testing.

Step 2: Add SMS sender name

An example of a message with SMS sender name
An SMS with sender name (SMS branding)

SMS sender name is a text shown as a text sender on the recipient’s phone. It looks like on the picture to the right.

It’s sometimes called SMS branding or branded SMS. Nevertheless, it can have up to 11 characters, and it should represent the brand that sent the message. So pick a name that will be easily recognizable as a part of your company’s communication.

By default, all messages sent from a new SMSAPI account are branded as “Test”, and for tests, it’s completely sufficient. But if you’d like to work with your own name, you have to complete the registration and activation process. You can do it SMSAPI Customer Portal, and it’s quite easy. Watch the how-to video below.

How to add a sender name to text message?

Step 3: Decide if you are going to use a library or API

It’s the first important choice that you must make. On the one hand, there are Libraries created by SMSAPI. They are available in a few popular languages, and all can be downloaded from GitHub.

SMSAPI Libraries on GitHub

  • PHP
  • C#
  • Bash
  • Python
  • JavaScript
  • Java
  • Go
  • On the other, you can connect directly with an API, without any library. The process has been thoroughly described with some examples in our Documentation in the form of OpenAPI using the popular Swagger tool.

    The choice is entirely up to you, your preferences and goals. All libraries will allow you to send text messages, some of them to work with our contacts database. At the same time, not all of them support the virtual mobile numbers (special numbers that allow you to receive messages from your customers), but we’ll get into it in one of the next episodes.

    If you are looking for quick and easy integration, we recommend using one of the ready-made libraries, assuming you are developing in one of the available languages. It’d make your work easier and faster.

    But! If you’re planning on doing something more advanced, than tools provided by a library allow, or if you prefer not using Fluent API (by the example of JS library), and would like to have greater control over the integration, you should know that connecting with an API directly is an equally viable choice.

    Step 4: Generate authorization key

    It’s an another action that requires you to login to Customer Portal. Go to the section shown below.

    Manage your API tokens in Customer Portal
    Manage API tokens (OAuth) in the SMSAPI Customer Portal

    Next, click the “Generate access token” button. A window will be displayed, where you can limit the token’s access to fit your needs. Having data access minimalization and security in mind, selecting text messaging (SMS) will be enough – you can toggle off the rest.

    When finished click „Generate token”, then you’ll see a new pop-up with your freshly generated token.

    Newly generated token in SMSAPI Customer Portal

    Attention!

    Due to the security matters, we will never show you your complete token ever again. So, it’s best to paste it in the code right away (or even better directly into the configuration). If you close the pop-up before copying it, you’ll have to generate a new token.

    Step 5: Test API request

    All that’s left is to actually send your first text messag via SMSAPI’s API! To do it, use the code below. In case of any problems, our Documentation is there to help you.

    <?php
    
    /** URL address of SMSAPI API, @see https://www.smsapi.com/docs/#url-adresses */
    
    $smsApiUrl = 'https://api.smsapi.com';
    
    /** OAuth autorization token, @see https://ssl.smsapi.com/react/oauth/manage */
    
    $smsApiToken = 'token_oauth';
    
    /** sender name, @see https://ssl.smsapi.com/sms_settings/sendernames */
    
    $from = 'test';
    
    /** recipient list, separated by comma */
    
    $to = 'XXXXXXXXX';
    
    /** message body */
    
    $message = 'Hello world!';
    
    /** answer format */
    
    $format = 'json';
    
    $httpClient = curl_init();
    
    curl_setopt($httpClient, CURLOPT_URL, $smsApiUrl . '/sms.do');
    
    curl_setopt($httpClient, CURLOPT_POST, true);
    
    curl_setopt($httpClient, CURLOPT_POSTFIELDS, [
    
        'to' => $to,
    
        'from' => $from,
    
        'message' => $message,
    
        'format' => $format,
    
    ]);
    
    curl_setopt($httpClient, CURLOPT_RETURNTRANSFER, true);
    
    curl_setopt($httpClient, CURLOPT_HTTPHEADER, [
    
        'Authorization: Bearer ' . $smsApiToken
    
    ]);
    
    $apiResponse = curl_exec($httpClient);
    
    curl_close($httpClient);
    
    echo $apiResponse . PHP_EOL;
    
    ?>
    

    This is a code that will send your first message to the selected recipient numbers. It’s probably best to change the number to yours to actually receive the text. 🙂 Do it in the $to variable. Oh, and you need to paste your OAuth token in the $smsApiToken variable.

    You need to pay extra attention to the recipient number in the $to variable. It must be preceded with a country code just like “44123456789″ – “44” is a country code, and “123456789” is a sample phone number. We are an international company, so we need the code to know, which country is the message supposed to reach.

    All that’s left is running the code in the PHP interpreter. Do it by saving the code as a testSms.php file on your computer with a PHP interpreter present. All versions >= 5.4 should run the script just fine with the command (you might need to adjust the command to your specific environment if you don’t have PHP in your $PATH or your PHP executable is named differently):

    php testSms.php

    If everything went smoothly you should get success notification in JSON format looking like this one:

    {"count":1,"list":[{"id":"566275XXXXX","points":0.14,"number":"48XXXXXXXXX","date_sent":1603356627,"submitted_number":"XXXXXXXXX","status":"QUEUE","error":null,"idx":null,"parts":1}]}

    And after a while, you should receive the SMS on your phone!

    Most common errors

    What if the test was not concluded with a success? The API will provide you with an error code which will help you to identify the reason for failure. All errors or explained in the Documentation. The most common are:

    • Error 101, Invalid authorization info – invalid token or server connection data, e.g. to api.com.pl instead to api.smsapi.com;
    • Error 14, Wrong sender name – wrong or inactive SMS sender name; check sender names in the Customer Portal;
    • Error 11, The message is too long, or there is no message or parameter: nounicode is set, and special characters (including Polish characters) are used – you are trying to send a message longer than your limit set in the account configuration – remember that message with characters outside of Unicode has a lower character limit, as usual, more information can be found in the Documentation;
    • Error 13, Lack of valid phone numbers (invalid or blacklisted numbers) – delivery failed due to the inactive or blocked numbers; check whether the entered numbers are valid and if there are no extra characters;
    • Error 103, Insufficient credits on your account – not enough points on the account or subaccount;

    There a couple of errors that are not shown by SMSAPI error notification (and they won’t be present in logs). It is due to the fact that they occurred before the connection with the API of SMSAPI could be established. The most common are:

    • Connection to a wrong addresscorrect address can be found in our Documentation, but you’ll probably want to use https://api.smsapi.com/,
    • Connection using TLS protocol version lower than 1.2 – we do not support older versions of TLS protocol, because they are depreciated as not secure enough. You have to check the TLS version of your system (environment) and probably update your entire environment or its part,
    • Connection blocked by a firewall at the client’s side – it means that connection had been blocked somewhere in between your machine and our API; you have to check your system or talk to the network administrator. The problems rarely occur on developers’ computers (if so, you wouldn’t even be able to read this article!), but it’s a possible scenario in isolated networks operating in server centres. Whitelisting IPs of SMSAPI servers should solve the problem.

    There’s one more thing that can prevent you from getting that SMS on your phone. Some sender names are blocked in certain countries. Unfortunately, our default sender name “Test” is also blocked in some regions, like the UK.

    Many local restrictions (imposed by a country or even a carrier!) regulate sender name management. That it is why we need to work case-by-case, usually fill some paperwork if we want to use some brand-specific sender names. So if you struggle with receiving SMS despite API giving you success message, contact our support specialist for more info and assistance.

    What’s next? Our SMSAPI API has a lot of applications. You can manage contacts store on your SMSAPI account, add parameters to bodies of messages or alter account settings. Moreover, it allows you to use the callback feature required when receiving messages from your customers. So, stay tuned, I’ll explain everything step-by-step in the upcoming episodes!

    Photo by Timothy Dykes on Unsplash