Hibot WhatsApp Authentication Template Error Signals

When using Hibot WhatsApp Business API authentication templates, your One-Tap Autofill or Zero-Tap OTP flow may sometimes fail.

To help developers debug these issues, WhatsApp provides Android-only error signals through the com.whatsapp.otp.OTP_ERROR intent.

These error signals are useful when:

• One-Tap Autofill falls back to Copy Code

• Zero-Tap delivery does not reach your app

• OTP notifications do not appear

• Handshake validation fails

• Android or WhatsApp settings block delivery

• 
  

Upcoming Deprecation Notice

Starting April 15, 2026, the old PendingIntent-based handshake method for authentication templates will be deprecated.

If your app still uses PendingIntent to initiate the OTP handshake or verify app identity, you should migrate to the WhatsApp OTP Android SDK.

The SDK provides:

• Easier handshake creation

• Built-in handshake ID validation

• Automatic error signal processing

• Better support for One-Tap and Zero-Tap authentication templates

• 
  

What Happens When an Eligibility Check Fails?

When WhatsApp receives your authentication template, it performs multiple eligibility checks.

If any check fails:

• Zero-Tap delivery stops

• One-Tap Autofill button is replaced with a Copy Code button

• WhatsApp may send an OTP error signal instead of the OTP code

The error signal is delivered through the following Android intent:

com.whatsapp.otp.OTP_ERROR

Your app must listen for this intent to detect and troubleshoot OTP delivery issues.

Available WhatsApp OTP Error Signals

ambiguous_delivery_destination

ambiguous_delivery_destination

Description:

Multiple apps listed in your template’s supported_apps array requested OTP delivery within the last 10 minutes, and WhatsApp could not determine which app should receive the OTP.

This usually happens when:

• Multiple builds of your app are installed

• More than one package initiates a handshake

• Several apps use the same verification template

Important:

This error only appears in the Android emulator.

How to fix it:

• Ensure only one app initiates the handshake

• Reduce the number of active app package names in supported_apps

• Wait until old handshakes expire before sending another OTP

• 
  

incompatible_os_version

incompatible_os_version

Description:

The Android device is running a version older than Android KitKat 4.4 (API 19).

WhatsApp authentication templates require Android API 19 or higher.

How to fix it:

• Ask the user to update Android

• Provide a fallback Copy Code or SMS option

• 
  

incorrect_signature_hash

incorrect_signature_hash

Description:

The app signature hash in the authentication template does not match the installed Android app.

This usually happens when:

• The wrong signature hash was added during template creation

• The app was signed with a different keystore

• Debug and production apps use different certificates

Important:

This error only appears in the Android emulator.

How to fix it:

• Recalculate the Android app signature hash

• Update the template with the correct signature hash

• Ensure the package name and signing key match the installed app

Example valid hash:

K8a/AINcGX7

missing_handshake_or_disorder

Description:

The OTP message arrived before your app initiated the handshake.

This is one of the most common issues with One-Tap and Zero-Tap authentication templates.

Typical causes:

• You sent the WhatsApp template before calling the handshake function

• The handshake was never triggered

• The app crashed before the handshake completed

How to fix it:

Always follow this order:

1. Initiate the handshake

2. Store the handshake ID

3. Send the WhatsApp OTP template

4. Wait for the OTP broadcast or One-Tap click

Correct SDK example:

WhatsAppOtpHandler whatsAppOtpHandler = new WhatsAppOtpHandler();
UUID handshakeId = whatsAppOtpHandler.sendOtpIntentToWhatsApp(context);

Only after this should you send the OTP message through Hibot WhatsApp Business API.

otp_request_expired

otp_request_expired

Description:

The OTP request expired before the message arrived.

This happens when:

• More than 10 minutes passed after the handshake

• Or more than the template’s code_expiration_minutes value passed

When this happens, WhatsApp replaces One-Tap Autofill with the Copy Code button.

How to fix it:

