How to: Enable Caller Id

This page will guide you through enabling Hiya's caller id overlay

Get Permission

Before your can respond to incoming calls by displaying Hiya's caller id overlay you will need these permissions:

Android 10+ (API level 29)

This is the optimal user experience, blocking unwanted calls before they ring. Your app will need to get the role and permissions listed below before blocking and showing caller id will function.

• ROLE_CALL_SCREENING
  • Required to load identity and block unwanted calls before they start ringing.
• READ_PHONE_STATE
  • Required to respond to call events using the BroadcastReceiver. This permission is mandatory and must be granted before calling startCallerIntelligence().
• ANSWER_PHONE_CALLS
  • Required to auto-block the phone calls for the users. If any of the auto-block features are enabled, the users must grant this permission.
• READ_CONTACTS
  • Required to show contact information if the phone number is from one of the contacts. To provide better user experiences, we recommend providing this permission such that HiyaServices will not perform an API lookup when the number is in the user’s contact list and thus avoid showing a different identity from that of the default dialer.

Android 9 and below (API levels 23-28)

Because the call screener role is not available until api level 29 we need to use a slightly larger set of permissions to support call identity and blocking on api levels 23-28:

• READ_CALL_LOG

  • In order to get the phone number from the Broadcast event, the users must grant this permission.

• READ_PHONE_STATE

  • Required to respond to call events using the BroadcastReceiver. This permission is mandatory and must be granted before calling startCallerIntelligence().

• ANSWER_PHONE_CALLS

  • Required to auto-block the phone calls for the users. If any of the auto-block features are enabled, the users must grant this permission.

• READ_CONTACTS

  • Required to show contact information if the phone number is from one of the contacts. To provide better user experiences, we recommend providing this permission such that HiyaServices will not perform an API lookup when the number is in the user’s contact list and thus avoid showing a different identity from that of the default dialer.

• SYSTEM_ALERT_WINDOW

  • Required to show the caller id overlay over other apps as a phone call starts ringing while your app is not in the foreground. Note: This permission can not be directly requested, instead you must launch an Intent for result that takes users to settings:

        Intent(
            Settings.ACTION_MANAGE_OVERLAY_PERMISSION,
            Uri.parse("package:${requireContext().packageName}")
        )

Initialize Hiya's Caller Id

Once you have acquired the required permissions you can call HiyaService.startCallerIntelligence(Context) to identify calls as they ring on the device.

// When users have fully onboarded to your app. This only needs to be called once.
HiyaService.startCallerIntelligence(context)

If you want to stop identifying calls as they ring you can call HiyaService.stopCallerIntelligence(Context)

// This will stop the caller identity overlay from showing
HiyaService.stopCallerIntelligence(context)