How to send SMS using the MTN Developer APIs (MADAPI)

This guide explains how you can access the MTN value added APIs through the MTN developer portal (https://developers.mtn.com/). It shows you how to get a developer Access token, and how to use the MTN SMS API v2 to send SMS messages using Ozeki SMS Gateway.

API URLs

  • https://sandbox.api.mtn.com/oauth/client_credential/accesstoken?grant_type=client_credentials
  • https://api.mtn.com/v2/messages/sms/outbound

What is MTN SMS Service?

MTN, as a pan-African mobile operator provides SMS services (SMS sending and receiving) for their business partners and mobile telephone users.

What is MADAPI Protocol?

It is a protocol implementation of MTN's online SMS Service.

What is MADAPI API?

The MTN MAD API is a unified API that includes various independent microservices (such as Mobile Money API, SMS and USSD API, Chenosis Marketplace API, etc.) These services are accessed by MTN and partner providers through the MAD API. MAD-APi service connections are provided by Google Apigee through a unified API gateway and provisioning portal.

How does the MADAPI API work?

MADAPI is a platform where MTN's SMS Messaging API allows developers to build SMS messaging into their business applications.

How to register on the Madapi Developer Portal

The following video will guide you through the seamless process of registering on the Madapi Developer Portal, where you can learn about API development possibilities. Discover the power of MTN's APIs that can elevate your applications, enhance communication, and streamline your projects. Follow along as we demonstrate the simplicity and effectiveness of using the MTN SMS API v2 in combination with the Ozeki SMS Gateway to send SMS messages seamlessly.

Video 1 - How to register on the Madapi Developer Portal (Video tutorial)

To begin the process, you need to register at the https://developers.mtn.com/ website, by clicking on the "Register" button at the upper right corner of the page. This registration will enable you to create an app; just follow the straightforward registration steps. Follow these steps to create your account:

select register
Figure 1 - Select register

By clicking on the "Register" button will bring up a registration page, where it is required to enter some personal details, like name, e-mail address. Make sure to use a valid email address as this will be used for communication and verification purposes. After that, click on the "Next" button. Add your last name, too. Select "Next" button again.

define name and email address
Figure 2 - Define name and email address

Choose a strong, unique password for your account that combines capital and lowercase letters, numbers, and special characters for safety purposes. When you've created your password, confirm it by entering it in again, then click the "Next" button to move on to the next stage.

add password
Figure 3 - Add password

To proceed, select your country of residence from the provided options, and once you've made your selection, click on the "Next" button. This will take you to the next stage of the registration process. Read through the terms and conditions, privacy policy, and any other relevant agreements provided by MTN. If you agree to their terms, check the appropriate box to give your consent.

select country
Figure 4 - Select country

After completing the registration form, an email will be sent to the address you provided. Click on the verification link in that email to confirm your account and activate it. You need to enter an authenticator code that you will receive through your Google Authenticator app. If you do not have yet this application, get it from any digital distribution platform for software called applications, like Google Play or App Store.

verify email address
Figure 5 - Verify email address

Download the Google Authenticator on your Android mobile phone from the Google Play or App Store if you use iOS device.

install google authenticator
Figure 6 - Install Google Authenticator

Now, you need to assign a Google Authenticator account, to be able to authenticate your MTN account. Tap on the "+" or "Add" button within the app to set up a new account. Enter your details, provided in the MTN's verification email. You will have two options to add your MTN account: If MTN provides a QR code, use the Google Authenticator app to scan it. This will automatically set up the account within the app. Or if there is no QR code provided, you can manually enter the account information.

add account in google authenticator
Figure 7 - Add account in Google Authenticator

You will need to enter the account name, your MTN account email, and the secret key or authentication code provided by MTN. Choose a name to identify your MTN account within the Google Authenticator app. Enter the email address associated with your MTN account. Paste your secret key, which is a unique code provided by MTN specifically for enabling two-factor authentication (2FA) with Google Authenticator.

account details in google authenticator
Figure 8 - Account details in Google Authenticator

Once you've added the account to Google Authenticator, the app will start generating six-digit one-time passwords (OTPs) that change every 30 seconds. Return to the MTN's verification email, where you should find a field to enter the verification code generated by the Google Authenticator app. Enter the current code from the Google Authenticator app into the designated field on the verification email. Click on "Authenticate" button to complete the setup process. By clicking on the "Authenticate" button, the MTN's developer portal will show up. There, you can see a My Profile page, where you can personalize your account and view the previously set up account details.

enable two-factor authentication
Figure 9 - Enable two-factor authentication

How to login using Google Authenticator

In order to log into your account, load the https://developers.mtn.com/ page and enter your email address and password to the certain boxes, then click on the "Log In" button at the bottom.

developer portal login
Figure 10 - Developer portal login

After that, it is required to enter the 2FA authentication code, provided by the Google Authenticator app. Enter the given password, then choose the "Authenticate" button to complete login process.

two-factor authentication
Figure 11 - Two-factor authentication

How to Create an APP

In this short video, you'll discover how to create an app using the MTN SMS API v2, in collaboration with the Ozeki SMS Gateway, enabling you to send SMS messages seamlessly. Follow the step-by-step guide o see the effectiveness and ease of integrating these tools into your projects.

Video 2 - How to Create an APP

For the first, click on the "Build app" button at the upper right corner of the page. This button will start the app creation process and let you start by looking through the numerous MTN developer platform development options.

build app
Figure 12 - Build app

You need to enter some essential details connected to the Apps. These details are necessary for setting up and configuring your app within the MTN developer platform. Choose a unique name for your app. This name will be used to identify your application within the developer portal. It is optional to write a brief description of your app's purpose and functionality. After that, click on the "Select countries" button.

define app details
Figure 13 - Define app details

After entering the necessary details connected to your app, the next step is to select the country you are coming from and would like to associate your app with. This selection helps MTN customize and optimize the services and APIs available to your app based on the specific region's requirements and regulations.

select country
Figure 14 - Select country

Now, choose the MTN SMS V2 interface option from the list of products. Click on the "+" button situated in the bottom right corner of the product description. By clicking on it, you will create this SMS interface with callback support.

add sms v2 interface
Figure 15 - Add SMS V2 interface

To initiate the app creation process, find the "Create app" button, then click on it.

create app
Figure 16 - Create app

If the application has created successfully, you will receive a notification about creation. Afterward, you will be directed to a summary page that provides an overview of your approved apps. On the summary page, you will find some details about the apps. If you have any apps that was not installed successfully, then in that case, you will see the list of apps under the "Revoked Apps" title.

madapi application created
Figure 17 - Madapi application created

How to add the SMS V2 service to your App

Now, we will explain how to add the SMS V2 service to your App. To add the SMS V2 service to your app, you need to edit the application details in the My apps page, under the Approved Apps tab.

edit application
Figure 18 - Edit application

Make changes in application details. Change the name of your app. Modify the description of your app to better reflect its purpose and functionality. Add or modify URLs that users should be redirected. Click on the "Edit" button, to modify the app. After making the changes, ensure accuracy, then click on "Next" button to proceed to the next step.

modify application details
Figure 19 - Modify application details

By completing these steps, click on the tick in the black circle. The SMS V2 service will be successfully added to your app. You can now leverage MTN's SMS capabilities to enhance communication.

add sms v2 service to your app
Figure 20 - Add SMS V2 service to your app

How to copy the customer key and Production secret into Ozeki 10

In the upcoming video, we will demonstrate the step-by-step process of copying the customer key and Production secret into Ozeki 10. This procedure enables the seamless integration between the two platforms, allowing you to leverage the features of MTN's APIs and Ozeki 10 to enhance your messaging capabilities and streamline communication with your users.

Video 3 - How to copy the customer key and Production secret into Ozeki 10 (Video tutorial)

To begin, log in to your Ozeki SMS Gateway account. If you don't have an account yet, you can download the software from the https://ozeki.hu/ website. Once you have your account ready, proceed to open the Ozeki Gateway on the Ozeki Desktop to access the gateway's management interface and configure your messaging settings. Click on the "Add new connections..." link on the Connections panel or choose the "Connect" icon at the toolbar.

add new connection
Figure 21 - Add new connection

By clicking on it, a list will appear, containing various client options that can be installed. Find the "MTN MADAPI client" that allows you to create outgoing SMS requests using MTN SMS V2 API, then click on the "Install" link.

install madapi client
Figure 22 - Install Madapi client

Installing the MTN MADAPI client, will bring up a page where you have to enter some details to set up the connection. Load the MNP'S Developers Portal and copy the consumer key and secret codes.

copy key and secret
Figure 23 - Copy key and secret

Paste these codes into the designated fields at the Ozeki SMS Gateway. Once you have pasted the codes in the appropriate sections, scroll down to the bottom of the page. To save the changes and confirm the integration, click on the "Ok" button. Saving the codes with the "Ok" button will ensure that the Ozeki SMS Gateway is now properly configured to work with MTN's APIs.

saste key and secret
Figure 24 - Paste key and secret

How to view that you have received your access token

After saving the details in the Ozeki SMS Gateway control panel, navigate to the "Events" tab. Here, you will find a slider button on the left side of the panel. Switch the slider button to the green position. If the setup was successful, you will receive a notification labelled "Access Token" in the Events panel. This indicates that the integration between MTN's APIs and Ozeki SMS Gateway is now active, and your app can access the necessary authentication token to communicate seamlessly with MTN's services.

access token received
Figure 25 - Access token received

How to send a test SMS and how to check the logs

In the upcoming video, we will provide a step-by-step guide of how to send a test SMS using the integrated MTN SMS service through the Ozeki SMS Gateway. We will guide you through the process of composing and sending the test message, ensuring that you can effectively communicate with your intended recipients. Additionally, we will show you how to check the logs within the Ozeki SMS Gateway to monitor the status and delivery details of sent SMS messages.

Video 4 - How to send a test SMS and how to check the logs (Video tutorial)

As the first step, log into your Ozeki SMS Gateway account and load the Ozeki Home page. Select the MNT_MADAPI_client connection. Open the "Test" tab at the MNT_MADAPI_client details. There, you can create an SMS message. To creation, provide the recipient's phone number into the certain filed, then enter the text message into the SMS field.

create test sms message
Figure 26 - Create test SMS message

After entering these data, click on the "Send" button.

send test message
Figure 27 - Send test message

Upon opening the Event tab in the Ozeki SMS Gateway, you will be able to view the status of the message that was sent. If the message was sent successfully, you will receive a notification labelled "Successfully initialized." This notification confirms that the SMS was delivered to the recipient without any issues.

message sent
Figure 28 - Message sent

Summary

The guide provides step-by-step instructions on how to use the MTN Developer APIs (MADAPI) in connection with the Ozeki SMS Gateway to send SMS messages seamlessly. By following the guide, developers can access the MTN value added APIs through the MTN developer portal, obtain a developer Access token and utilize the MTN SMS API v2 to send SMS messages. Overall, the combination of MTN Developer APIs and Ozeki SMS Gateway offers developers a useful and reliable solution for integrating SMS messaging into their applications, enabling efficient communication and enhancing user experience.

More information