• Send the OTP immediately after the handshake

• Keep OTP expiration short, ideally between 3 and 10 minutes

• Re-initiate the handshake before sending another OTP

• 
  

whatsapp_message_notification_disabled

Description:

Notifications are disabled inside the WhatsApp or WhatsApp Business app settings.

Even though the OTP message is delivered, the user may never see it.

Important:

This error only appears in the Android emulator.

How to fix it:

Ask the user to enable:

WhatsApp > Settings > Notifications

whatsapp_notification_disabled

whatsapp_notification_disabled

Description:

Device-level notifications for WhatsApp are disabled.

This means Android blocks WhatsApp notifications completely.

Important:

This error only appears in the Android emulator.

How to fix it:

Ask the user to enable Android notifications for WhatsApp:

Android Settings > Apps > WhatsApp > Notifications > Allow

Implementing Error Signal Support in Android

To receive these OTP debugging signals, add a BroadcastReceiver to your Android app.

AndroidManifest.xml Setup

<receiver
    android:name=".app.otp.OtpErrorReceiver"
    android:enabled="true"
    android:exported="true">
    <intent-filter>
        <action android:name="com.whatsapp.otp.OTP_ERROR" />
    </intent-filter>
</receiver>

This receiver listens for all WhatsApp OTP error events.

Using the OTP Android SDK (Recommended)

The easiest way to process debug signals is through the WhatsApp OTP Android SDK.

public class OtpErrorReceiver extends BroadcastReceiver {

    @Override
    public void onReceive(Context context, Intent intent) {
        WhatsAppOtpIncomingIntentHandler handler = new WhatsAppOtpIncomingIntentHandler();

        handler.processOtpDebugSignals(
            intent,
            (debugSignal) -> handleSignal(debugSignal),
            (error, exception) -> handleError(error, exception)
        );
    }
}

Benefits of using the SDK:

• Parses error signals automatically

• Handles invalid intent formats

• Simplifies debugging

• Future-proof for the April 2026 deprecation

Without the SDK

If you are not using the WhatsApp OTP Android SDK, you can read the error values manually.

public class OtpErrorReceiver extends BroadcastReceiver {

    public static final String OTP_ERROR_KEY = "error";
    public static final String OTP_ERROR_MESSAGE_KEY = "error_message";

    @Override
    public void onReceive(Context context, Intent intent) {

        String otpErrorKey = intent.getStringExtra(OTP_ERROR_KEY);
        String otpErrorMessage = intent.getStringExtra(OTP_ERROR_MESSAGE_KEY);

        // Handle error here
    }
}

Example received values:

error = missing_handshake_or_disorder
error_message = Handshake was not initiated before OTP message delivery

Best Practices for Avoiding OTP Delivery Errors

To reduce One-Tap and Zero-Tap authentication failures:

• Always initiate the handshake before sending the OTP

• Migrate to the OTP Android SDK before April 15, 2026

• Validate the handshake ID before accepting the OTP

• Double-check your app signature hash

• Keep code expiration below 10 minutes

• Enable fallback Copy Code buttons

• Test on both WhatsApp and WhatsApp Business apps

• Verify Android notification settings during testing

• 
  

Recommended Debugging Flow

If One-Tap or Zero-Tap is not working:

1. Check whether the handshake was initiated

2. Confirm the app package name is correct

3. Verify the signature hash matches the installed app

4. Confirm the OTP was sent within the allowed time window

5. Check WhatsApp and Android notification settings

6. Listen for the com.whatsapp.otp.OTP_ERROR broadcast

7. Log the error key and message for debugging

8. 
   

Final Thoughts

WhatsApp OTP Error Signals make it much easier to troubleshoot One-Tap Autofill and Zero-Tap authentication templates inside Hibot WhatsApp Business API.

By implementing the OTP_ERROR receiver and migrating to the WhatsApp OTP Android SDK, developers can quickly detect why OTP delivery failed and provide a better authentication experience for users.