SMS Notification API (4.x for Android)

Updated at:

This document describes the Android SDK 4.x APIs for binding the current device to and unbinding it from a phone number.

Note

This document applies to Mobile Push Android SDK 4.x. The APIs and examples are based on the 4.0.0 release. For applications that use SDK 3.x, refer to the 3.x API documentation.

Use cases

In SMS integration scenarios, the client calls the following APIs to associate a device with a phone number. A successful binding establishes the association. Server-side push parameters determine the conditions and timing for SMS fallback.

Before calling these APIs, complete the initialization by using PushServiceFactory.init and the push registration. Ensure the onSuccess callback of the register method has been triggered. Get the CloudPushService instance by calling PushServiceFactory.getCloudPushService(). The examples use a non-null CommonCallback. If an operation fails, check the errorCode and errorMessage in the onFailed callback.

Bind phone number (bindPhoneNumber)

Method definition

void bindPhoneNumber(String phoneNumber, CommonCallback callback);

Class

CloudPushService

Parameters

Parameter

Type

Required

Description

phoneNumber

String

Yes

A valid phone number to bind. This parameter cannot be null or an empty string.

callback

CommonCallback

No

A callback for the operation's result. This parameter can be null. We recommend providing a non-null callback to handle the success or failure.

Return value and callback

This method returns void. On success, the onSuccess(String response) callback is triggered. On failure, the onFailed(String errorCode, String errorMessage) callback is triggered with an error code and error message.

Code examples

public void bindDevicePhoneNumber(String phoneNumber) {
    CloudPushService pushService = PushServiceFactory.getCloudPushService();
    pushService.bindPhoneNumber(phoneNumber, new CommonCallback() {
        @Override
        public void onSuccess(String response) {
            Log.i("PushDemo", "bindPhoneNumber success");
        }

        @Override
        public void onFailed(String errorCode, String errorMessage) {
            Log.e("PushDemo", "bindPhoneNumber failed: " + errorCode + ", " + errorMessage);
        }
    });
}
fun bindDevicePhoneNumber(phoneNumber: String) {
    val pushService = PushServiceFactory.getCloudPushService()
    pushService.bindPhoneNumber(phoneNumber, object : CommonCallback {
        override fun onSuccess(response: String?) {
            Log.i("PushDemo", "bindPhoneNumber success")
        }

        override fun onFailed(errorCode: String?, errorMessage: String?) {
            Log.e("PushDemo", "bindPhoneNumber failed: $errorCode, $errorMessage")
        }
    })
}

Unbind phone number (unbindPhoneNumber)

Removes the binding between the current device and its associated phone number.

Method definition

void unbindPhoneNumber(CommonCallback callback);

Class

CloudPushService

Parameters

Parameter

Type

Required

Description

callback

CommonCallback

No

A callback for the operation's result. This parameter can be null. We recommend providing a non-null callback to handle the success or failure.

Return value and callback

This method returns void. On success, the onSuccess(String response) callback is triggered. On failure, the onFailed(String errorCode, String errorMessage) callback is triggered with an error code and error message.

Code examples

CloudPushService pushService = PushServiceFactory.getCloudPushService();
pushService.unbindPhoneNumber(new CommonCallback() {
    @Override
    public void onSuccess(String response) {
        Log.i("PushDemo", "unbindPhoneNumber success");
    }

    @Override
    public void onFailed(String errorCode, String errorMessage) {
        Log.e("PushDemo", "unbindPhoneNumber failed: " + errorCode + ", " + errorMessage);
    }
});
val pushService = PushServiceFactory.getCloudPushService()
pushService.unbindPhoneNumber(object : CommonCallback {
    override fun onSuccess(response: String?) {
        Log.i("PushDemo", "unbindPhoneNumber success")
    }

    override fun onFailed(errorCode: String?, errorMessage: String?) {
        Log.e("PushDemo", "unbindPhoneNumber failed: $errorCode, $errorMessage")
    }
})

Verify integration

After confirming that the binding API call was successful, verify the end-to-end flow with your server-side SMS integration configuration. Redact phone numbers in logs and screenshots.

References

For integration instructions, see Android SDK integration (4.x).

For applications that use SDK 3.x, see SMS Notification API (3.x for Android).