Android call screening

About 30 minutes. You write one permission prompt. The SDK does the rest.

Before you start

Finish the Android quickstart first, and confirm a lookup returns a name. Everything here depends on working credentials.

Automatic blocking needs Android 10 or later. Your app can still target minSdk 24, because the SDK turns the feature off by itself on older versions.

What you get

Two features, and each needs its own permission from the user.

Feature	Permission the user grants	Where the user grants it
Reject known spam calls	Caller ID and spam app role	A system dialog you trigger
Show a name over the call screen	Display over other apps	A Settings screen you open

The two are independent. Ask for one, the other, or both.

What you do not have to write

The SDK already ships the call screening service and its manifest entry. Gradle merges them into your app when you add the dependency.

If you want the SDK name card, do not declare a CallScreeningService of your own. Do not add android.permission.BIND_SCREENING_SERVICE. Both are present already.

If you want your own name card, you replace that service. See Drawing your own name card.

Android allows one screening app at a time, so your app cannot combine with another one.

Step 1: ask for the role

Add this to your main activity. It asks for both permissions, and it skips any the user already granted.

Android shows this dialog when you launch the role intent:

CallerAPI SDK default Caller ID and spam app

Do not ask on your first screen. A user who has not seen your app yet says no. Ask after you have explained the feature. A denied role cannot be asked for again on some Android versions, so the user has to go to Settings themselves.

Step 2: turn on block reporting

The dashboard counts blocked calls only after the user agrees to share that count:

Call it after your own consent screen. Blocking works without it. Only the count is affected.

Step 3: test it

You need a real phone. An emulator cannot receive a real call.

Install your app on the phone.

Grant both permissions.

Look up a spam number in your app first, so the answer is cached. Ask us for a current test number.

Have that number call the phone.

A cached spam number is rejected before it rings. A number with a name shows a card over the call screen.

How the SDK decides, and why the first call always rings

Android gives a screening app a very short time to answer, and no network is safe in that window. The SDK therefore answers only from its cache.

The number is cached as spam, so the SDK rejects the call.

The number is cached as clean, so the call rings.

The number is not cached, so the call rings, and the SDK fetches the answer in the background for next time.

The last case is deliberate. Blocking a real call because a lookup was slow is worse than letting one spam call ring.

Call CallerAPI.prewarmAsync(number) when you already know a number is about to call, for example from your own recent calls list. That fills the cache in advance.

Turning the name card off

Some apps want blocking without a card:

This only hides the SDK name card. The SDK screening service still receives every call. Your code does not get the number, so this is not how you draw your own card.

Drawing your own name card

The SDK name card is not a theme. There is no callback and no color API.

To draw your own card you replace the SDK screening service, then call the lookup methods from yours.

Remove the SDK service from the merged manifest.

Declare your own CallScreeningService.

Answer Telecom from the cache.

Look up the name after you answer, then draw your card.

Add the tools namespace to the manifest, then remove the SDK service and add yours:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <application>
        <service
            android:name="com.callerapi.sdk.CallerScreeningService"
            tools:node="remove" />

        <service
            android:name=".MyCallScreeningService"
            android:permission="android.permission.BIND_SCREENING_SERVICE"
            android:exported="true">
            <intent-filter>
                <action android:name="android.telecom.CallScreeningService" />
            </intent-filter>
        </service>
    </application>
</manifest>

In your service, reply first. Then look up the name off the call path:

Call CallerAPI.register in your Application class first. Lookups fail if the SDK is not started.

Do not call isSpam or lookupLabel before respondToCall. Those use the network. Telecom drops screening if you wait.

You still need the call screening role. You still need Display over other apps if your card sits over the Phone UI. You cannot write into the system incoming-call heads-up. Your card sits under it, the same as the SDK card.

Flutter and React Native hosts do this in Android source, not in Dart or JavaScript.

Things that will confuse you

Nothing happens on any call. The role is not held. This is the most common problem, and it is silent, because Android never asks your app. Check with:

Calls get blocked but no name appears. The overlay permission is missing. Check CallerAPI.canShowIncomingCallerIdOverlay(this).

I turned the SDK card off, and my UI never appears. That flag only hides the SDK card. Replace the screening service if you want your own. See Drawing your own name card.

I wrote my own service, and the SDK card still appears. You did not remove com.callerapi.sdk.CallerScreeningService. Gradle still merges it, and Telecom can bind it instead of yours.

The role dialog never appears. Either the user already granted it, or another app holds it, or the device runs Android 9 or older.

The first spam call always rings. That is by design. See the section above.

Blocking works, and the dashboard shows zero blocks. You did not call setAnalyticsConsent(true).

iOS prerequisites

Methods

Troubleshooting

Before you start#

What you get#

What you do not have to write#

Step 1: ask for the role#

Step 2: turn on block reporting#

Step 3: test it#

How the SDK decides, and why the first call always rings#

Turning the name card off#

Drawing your own name card#

Things that will confuse you#

Next#