Criar uma notificação de estilo de chamada para apps de ligações

No Android 12.0 (nível 31 da API) e versões mais recentes, o sistema oferece o modelo de notificação CallStyle para distinguir as notificações de chamada de outros tipos de notificações. Use esse modelo para criar notificações de chamadas recebidas ou em andamento. O modelo é compatível com notificações de formato grande que incluem informações do autor da chamada e ações necessárias, como atender ou recusar chamadas.

Como as chamadas recebidas e em andamento são eventos de alta prioridade, essas notificações recebem prioridade máxima na aba de notificações. Essa classificação também permite que o sistema encaminhe essas chamadas priorizadas para outros dispositivos.

O modelo de notificação CallStyle inclui as seguintes ações obrigatórias:

  • Atender ou Recusar para ligações recebidas.
  • Desligar para chamadas em andamento.
  • Atender ou Desligar para o Filtro de Ligações.

As ações nesse estilo aparecem como botões, e o sistema adiciona automaticamente ícones e textos adequados. Não é possível rotular os botões manualmente. Para mais informações sobre os princípios de design de notificações, consulte Notificações.

Notificações de estilo de ligação com botões rotulados
Figura 1. Modelo CallStyle para chamadas recebidas e em andamento.

As ações necessárias são transmitidas como intents, como hangupIntent e answerIntent nas seções a seguir. Cada um deles é uma referência a um token mantido pelo sistema. O token é um objeto leve que pode ser transmitido entre diferentes apps e processos. O sistema é responsável por gerenciar o ciclo de vida do token e garantir que o PendingIntent seja utilizável, mesmo que o app que o criou não esteja mais em execução. Ao dar um PendingIntent a outro app, você concede a ele permissão para realizar a operação especificada, como recusar ou atender. Essa permissão é concedida mesmo que o app que criou a intent não esteja em execução. Para saber mais, consulte a documentação de referência para PendingIntent.

No Android 14 (nível 34 da API) e versões mais recentes, é possível configurar as notificações de chamada para que não sejam dispensáveis. Para fazer isso, use as notificações do CallStyle com o Notification.FLAG_ONGOING_EVENT pelo Notification.Builder#setOngoing(true).

Confira a seguir exemplos de como usar vários métodos com a notificação CallStyle.

// Create a new call, setting incoming caller.
val incomingCaller = Person.Builder()
    .setName("Jane Doe")
    .setImportant(true)
    .build()

Chamada recebida

Use o método forIncomingCall() para criar uma notificação de estilo de chamada para uma ligação recebida.

// For demonstrative purposes only, should use a well-defined Intents.
val contentIntent =
    PendingIntent.getActivity(context, 0, Intent(), PendingIntent.FLAG_IMMUTABLE)
val declineIntent =
    PendingIntent.getActivity(context, 0, Intent(), PendingIntent.FLAG_IMMUTABLE)
val hangupIntent = PendingIntent.getActivity(context, 0, Intent(), PendingIntent.FLAG_IMMUTABLE)
val answerIntent = PendingIntent.getActivity(context, 0, Intent(), PendingIntent.FLAG_IMMUTABLE)
// Create a call style notification for an incoming call.
val builderForIncomingCall = NotificationCompat.Builder(context, CHANNEL_ID)
    .setContentIntent(contentIntent)
    .setSmallIcon(R.drawable.ic_logo)
    .setStyle(
        NotificationCompat.CallStyle.forIncomingCall(incomingCaller, declineIntent, answerIntent))
    .addPerson(incomingCaller)

Chamada em andamento

Use o método forOngoingCall() para criar uma notificação de estilo de chamada para uma chamada em andamento.

// Create a call style notification for an ongoing call.
val builderForOngoingCall = NotificationCompat.Builder(context, CHANNEL_ID)
    .setContentIntent(contentIntent)
    .setSmallIcon(R.drawable.ic_logo)
    .setStyle(
        NotificationCompat.CallStyle.forOngoingCall(callerAtOtherEnd, hangupIntent))
    .addPerson(caller)

Filtrar uma ligação

Use o método forScreeningCall() para criar uma notificação de estilo de chamada para filtrar uma chamada.

// Create a call style notification for screening a call.
val builder = NotificationCompat.Builder(context, CHANNEL_ID)
    .setContentIntent(contentIntent)
    .setSmallIcon(R.drawable.ic_logo)
    .setStyle(
        NotificationCompat.CallStyle.forScreeningCall(caller, hangupIntent, answerIntent))
    .addPerson(caller)

Oferecer compatibilidade com mais versões do Android

Associe as notificações de CallStyle nas versões 30 ou anteriores da API a um serviço em primeiro plano para atribuir a elas a classificação alta que recebem no nível 31 ou mais recente da API. Além disso, as notificações de CallStyle na versão 30 ou anterior da API podem alcançar uma classificação semelhante ao marcar a notificação como colorida usando o método setColorized().

Use as APIs Telecom com notificações do CallStyle. Para mais informações, consulte Visão geral do framework de telecomunicações.