Feature

SMS/MMS/2FA API Service

In today’s digital era, communication is vital. Whether for business purposes or personal connections, the ability to send instant messages and implement secure login processes is indispensable. Backendless, in collaboration with Plivo, offers an API service tailored for developers aiming to seamlessly deliver SMS/MMS messages and bolster app security with two-factor authentication (2FA).

Technical Capabilities

Drawing from Plivo’s acclaimed communication infrastructure, Backendless has curated a suite of APIs designed for the modern developer. The service not only facilitates seamless SMS/MMS dispatch but also empowers applications with passwordless and 2FA security features:

SMS & MMS Integration Features:

Real-time Notifications: Keep users informed with timely alerts and updates.
Media Exchange: Enable seamless sharing of multimedia content.
Automated Messaging Workflows: Optimize your communication processes with pre-defined messaging sequences.
User Engagement: Capitalize on SMS and MMS features to foster stronger user interactions.

Two-Factor Authentication (2FA) Security Enhancement:

Robust Account Protection: Integrate 2FA to fortify user account security.
Data Safeguarding: Ensure user data remains protected from potential breaches.

User Authentication Capabilities:

Phone Number Login: Offer users the convenience of authentication using their phone numbers.
Passwordless/Secure Code Access: Facilitate quick access with code-based authentication, combining speed with security.

Installation Instructions

Login to Backendless Console and select your app. Open the Marketplace screen, select the API Services section, and install the Plivo Integration Service.
During the installation, you are prompted to enter configuration details from your Plivo account. The required information can be obtained from the Plivo dashboard. The Plivo Sender Phone Number field value must start with + and include the country code, for example, +1 for the United States. Enter the required details and click the INSTALL button:
To verify the installation, click the Cloud Code icon in the Backendless Console and confirm that the Plivo API service appears in the list of services:
If you need to change configuration settings, click the gear icon to access the Service Configuration popup.

Phone Number Column

The login operations implemented with the Plivo Integration Service rely on a phone number present for every user. The phone number must be stored in the Users table. The name of the column where the phone number is stored is phoneNumber. However, you can change the column name using the Service Configuration described above.

Using the API

The API supported by the Plivo Integration Service can be used via REST or a Backendless SDK. To use the API with an SDK, generate the client-side library for the API as shown below:

Click the Business Logic icon in the Backendless Console and select the Plivo service.
Click the Download Client SDK icon as shown below (the icon is shown in bright green color):
Select the language of your choice to download the client SDK generated specifically for the Plivo service. The SDK includes all the methods provided by the Plivo Integration Service.

If a language you want to use does not appear in the list, you can still use the plugin. The information below describes all available options.

User Registration with Phone Verification

Consider the following scenario: your application’s registration form includes a field for the user’s phone number. When users create an account, they provide a phone number that you want to verify before their account is enabled. They can then log in after the registration process is complete.

The process of user registration with phone number confirmation consists of the following steps:

The application uses the standard registration API call. However, the client sends only the phone number. The response for the registration call includes a special value called "transactionId".
The Plivo Integration Service sends out an SMS message containing a confirmation code. The message is sent to the phone number specified in the request (1).
Your application asks the user to enter the confirmation code to complete the registration process.
Once the user enters the confirmation code, the application sends out the second registration API call, which now includes the following fields:
- email or the property/column used as identity by your application.
- password – user’s password
- transactionId – this is the value from step 1.
- transactionCode – this is the code sent to the user’s phone in step 2.
- phoneNumber – this is the same number used in step 1. This is required as a security measure.
The second registration API call returns a complete user object,

It is possible to configure your application to use the phoneNumber column as identity. In this case, the second registration API call will include only four properties (phoneNumber, password, transactioniId and transactionCode).
First registration request:

POST https://xxxx.backendless.app/api/users/register

Request Body:

{ 
  "phoneNumber":"PHONE-NUMBER-VALUE" 
}

Response:

{ 
  "transactionId": "TRANSACTION-ID-VALUE" 
}

Second registration request:

POST https://xxxx.backendless.app/users/register

Request Body:

{ 
  "email":"VALUE", 
  "password":"VALUE", 
  "phoneNumber":"MUST BE THE SAME VALUE AS IN FIRST CALL", 
  "transactionId":"VALUE FROM THE FIRST CALL'S RESPONSE", 
  "transactionCode":"VALUE SENT TO THE USER'S PHONE", 
}

Response:

