Introduction

Wavecell offers different API methods that allow you to send SMS programmatically.
In this tutorial, we are going to cover the simplest method: Send SMS (Single)
It is used to send SMS one by one.
We also offer bulk methods that allow sending multiple SMS in one command - for more information, check the following methods in the documentation: Send SMS (Batch) and Send SMS batch (Compact)

If you follow the different steps of this tutorial, you will get to send an SMS directly from your command line utility using a simple curl command.

Index

  • Learn how to use the method for sending single SMS
  • Prerequisites
  • Account and credentials
  • Signing-up
  • Finding your apiKey bearer token (for API authentication)
  • Identifying your Wavecell Subaccountid
  • API request
  • Preparing the URL
  • Preparing the authentication
  • Preparing the data payload
  • Putting it together and posting the curl request
  • Going further
  • API response
  • API errors

Tutorial: Learn how to use the method for sending single SMS

In this tutorial, we are going to send the text “Hello, World!” to the mobile phone number 12345678 registered on a Singaporean network (+65) using curl. For this, we are going to use a Wavecell account created with our email amazing@developer.com . We are going to use our subaccountid amazing_hq. The apiKey for our account is OiLc1xKaghw3sD1piU6sZHYwSuFK3uWtLQn4WjvOww.

Prerequisites

  • Command line interface compatible with CURL
  • Wavecell account
  • apiKey (Bearer token)
  • Wavecell subaccountid
  • Destination phone number
  • SMS Body

Account and credentials

You will need to sign-up to use the API. The following steps will guide you through this process and highlight the information to keep aside.

I. Signing-up

  1. Head to https://www.wavecell.com
  2. Click on SIGN UP.
  3. Enter your email and follow the instructions to define your password and finalize your account (by default, API password and account password are the same, you can modify this from your account settings)
  4. Confirm your email address by clicking on the validation link you received in the activation email to activate your account.

Sign up

II. Finding your apiKey bearer token (for API authentication)

  1. Head to https://app.wavecell.com .
  2. Click on LOG IN.
  3. Enter your email address and password to get access to your account dashboard.
  4. Head over to the configuration > API keys section
  5. Create an API key if empty and then keep the API Key value, here: OiLc1xKaghw3sD1piU6sZHYwSuFK3uWtLQn4WjvOww

apiKey

III. Identifying your Wavecell Subaccountid

  1. Head over to the pricing section and use the subaccountid list to retrieve the subaccountid that you want to use
  2. By default, your account comes with only one subaccountid for your high-quality service. It is designated by your accountid and the suffix _hq.
  3. Note down this value, you will need it later.
  4. In that example, the subaccountid is amazing_hq

subaccountid


API Request

The Wavecell SMS single method expects requests sent by developers to respect a specific format.
In the following parts, we are going to go over the different elements of the request:

  • the URL format
  • the authentication
  • the data payload.

At the end of the section, we will generate a curl command to send an SMS directly from the command line.

I. Preparing the request URL

Remarks
  • We are going to send a POST request to the Wavecell API single URL endpoint.
  • As detailed in the documentation, the URL is defined by the following pattern: https://api.wavecell.com/sms/v1/{subAccountId}/single
Tutorial URL
  • In order to create the URL to use, we are going to replace {subaccountid} in the pattern above by amazing_hq, the subaccountid that we are using in this tutorial
  • In that example, the URL that we are going to send the request to is: https://api.wavecell.com/sms/v1/amazing_hq/single
curl
  • In curl, we will have to indicate that we want to do a POST request to this URL by using the following command:
curl -X "POST" https://api.wavecell.com/sms/v1/amazing_hq/single

II. Preparing the request authentication

Remarks

  • As explained in the docs, the API authentication uses an apiKey bearer token method.

Tutorial authentication

  • In this tutorial, the apiKey for our account is OiLc1xKaghw3sD1piU6sZHYwSuFK3uWtLQn4WjvOww .

