The messaging products have the following features:

1. Bulk SMS

These are the messages sent as a whole to multiple recipients at once. It is the same message received by all recipients.

2. Two-way SMS

This is a message sent from the developer/business to the recipients where the recipients are required or able to send a message back to the sender, such as in collecting feedback.

3. Premium SMS

These are messages sent to recipients on demand or on subscription to generate income to the sender.

The airtime product has no variety of features, and simply involves sending an amount of airtime to various recipients.

In order for these transactions to take place, the developer needs to use an application URL to send the data, and monitor transactions made. That is where Postman and Ngrok come in.

Postman

Postman is an application that is used to process requests from a user on a particular application. The requests can be in the form of:

1. POST

2. GET

3. PUT

4. DELETE

… among others.

For the purpose of this article, we will focus on the POST request.

1. SMS

When sending a message, the developer/business POSTs a request with the required data in order to receive a notification. The required fields in POSTing a request for messaging are:

• Username: Your application username as defined on your dashboard

• To: The number of the message recipient (May be more than one for bulk messaging, The country code should be included in the number, Separate multiple numbers using a comma(,) )

• Message: The body of message to be shared to the recipients

On Postman, you can post a request to send a message for an application/file hosted locally via localhost or an application that is live via Africa’s Talking endpoint URL (Live or Sandbox).

i. Localhost

To POST a request via localhost, the code for the application is run and hosted on your local machine or environment. The URL used is the loopback address (127.0.0.1) together with the port number specified in your code (e.g. 3005, 8080). The combination yields a URL of the form:

http://127.0.0.1:PORTNUMBER/

...depending on your port number. For example: The port number used in the image illustration below is 3003, hence the URL is

http://127.0.0.1:3003/

This is as shown in the image below:

Since the code is on your local machine, the key identifiers such as API Key, username and sending details (To, Message) are already defined there. Hence, clicking on the SEND button immediately sends the message to the recipient(s). A response is output on the console as illustrated in the image below:

ii. Africa’s Talking SMS Endpoint (Live)

When using the AT endpoint URL, the endpoint is used by all users, hence, you have to specify your API Key, username as well as the message specifics (To, Message). The endpoints are in two forms: Live and Sandbox. In this case, we will use the Live endpoint. The endpoints can be found here. The Live endpoint URL is:

https://api.africastalking.com/version1/messaging

Note: Sandbox is the test environment, Live is the actual environment used in production.

The POST request sent to the endpoint with the mentioned fields is as shown in the images below:

• The API Key is added in the authorization field, hence, to the Header section as shown:

• The rest of the details are added in the Body as shown:

The response message received is similar to the one received when using the localhost URL as shown below:

1. Airtime

When sending airtime, the developer/business POSTs a request with the required data in order to receive a notification. The required fields in POSTing a request for airtime are:

• maxNumRetry: This is the maximum number of retries which the transaction does every 60 seconds for the next specified number of hours.

• Recipient details: The details of the recipients that are essential are:

• phoneNumber: This is the number of the recipient who receives the airtime.

• Amount: This is the amount to be transferred.

• Currency: This is to identify the currency form to be transferred as.

On Postman, you can post a request to send airtime for an application/file hosted locally via localhost or an application that is live via the Africa’s Talking endpoint URL (Live or Sandbox).

i. Localhost

The localhost method is done by POSTing using the URL formed by the loopback address (127.0.0.1) together with the port number specified in your code (e.g. 3005, 8080), just as shown in the previous section on SMS -> Localhost. This is as shown in the image below:

The response received is as shown in the image below:

ii. Africa’s Talking SMS Endpoint (Live)

When using the AT endpoint URL, the endpoint is used by all users, hence, you have to specify your API Key, username as well as the airtime specifics (maxNumRetry, Recipients). The endpoints are in two forms: Live and Sandbox. In this case, we will use the Live endpoint. The endpoints can be found here. The Live endpoint URL is:

https://api.africastalking.com/version1/airtime/send

The POST request sent to the endpoint with the mentioned fields is as shown in the images below:

• The API Key is added in the authorization field, hence, to the Header section as shown:

• The rest of the details are added in the Body as shown:

The response message received is similar to the one received when using the localhost URL as shown below:

Ngrok

Ngrok is used for connectivity to the app by providing a forwarding address. To do this, Ngrok should be installed on your local machine. The port to be accessed in as defined in the code for your application. Commands are used to access that port in which the code is running in this form:

ngrok http PORTNUMBER

For example, in our case the port number used is 3003, hence, the command is:

ngrok http 3003

After running the command, the terminal opens a window with details as illustrated in the image below:

With this, a forwarding address is identified which is used to create the callback URL.

Callback URLs

A callback URL is an address where data is posted to which enables you to receive reports in your application. The Ngrok forwarding address is placed in the callback URL field with a small extension to identify it. SMS and Airtime have various callback URLs as explained below:

a) SMS

• Delivery reports: Reports on whether the messages were delivered

• Incoming messages: Reports details on the incoming messages for two-way SMS

• Bulk SMS opt out: Reports on users who wish to opt out of receiving bulk SMSs

• Subscription notifications: Reports details on users who subscribe to various SMS

b) Airtime

• Status: Reports on whether the transactions were successful or failed

• Validation: Reports used when the developer wishes to validate or approve transactions before they take place

An illustration of setting a callback URL in:

• SMS (Delivery Reports)

The Ngrok forwarding address is placed in the callback URL field with a small extension to identify it, such as /delivery in this case. Hence, the callback URL is as shown in the image below:

The Submit button is selected and a message displayed to show that the callback has successfully been updated. Once this is done, whenever messages are sent, the reports are visible on the terminal as shown in the image below:

• Airtime (Status)

The Ngrok forwarding address is placed in the callback URL field with a small extension to identify it, such as /status in this case. Hence, the callback URL is as shown in the image below:

The Submit button is selected and a message displayed to show that the callback has successfully been updated. Once this is done, whenever transactions take place, the reports are visible on the terminal as shown in the image below:

That’s it. All the best in getting started :)

Resources

• Africa’s Talking Postman Collections are found here