{ 
  "userStatus": "ENABLED", 
  "created": VALUE, 
  "ownerId": "9693201D-C418-410B-FFAE-427D2D08B800", 
  "phoneNumber": "USER'S PHONE NUMBER", 
  "___class": "Users", "blUserLocale": 
  "en", 
  "updated": null, 
  "objectId": "9693201D-C418-410B-FFAE-427D2D08B800", 
  "email": "VALUE" 
}

Login with Phone Number

Consider a scenario where an application login form requires the user’s phone number and their password. The user enters their phone number and the password. If the password is correct, the user receives a code via SMS and enters the code into the application to complete the login. This scenario is supported by the API documented below.

The process consists of the following steps, which include two service API calls:

The application initiates user login with a phone number by making the first API call to the Plivo Integration API service.
Plivo Service verifies that a user with the provided phone number exists and sends a code to the user’s phone number.
The API call response has transactionId value.
The second API call by the application completes the login by sending transactionId and code to the Plivo API service.
If the code is confirmed, the second call’s response has the logged-in user object.

STEP 1: Request to initiate the login:

POST https://xxxx.backendless.app/api/services/Plivo/loginWithPhoneNumber

Request Body is a string value of the phone number:

"PHONE-NUMBER-VALUE"

Response Body

{ 
  "transactionId":"VALUE" 
}

STEP 2 Request to confirm code:

POST https://xxxx.backendless.app/api/services/Plivo/loginWithCode

Request Body:

{ 
  "transactionId":"TRANSACTION ID VALUE FROM STEP1", 
  "code" : "CODE SENT VIA SMS" 
}

Response Body:

{ 
  "___jsonclass": "Users", 
  "lastLogin": 1590527843419, 
  "userStatus": "ENABLED", 
  "created": 1590527533000, 
  "ownerId": "CBFA6722-58AD-12BE-FF80-28999D7D0200",
  "socialAccount": "BACKENDLESS", 
  "___class": "Users", 
  "blUserLocale": "en", 
  "user-token": "B83FA46D-A19A-A8CE-FF2B-976B7A1D8100", 
  "updated": null, 
  "email": "VALUE", 
  "objectId": "CBFA6722-58AD-12BE-FF80-28999D7D0200" 
}

The user-token property value is important, as it identifies the user’s session with Backendless. The value must be passed to the server as an HTTP header with all subsequent API calls.

Login with Phone Number And Password

The application initiates user login with a phone number and password by making the first API call to the Plivo Integration API service.
Plivo Integration Service verifies that a user with the provided phone number exists, and if the provided password is correct, sends a code to the user’s phone number.
The API call response has a transactionId value.
The second API call by the application completes the login by sending transactionId and the code from step 2 to the Plivo Integration API service.
If the code is confirmed, the second call’s response has the logged-in user object.

STEP 1: Request to initiate the login:

POST https://xxxx.backendless.app/api/services/Plivo/loginWithPhoneNumberAndPassword

Request Body:

{ 
  "phoneNumber":"VALUE", 
  "password" : VALUE" 
}

Response Body:

{ 
  "transactionId":"VALUE" 
}

STEP 2: Request to confirm code:

POST https://xxxx.backendless.app/api/services/Plivo/loginWithCode

Request Body:

{ 
  "transactionId":"TRANSACTION ID VALUE FROM STEP1", 
  "code" : "CODE SENT VIA SMS" 
}

Response Body:

{ 
  "___jsonclass": "Users", 
  "lastLogin": 1590527843419, 
  "userStatus": "ENABLED", 
  "created": 1590527533000, 
  "ownerId": "CBFA6722-58AD-12BE-FF80-28999D7D0200",
  "socialAccount": "BACKENDLESS", 
  "___class": "Users", 
  "blUserLocale": "en", 
  "user-token": "B83FA46D-A19A-A8CE-FF2B-976B7A1D8100", 
  "updated": null, 
  "email": "VALUE", 
  "objectId": "CBFA6722-58AD-12BE-FF80-28999D7D0200" 
}

The user-token property value is important, as it identifies the user’s session with Backendless. The value must be passed to the server as an HTTP header with all subsequent API calls.

Sending SMS/MMS API

The API below provides a way to send SMS/MMS messages using the Plivo Integration Service via your Plivo account.

POST https://xxxx.backendless.app/api/services/Plivo/sendMessage

Request Body:

{
    "phoneNumber": "RECEPIENT NUMBER",
    "message": "TEXT MESSAGE",
    "mediaUrls": "URL1,URL2,..,.."]
}

The mediaUrl is an optional parameter. If provided, it must contain a string value which is a comma-separated list of URL-encoded hyperlinks to the images or media to be included in the MMS message.

Response Body:

The same response as documented by Plivo – https://www.plivo.com/docs/sms/api/message#send-a-message