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

Usage    |    Extra Features    |    Cordova Plugin    |    Contributors

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

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

• 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"
    .../>

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" />

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 )

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

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 {
    ...
});

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);

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" />

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)

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-VoIpUSSD - Ramy Mokako

Thanks goes to these wonderful people (emoji key):

Romell D.Z. 福迪 💻

Abdullahi Yusuf 💻

Mohamed Hamdy Hasan 💻

Mohamed Daahir 💻

Ramy Mokako 🔌

Md Mafizur Rahman 💻

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.