VOIP USSD ANDROID

Loved the tool? Please consider donating 💸 to help it improve!

Usage    |    Extra Features    |    Cordova Plugin    |    Contributors

by Romell Dominguez

Target Development High Quality:

Interactive with ussd windows, remember the USSD interfaces depends on the System Operative and the manufacturer of Android devices.

Community Chat

Downloads Dashboard

USSD LIBRARY

Implementations

Add the following dependency in your app's build.gradle configuration file:

Repository	implementation	Status
jcenter()	'com.romellfudi.ussdlibrary:ussd-library:1.1.i'	DEPRECATED
jcenter()	'com.romellfudi.ussdlibrary:kotlin-ussd-library:1.1.k'	DEPRECATED
maven { url https://jitpack.io }	'com.github.romellfudi.VoIpUSSD:ussd-library:1.4.a'	READY
maven { url https://jitpack.io }	'com.github.romellfudi.VoIpUSSD:kotlin-ussd-library:1.4.a'	READY

• Writing a config xml file from here to res/xml folder (if necessary), this config file allow to link between Application and System Oerative:

<?xml version="1.0" encoding="utf-8"?>
<accessibility-service xmlns:android="http://schemas.android.com/apk/res/android"
    .../>

Application Permissions

To use the application, add the following permissions to your AndroidManifest.xml:

<uses-permission android:name="android.permission.CALL_PHONE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />

Service Configuration

Include the service in your AndroidManifest.xml for Java:

<service
    android:name="com.romellfudi.ussdlibrary.USSDService"
    android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE">
    <intent-filter>
        <action android:name="android.accessibilityservice.AccessibilityService" />
    </intent-filter>
    <meta-data
        android:name="android.accessibilityservice"
        android:resource="@xml/ussd_service" />
</service>

Or for Kotlin:

<service
    android:name="com.romellfudi.ussdlibrary.USSDServiceKT"
    android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE">
    <intent-filter>
        <action android:name="android.accessibilityservice.AccessibilityService" />
    </intent-filter>
    <meta-data
        android:name="android.accessibilityservice"
        android:resource="@xml/ussd_service" />
</service>

NOTE: You may want to override android:notificationTimeout="0"to a corresponding value of 200 or avobe by copying the contents of @xml/ussd_service to the xml dir. Otherwise it is possible that the library will miss accessibility events during operation, resulting is unintended behaivours (e.g not reading up to date prompts #115 )

Usage Instructions

1. Create a HashMap to identify USSD response messages for login and error scenarios:

KEY MESSAGE	String Messages
KEY_LOGIN	"espere", "waiting", "loading", "esperando", ...
KEY_ERROR	"problema", "problem", "error", "null", ...

For Java:

Map<String, HashSet<String>> map = new HashMap<>();
map.put("KEY_LOGIN", new HashSet<>(Arrays.asList("espere", "waiting", "loading", "esperando")));
map.put("KEY_ERROR", new HashSet<>(Arrays.asList("problema", "problem", "error", "null")));

For Kotlin:

val map = HashMap<String, HashSet<String>>()
map["KEY_LOGIN"] = hashSetOf("espere", "waiting", "loading", "esperando")
map["KEY_ERROR"] = hashSetOf("problema", "problem", "error", "null")

2. Instantiate a USSDController object and invoke a USSD code:

For Java:

USSDApi ussdApi = USSDController.getInstance(context);
ussdApi.callUSSDInvoke(phoneNumber, map, new USSDController.CallbackInvoke() {
    @Override
    public void responseInvoke(String message) {
        // Handle the USSD response
        String dataToSend = "data"; // Data to send to USSD
        ussdApi.send(dataToSend, new USSDController.CallbackMessage() {
            @Override
            public void responseMessage(String message) {
                // Handle the message from USSD
            }
        });
    }

    @Override
    public void over(String message) {
        // Handle the final message from USSD or error
    }
});

For Kotlin:

val ussdApi = USSDController.getInstance(context)
ussdApi.callUSSDOverlayInvoke(phoneNumber, map, object : USSDController.CallbackInvoke {
    override fun responseInvoke(message: String) {
        // Handle the USSD response
        val dataToSend = "data" // Data to send to USSD
        ussdApi.send(dataToSend) { responseMessage ->
            // Handle the message from USSD
        }
    }

    override fun over(message: String) {
        // Handle the final message from USSD or error
    }
})

3. For custom message handling, structure your code as follows:

For Java:

// Example of selecting options from USSD menu
ussdApi.callUSSDInvoke(phoneNumber, map, new USSDController.CallbackInvoke() {
    ...
    // Select the first option
    ussdApi.send("1", new USSDController.CallbackMessage() {
        ...
        // Select the next option
        ussdApi.send("1", new USSDController.CallbackMessage() {
            ...
        });
    });
    ...
});

For Kotlin:

// Example of selecting options from USSD menu
ussdApi.callUSSDOverlayInvoke(phoneNumber, map, object : USSDController.CallbackInvoke {
    ...
    // Select the first option
    ussdApi.send("1") {
        ...
        // Select the next option
        ussdApi.send("1") {
            ...
        }
    }
    ...
})

4. For dual SIM support, specify the SIM slot:

For Java:

ussdApi.callUSSDInvoke(phoneNumber, simSlot, map, new USSDController.CallbackInvoke() {
    ...
});

For Kotlin:

ussdApi.callUSSDOverlayInvoke(phoneNumber, simSlot, map, object : USSDController.CallbackInvoke {
    ...
});

Static Methods

For Android M and above, check permissions before invoking USSD:

// Check if accessibility permissions are enabled
ussdApi.verifyAccessibilityAccess(Activity);
// Check if overlay permissions are enabled
ussdApi.verifyOverlay(Activity);

Overlay Service Widget (Optional)

For Android O and above, use the OverlayShowingService to handle overlay permissions. Add the following permission to your AndroidManifest.xml:

<uses-permission android:name="android.permission.ACTION_MANAGE_OVERLAY_PERMISSION" />

SplashLoadingService

Add the service to your AndroidManifest.xml:

<service android:name="com.romellfudi.ussdlibrary.SplashLoadingService"
         android:exported="false" />

Start and stop the service around the USSD invocation:

For Java:

Intent svc = new Intent(activity, SplashLoadingService.class);
// Show the overlay
activity.startService(svc);
// Invoke USSD and handle responses
...
// Dismiss the overlay
activity.stopService(svc);

For Kotlin:

val svc = Intent(activity, SplashLoadingService::class.java)
// Show the overlay
activity.startService(svc)
// Invoke USSD and handle responses
...
// Dismiss the overlay
activity.stopService(svc)

EXTRA: Use Voip line

In this section leave the lines to call to Telcom (ussd number) for connected it:

ussdPhoneNumber = ussdPhoneNumber.replace("#", uri);
Uri uriPhone = Uri.parse("tel:" + ussdPhoneNumber);
context.startActivity(new Intent(Intent.ACTION_CALL, uriPhone));

ussdPhoneNumber = ussdPhoneNumber.replace("#", uri)
val uriPhone = Uri.parse("tel:$ussdPhoneNumber")
context.startActivity(Intent(Intent.ACTION_CALL, uri))

Once initialized the call will begin to receive and send the famous USSD windows

Cordova Plugin

• cordova-plugin-VoIpUSSD - Ramy Mokako

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Romell D.Z. 福迪 💻

Abdullahi Yusuf 💻

Mohamed Hamdy Hasan 💻

Mohamed Daahir 💻

Ramy Mokako 🔌

Md Mafizur Rahman 💻

License

VoIpUSSD is a Free Library Software: You can use, study share and improve it at your will. Specifically you can redistribute and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.