curl

  • In a curl request, bearer tokens must be passed as a header like so: -H "Authorization: Bearer {token}"
  • We just have to replace our {token} placeholder by our apiKey
  • The authorization header will then look like that: -H "Authorization: Bearer OiLc1xKaghw3sD1piU6sZHYwSuFK3uWtLQn4WjvOww"

III. Preparing the request data payload

  • The API expects to receive a structured request containing the SMS data in a specific format.
  • As detailed in the documentation, the data that we have to submit should be a JSON object structured as follow:

Wavecell_API_Reference_Google_Chrome_Today_at_12_26_54_PM

Tutorial request data payload

  • The API expects to receive a structured request containing the SMS details and parameters. The format of the request is JSON and it can accept both optional and required parameters.
  • For simplicity sake, we are going to use only the most important of the parameters (the others are detailed in the documentation):
    • Source:
      • this parameter defines the SMS senderID, let’s use "AmazingDev" 😎
    • Destination:
      • this is the phone number that we want to reach. As mentioned in the introduction, we want to send a message to 12345678 and it is a phone number registered in Singapore, which uses the international prefix +65.
      • For the destination parameter, we are going to use the value "+6512345678"
    • Text:
      • This is the content of the message.
      • For the sake of tradition, let’s us the value: “Hello, World!”
    • Encoding:
      • This parameter tells the destination handset which encoding to use to display the SMS. Our text only contains GSM7bit characters which is the most standard encoding but for the sake of safety let’s use "AUTO"
        • it means that Wavecell API will automatically detect the characters used in the text and select the best encoding.
        • It allows preventing the message to show up as “ ⃞ ⃞ ⃞ ⃞, ⃞ ⃞ ⃞ ⃞” in the case where we would have used special characters or another alphabet.

Our final JSON object that we are going to send as the request data payload is then:

{
  "source": "AmazingDev",
  "destination": "+6512345678",
  "text": "Hello, World!",
  "encoding": "AUTO"
}

curl

  • In curl, we will transmit the JSON data inline and indicate that the data payload is in JSON format using the following commands:
-H "Content-Type: application/json" 
-d $'{ 
  "source": "AmazingDev", 
  "destination": "+6512345678", 
  "text": "Hello, World!", 
  "encoding": "AUTO" 
}'

IV. Putting it together and posting the curl request

  • If we wrap up all the elements prepared in the steps above, we should put together the 3 elements of our request: URL + Authentication + Data Payload
  • To send the API request to Wavecell API single endpoint with our message we should use the following command in our command line utility:
curl -X "POST" https://api.wavecell.com/sms/v1/amazing_hq/single -H "Authorization: Bearer OiLc1xKaghw3sD1piU6sZHYwSuFK3uWtLQn4WjvOww " -H "Content-Type: application/json" -d $'{ "source": "AmazingDev", "destination": "+6512345678", "text": "Hello, World!", "encoding": "AUTO" }'
  • And that’s it! Here is the result:

Pasted_Graphic_6

Going further

I. API response

  • When sending the curl command above from your command line utility, you notice that the Wavecell API sends back a response that shows up in your terminal, for example in this tutorial:
{
  "umid":"f9eaeb51-24fd-e611-813c-06ed3428fe67",
  "clientMessageId":null,
  "destination":"6512345678",
  "status":{
	"code":"QUEUED",
	"description":"SMS is accepted and queued for processing"
  }
}
  • The API response is used to provide a feedback about the expected result of the API request (sending an SMS) and various additional information.
  • If we take some time analyze the different elements there, we can identify the following:
    • umid: it stands for unique message id, it is the unique id associated with this SMS by Wavecell platform.
    • clientmessageid: here, it is null because no value has been specified in the request but you have the possibility to attribute your own custom ids to your messages.
    • destination: this is the phone number to which the SMS was sent.
    • status: this array contains 2 elements: the status of the message and the description of this status
  • For more information, check the dedicated section of the API documentation, “Response” section

II. API errors

  • A developer World without error would not be funny!
  • If ever you send malformed requests to the API, it will let you know by using some specific error codes in the response.
  • You can find the different codes and their meanings in the error codes documentation