@poolse/react-native-calls 0.5.0 → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Poolse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -14,9 +14,11 @@ can render against it unconditionally.
 import * as calls from '@poolse/react-native-calls';
 
 await calls.configure('https://api.poolse.dev', { smallIcon: 'ic_call', ringback: 'ringback' });
-const stop = calls.onCallState((s) => render(s));   // s: Snapshot | null
+const stop = calls.onCallState((s) => render(s)); // s: Snapshot | null
 await calls.place(conversationId, { media: 'audio', sessionToken });
-calls.answer(); calls.decline(); calls.hangUp();
+calls.answer();
+calls.decline();
+calls.hangUp();
 
 // Audio output: s.audioOutputs lists the phone, the speaker and every
 // connected headset/Bluetooth device by name; s.audioOutputId is the live one.
@@ -24,7 +26,38 @@ calls.setAudioOutput(s.audioOutputs[0].id);
 calls.setSpeaker(true); // the one-tap toggle, still there
 ```
 
+### Chat notifications
+
+poolse sends message notifications itself, with the push credentials you
+set up for calls. Register the devices (Android: the FCM token; iOS: the
+regular APNs token with `kind: 'alert'`, beside the VoIP one), and the
+core does the rest — one notification per conversation with every
+message a line in it, Reply and Mark as read straight from the
+notification (no app, no session), cleared when the chat is read on
+another device. Requires `expo-notifications` (a peer dependency).
+
+```ts
+calls.setActiveConversation(conversationId); // on screen: don't notify it
+calls.setActiveConversation(null); // left it, or app backgrounded
+
+// iOS, in your expo-notifications handler:
+Notifications.setNotificationHandler({
+  handleNotification: async (n) => {
+    const show = calls.shouldPresentMessage(n.request.content.data);
+    return {
+      shouldShowBanner: show,
+      shouldShowList: show,
+      shouldPlaySound: show,
+      shouldSetBadge: true,
+    };
+  },
+});
+// A tap opens the app: calls.conversationOfNotification(data) (iOS), or
+// takeCallAction()/onCallAction() with type 'open' (Android).
+```
+
 ## Layout
+
 - `src/` — the TypeScript API (this is what apps import).
 - `android/src/main/java/dev/poolse/callcore/` — the pure state machine
   and ports (contract cv 1).

package/android/src/main/AndroidManifest.xml

@@ -26,6 +26,10 @@
       android:name="dev.poolse.callcore.android.CallActionReceiver"
       android:exported="false" />
 
+    <receiver
+      android:name="dev.poolse.callcore.android.MessageActionReceiver"
+      android:exported="false" />
+
     <service
       android:name="dev.poolse.callcore.android.CallForegroundService"
       android:exported="false"

package/android/src/main/java/dev/poolse/callcore/android/CallCore.kt

@@ -384,6 +384,18 @@ class CallCore private constructor(context: Context) {
     /** The live core if one exists — never creates (cheap reads, e.g. getCallState). */
     fun peek(): CallCore? = instance
 
+    /** The configured API origin (restored from disk on a cold start), or null. */
+    fun apiBaseUrl(context: Context): String? {
+      if (config == null) restoreConfig(context.applicationContext)
+      return config?.apiBaseUrl?.ifEmpty { null }
+    }
+
+    /** The configured notification icon (restored from disk on a cold start). */
+    fun smallIcon(context: Context): Int {
+      if (config == null) restoreConfig(context.applicationContext)
+      return config?.smallIcon ?: context.applicationInfo.icon
+    }
+
     internal fun peekConfig(): CallCoreConfig? = config
 
     internal fun requireConfig(): CallCoreConfig =

package/android/src/main/java/dev/poolse/callcore/android/CallMessagingService.kt

@@ -13,8 +13,8 @@ import dev.poolse.callcore.RingContext
  * everything else keep working unchanged.
  *
  * Contract: data-only messages — rings with `type: "call"`, control
- * pushes (`ring_ended`, `finished`) with `type: "call_event"`
- * (CONTRACT.md §5).
+ * pushes (`ring_ended`, `finished`) and the missed-call notification
+ * (`missed`) with `type: "call_event"` (CONTRACT.md §5).
  */
 class CallMessagingService : FirebaseMessagingService() {
 
@@ -35,6 +35,17 @@ class CallMessagingService : FirebaseMessagingService() {
     // type=call_event so old JS Android builds — which ring on ANY
     // type=call — ignore them. Everything else belongs to the host.
     val type = data["type"]
+    if (type == "message") {
+      // Chat notifications (§5.5): posted here so they appear with the
+      // app killed, grouped per conversation.
+      if (CallCore.getOrNull(this) == null) return
+      val conversationId = data["conversation_id"] ?: return
+      when (data["event"]) {
+        "new" -> MessageNotifications.onNew(this, data, CallCore.smallIcon(this))
+        "read" -> MessageNotifications.clear(this, conversationId)
+      }
+      return
+    }
     if (type != "call" && type != "call_event") {
       forwardToHost { it.onMessageReceived(message) }
       return
@@ -43,6 +54,11 @@ class CallMessagingService : FirebaseMessagingService() {
     // Never configured on this install: nothing can answer a call, and
     // throwing here would crash the messaging process.
     val core = CallCore.getOrNull(this) ?: return
+    if (data["event"] == "missed") {
+      // A notification, not call state: the call is already over.
+      MissedCallNotification.show(this, data, CallCore.smallIcon(this))
+      return
+    }
     // A type=call push without an event is a legacy-shaped ring.
     val event = data["event"]?.ifEmpty { null } ?: if (type == "call") "ring" else return
     when (event) {

package/android/src/main/java/dev/poolse/callcore/android/MessageNotifications.kt

@@ -0,0 +1,340 @@
+package dev.poolse.callcore.android
+
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.os.Build
+import android.util.Log
+import androidx.core.app.NotificationCompat
+import androidx.core.app.NotificationManagerCompat
+import androidx.core.app.Person
+import androidx.core.app.RemoteInput
+import okhttp3.MediaType.Companion.toMediaType
+import okhttp3.Request
+import okhttp3.RequestBody.Companion.toRequestBody
+import org.json.JSONArray
+import org.json.JSONObject
+import java.util.UUID
+
+/**
+ * Chat notifications on Android (CONTRACT.md §5.5), WhatsApp-style.
+ *
+ * One notification per conversation, in MessagingStyle: each new message
+ * becomes a line in it ("Ana: on my way") rather than a new card, and a
+ * group summary collects every chat. Reply (inline text) and Mark as
+ * read run natively, authorized by the reply grant the push carried, so
+ * they work with the app killed and the phone locked.
+ *
+ * Android cannot read back the lines of a posted notification, so the
+ * last few lines per conversation are kept in a small preferences file
+ * and the notification is rebuilt from them on every message. They are
+ * dropped the moment the conversation is read, here or elsewhere.
+ */
+object MessageNotifications {
+  const val CHANNEL_ID = "poolse_messages"
+  private const val GROUP_KEY = "dev.poolse.messages"
+  private const val SUMMARY_ID = 0x504F4F4C // "POOL"
+  private const val PREFS = "dev.poolse.messages"
+  private const val MAX_LINES = 7
+  internal const val KEY_REPLY = "poolse_reply_text"
+  internal const val ACTION_REPLY = "dev.poolse.callcore.message.REPLY"
+  internal const val ACTION_READ = "dev.poolse.callcore.message.READ"
+  internal const val EXTRA_CONVERSATION = "poolse_message_conversation"
+  private const val TAG = "PoolseMessages"
+
+  // A message notification that waited this long for the phone to come
+  // online is history.
+  private const val STALE_MS = 24 * 60 * 60 * 1000L
+
+  /**
+   * The conversation on screen in the app, set by the host. Its messages
+   * are not notified — the user is reading them.
+   */
+  @Volatile var activeConversationId: String? = null
+
+  /** A `type: "message", event: "new"` push. */
+  fun onNew(context: Context, data: Map<String, String>, smallIcon: Int) {
+    val conversationId = data["conversation_id"] ?: return
+    if (conversationId == activeConversationId) return
+    val sentAt = data["sent_at"]?.toLongOrNull() ?: System.currentTimeMillis()
+    if (System.currentTimeMillis() - sentAt > STALE_MS) return
+
+    val state = load(context, conversationId) ?: Conversation(conversationId)
+    state.title = data["conversation_name"]?.ifBlank { null } ?: state.title
+    state.group = data["group"] == "1"
+    data["reply_grant"]?.ifBlank { null }?.let { state.grant = it }
+    val messageId = data["message_id"]
+    if (messageId == null || state.lines.none { it.id == messageId }) {
+      state.lines += Line(
+        id = messageId,
+        sender = data["sender_name"]?.ifBlank { null } ?: "Someone",
+        senderKey = data["sender_user_id"],
+        text = data["text"] ?: "",
+        at = sentAt,
+        self = false,
+      )
+      while (state.lines.size > MAX_LINES) state.lines.removeAt(0)
+    }
+    save(context, state)
+    post(context, state, smallIcon, alert = true)
+  }
+
+  /** The conversation was read (here, or on another device): clear it. */
+  fun clear(context: Context, conversationId: String) {
+    prefs(context).edit().remove(key(conversationId)).apply()
+    runCatching { NotificationManagerCompat.from(context).cancel(notificationId(conversationId)) }
+    refreshSummary(context, CallCore.smallIcon(context))
+  }
+
+  /** The reply went through: show it as the user's line and stop the spinner. */
+  internal fun onReplied(context: Context, conversationId: String, text: String, ok: Boolean) {
+    val state = load(context, conversationId) ?: return
+    state.lines += Line(
+      id = null,
+      sender = "You",
+      senderKey = null,
+      text = if (ok) text else "Not sent: $text",
+      at = System.currentTimeMillis(),
+      self = true,
+    )
+    while (state.lines.size > MAX_LINES) state.lines.removeAt(0)
+    save(context, state)
+    post(context, state, CallCore.smallIcon(context), alert = false)
+  }
+
+  internal fun grantFor(context: Context, conversationId: String): String? =
+    load(context, conversationId)?.grant
+
+  // ── building ────────────────────────────────────────────────────────
+
+  private fun post(context: Context, state: Conversation, smallIcon: Int, alert: Boolean) {
+    ensureChannel(context)
+    val me = Person.Builder().setName("You").build()
+    val style = NotificationCompat.MessagingStyle(me)
+      .setGroupConversation(state.group)
+    if (state.group) style.conversationTitle = state.title
+    for (line in state.lines) {
+      val person = if (line.self) null else Person.Builder().setName(line.sender).setKey(line.senderKey).build()
+      style.addMessage(NotificationCompat.MessagingStyle.Message(line.text, line.at, person))
+    }
+
+    val id = notificationId(state.id)
+    val builder = NotificationCompat.Builder(context, CHANNEL_ID)
+      .setSmallIcon(smallIcon)
+      .setStyle(style)
+      .setCategory(NotificationCompat.CATEGORY_MESSAGE)
+      .setPriority(NotificationCompat.PRIORITY_HIGH)
+      .setGroup(GROUP_KEY)
+      .setAutoCancel(true)
+      .setOnlyAlertOnce(!alert)
+      .setWhen(state.lines.lastOrNull()?.at ?: System.currentTimeMillis())
+      .setNumber(state.lines.count { !it.self })
+    openIntent(context, state.id, id)?.let(builder::setContentIntent)
+
+    if (state.grant != null) {
+      val remoteInput = RemoteInput.Builder(KEY_REPLY).setLabel("Message").build()
+      val reply = NotificationCompat.Action.Builder(0, "Reply", actionIntent(context, ACTION_REPLY, state.id, id + 1, mutable = true))
+        .addRemoteInput(remoteInput)
+        .setAllowGeneratedReplies(true)
+        .setSemanticAction(NotificationCompat.Action.SEMANTIC_ACTION_REPLY)
+        .setShowsUserInterface(false)
+        .build()
+      val read = NotificationCompat.Action.Builder(0, "Mark as read", actionIntent(context, ACTION_READ, state.id, id + 2, mutable = false))
+        .setSemanticAction(NotificationCompat.Action.SEMANTIC_ACTION_MARK_AS_READ)
+        .setShowsUserInterface(false)
+        .build()
+      builder.addAction(reply).addAction(read)
+    }
+
+    try {
+      NotificationManagerCompat.from(context).notify(id, builder.build())
+    } catch (e: SecurityException) {
+      Log.w(TAG, "message notification refused (POST_NOTIFICATIONS?)", e)
+      return
+    }
+    refreshSummary(context, smallIcon)
+  }
+
+  /** The group's summary: "5 messages from 2 chats". Gone with the last chat. */
+  private fun refreshSummary(context: Context, smallIcon: Int) {
+    val all = prefs(context).all.keys.filter { it.startsWith("conv:") }
+      .mapNotNull { load(context, it.removePrefix("conv:")) }
+    val manager = NotificationManagerCompat.from(context)
+    if (all.isEmpty()) {
+      runCatching { manager.cancel(SUMMARY_ID) }
+      return
+    }
+    val messages = all.sumOf { c -> c.lines.count { !it.self } }
+    val text = if (all.size == 1) "$messages new messages" else "$messages messages from ${all.size} chats"
+    val summary = NotificationCompat.Builder(context, CHANNEL_ID)
+      .setSmallIcon(smallIcon)
+      .setContentTitle(text)
+      .setStyle(NotificationCompat.InboxStyle().setSummaryText(text))
+      .setGroup(GROUP_KEY)
+      .setGroupSummary(true)
+      .setGroupAlertBehavior(NotificationCompat.GROUP_ALERT_CHILDREN)
+      .setAutoCancel(true)
+      .build()
+    runCatching { manager.notify(SUMMARY_ID, summary) }
+  }
+
+  private fun openIntent(context: Context, conversationId: String, requestCode: Int): PendingIntent? {
+    val intent = context.packageManager.getLaunchIntentForPackage(context.packageName) ?: return null
+    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_SINGLE_TOP)
+      .putExtra(MissedCallNotification.EXTRA_ACTION, MissedCallNotification.ACTION_OPEN)
+      .putExtra(MissedCallNotification.EXTRA_CONVERSATION_ID, conversationId)
+    return PendingIntent.getActivity(
+      context,
+      requestCode,
+      intent,
+      PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+    )
+  }
+
+  private fun actionIntent(context: Context, action: String, conversationId: String, requestCode: Int, mutable: Boolean): PendingIntent {
+    val intent = Intent(context, MessageActionReceiver::class.java)
+      .setAction(action)
+      .putExtra(EXTRA_CONVERSATION, conversationId)
+    // RemoteInput writes the typed text into the intent: it must be mutable.
+    val mutability = if (mutable && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+      PendingIntent.FLAG_MUTABLE
+    } else {
+      PendingIntent.FLAG_IMMUTABLE
+    }
+    return PendingIntent.getBroadcast(context, requestCode, intent, PendingIntent.FLAG_UPDATE_CURRENT or mutability)
+  }
+
+  private fun ensureChannel(context: Context) {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+    val manager = context.getSystemService(NotificationManager::class.java)
+    if (manager.getNotificationChannel(CHANNEL_ID) != null) return
+    manager.createNotificationChannel(
+      NotificationChannel(CHANNEL_ID, "Messages", NotificationManager.IMPORTANCE_HIGH).apply {
+        lockscreenVisibility = NotificationCompat.VISIBILITY_PRIVATE
+      },
+    )
+  }
+
+  private fun notificationId(conversationId: String) = ("msg:$conversationId").hashCode()
+
+  // ── storage ─────────────────────────────────────────────────────────
+
+  internal data class Line(
+    val id: String?,
+    val sender: String,
+    val senderKey: String?,
+    val text: String,
+    val at: Long,
+    val self: Boolean,
+  )
+
+  internal class Conversation(
+    val id: String,
+    var title: String? = null,
+    var group: Boolean = false,
+    var grant: String? = null,
+    val lines: MutableList<Line> = mutableListOf(),
+  )
+
+  private fun prefs(context: Context) =
+    context.applicationContext.getSharedPreferences(PREFS, Context.MODE_PRIVATE)
+
+  private fun key(conversationId: String) = "conv:$conversationId"
+
+  private fun load(context: Context, conversationId: String): Conversation? {
+    val raw = prefs(context).getString(key(conversationId), null) ?: return null
+    return runCatching {
+      val o = JSONObject(raw)
+      val lines = o.optJSONArray("lines") ?: JSONArray()
+      Conversation(
+        id = conversationId,
+        title = o.optString("title").ifBlank { null },
+        group = o.optBoolean("group"),
+        grant = o.optString("grant").ifBlank { null },
+        lines = MutableList(lines.length()) { i ->
+          val l = lines.getJSONObject(i)
+          Line(
+            id = l.optString("id").ifBlank { null },
+            sender = l.optString("sender"),
+            senderKey = l.optString("key").ifBlank { null },
+            text = l.optString("text"),
+            at = l.optLong("at"),
+            self = l.optBoolean("self"),
+          )
+        },
+      )
+    }.getOrNull()
+  }
+
+  private fun save(context: Context, c: Conversation) {
+    val lines = JSONArray()
+    for (l in c.lines) {
+      lines.put(
+        JSONObject()
+          .put("id", l.id ?: "")
+          .put("sender", l.sender)
+          .put("key", l.senderKey ?: "")
+          .put("text", l.text)
+          .put("at", l.at)
+          .put("self", l.self),
+      )
+    }
+    val o = JSONObject()
+      .put("title", c.title ?: "")
+      .put("group", c.group)
+      .put("grant", c.grant ?: "")
+      .put("lines", lines)
+    prefs(context).edit().putString(key(c.id), o.toString()).apply()
+  }
+}
+
+/**
+ * Reply / Mark as read, tapped on a message notification. Posts to the
+ * notification-action endpoints with the conversation's reply grant —
+ * no app, no session — on a background thread kept alive by goAsync().
+ */
+class MessageActionReceiver : BroadcastReceiver() {
+  override fun onReceive(context: Context, intent: Intent) {
+    val conversationId = intent.getStringExtra(MessageNotifications.EXTRA_CONVERSATION) ?: return
+    val app = context.applicationContext
+    val grant = MessageNotifications.grantFor(app, conversationId)
+    val base = CallCore.apiBaseUrl(app)
+
+    when (intent.action) {
+      MessageNotifications.ACTION_REPLY -> {
+        val text = RemoteInput.getResultsFromIntent(intent)
+          ?.getCharSequence(MessageNotifications.KEY_REPLY)?.toString()?.trim().orEmpty()
+        if (text.isEmpty() || grant == null || base == null) return
+        val pending = goAsync()
+        Thread {
+          val body = JSONObject().put("body", text).put("id", UUID.randomUUID().toString())
+          val ok = post("$base/v1/notifications/reply", grant, body)
+          MessageNotifications.onReplied(app, conversationId, text, ok)
+          pending.finish()
+        }.start()
+      }
+      MessageNotifications.ACTION_READ -> {
+        // Optimistic: the notification goes now; the server catches up.
+        MessageNotifications.clear(app, conversationId)
+        if (grant == null || base == null) return
+        val pending = goAsync()
+        Thread {
+          post("$base/v1/notifications/read", grant, JSONObject())
+          pending.finish()
+        }.start()
+      }
+    }
+  }
+
+  private fun post(url: String, grant: String, body: JSONObject): Boolean = runCatching {
+    val request = Request.Builder()
+      .url(url)
+      .header("Authorization", "Bearer $grant")
+      .post(body.toString().toRequestBody("application/json".toMediaType()))
+      .build()
+    CallHttpClient.defaultClient().newCall(request).execute().use { it.isSuccessful }
+  }.onFailure { Log.w("PoolseMessages", "notification action failed", it) }.getOrDefault(false)
+}

package/android/src/main/java/dev/poolse/callcore/android/MissedCallNotification.kt

@@ -0,0 +1,103 @@
+package dev.poolse.callcore.android
+
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import android.os.Build
+import android.util.Log
+import androidx.core.app.NotificationCompat
+import androidx.core.app.NotificationManagerCompat
+
+/**
+ * "Jasir — Missed voice call  [Call back]", posted natively from the
+ * missed-call push (`event: "missed"`) so it shows with the app closed.
+ *
+ * Both the tap and Call back open the app through its launch activity,
+ * carrying the action in extras ([EXTRA_ACTION] …). The bridge reads
+ * them — `takeCallAction()` on a cold start, `onCallAction` while
+ * running — and the host opens the conversation or places the call.
+ * Placing needs the user's session, which only the app has; that is
+ * why Call back does not dial from here.
+ */
+object MissedCallNotification {
+  const val CHANNEL_ID = "poolse_missed_calls"
+  const val EXTRA_ACTION = "poolse_call_action"
+  const val EXTRA_CONVERSATION_ID = "poolse_call_action_conversation"
+  const val EXTRA_CALL_ID = "poolse_call_action_call"
+  const val EXTRA_MEDIA = "poolse_call_action_media"
+  const val ACTION_OPEN = "open"
+  const val ACTION_CALL_BACK = "call_back"
+  private const val TAG = "PoolseMissedCall"
+
+  // A missed call FCM held while the phone was off for days is history.
+  private const val STALE_MS = 24 * 60 * 60 * 1000L
+
+  fun show(context: Context, data: Map<String, String>, smallIcon: Int) {
+    val callId = data["call_id"] ?: return
+    val conversationId = data["conversation_id"] ?: return
+    val sentAt = data["sent_at"]?.toLongOrNull()
+    if (sentAt != null && System.currentTimeMillis() - sentAt > STALE_MS) return
+    val media = if (data["media"] == "video") "video" else "audio"
+    val title = data["title"]?.ifBlank { null }
+      ?: data["caller_name"]?.ifBlank { null }
+      ?: "Missed call"
+    val body = data["body"]?.ifBlank { null }
+      ?: if (media == "video") "Missed video call" else "Missed voice call"
+
+    ensureChannel(context)
+    val id = notificationId(callId)
+
+    fun launch(action: String, requestOffset: Int): PendingIntent? {
+      val intent = context.packageManager.getLaunchIntentForPackage(context.packageName) ?: return null
+      intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_SINGLE_TOP)
+        .putExtra(EXTRA_ACTION, action)
+        .putExtra(EXTRA_CONVERSATION_ID, conversationId)
+        .putExtra(EXTRA_CALL_ID, callId)
+        .putExtra(EXTRA_MEDIA, media)
+      return PendingIntent.getActivity(
+        context,
+        id + requestOffset,
+        intent,
+        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+      )
+    }
+
+    val builder = NotificationCompat.Builder(context, CHANNEL_ID)
+      .setSmallIcon(smallIcon)
+      .setContentTitle(title)
+      .setContentText(body)
+      .setCategory(NotificationCompat.CATEGORY_MISSED_CALL)
+      .setPriority(NotificationCompat.PRIORITY_DEFAULT)
+      .setAutoCancel(true)
+      .setWhen(sentAt ?: System.currentTimeMillis())
+      .setShowWhen(true)
+    launch(ACTION_OPEN, 0)?.let(builder::setContentIntent)
+    launch(ACTION_CALL_BACK, 1)?.let { builder.addAction(0, "Call back", it) }
+
+    try {
+      NotificationManagerCompat.from(context).notify(id, builder.build())
+    } catch (e: SecurityException) {
+      Log.w(TAG, "missed-call notification refused (POST_NOTIFICATIONS?)", e)
+    }
+  }
+
+  /** Clear it once the user acted on it from the app (its buttons do not auto-cancel). */
+  fun cancel(context: Context, callId: String) {
+    runCatching { NotificationManagerCompat.from(context).cancel(notificationId(callId)) }
+  }
+
+  private fun notificationId(callId: String) = ("missed:$callId").hashCode()
+
+  private fun ensureChannel(context: Context) {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+    val manager = context.getSystemService(NotificationManager::class.java)
+    if (manager.getNotificationChannel(CHANNEL_ID) != null) return
+    manager.createNotificationChannel(
+      NotificationChannel(CHANNEL_ID, "Missed calls", NotificationManager.IMPORTANCE_DEFAULT).apply {
+        lockscreenVisibility = NotificationCompat.VISIBILITY_PRIVATE
+      },
+    )
+  }
+}

package/android/src/main/java/expo/modules/poolsecalls/PoolseCallsModule.kt

@@ -8,6 +8,8 @@ import android.os.Build
 import android.provider.Settings
 import android.util.Log
 import dev.poolse.callcore.android.CallCore
+import dev.poolse.callcore.android.MessageNotifications
+import dev.poolse.callcore.android.MissedCallNotification
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
 
@@ -30,7 +32,7 @@ class PoolseCallsModule : Module() {
   override fun definition() = ModuleDefinition {
     Name("PoolseCalls")
 
-    Events("onCallState")
+    Events("onCallState", "onCallAction")
 
     // <CallVideoView>: renders a participant's (or our own) camera.
     View(PoolseCallVideoView::class) {
@@ -93,6 +95,21 @@ class PoolseCallsModule : Module() {
       core()?.onCallFinished(callId, reason?.ifEmpty { null })
     }
 
+    // A missed-call notification's tap / Call back. Cold start: the
+    // launch intent still carries it — the host reads it once on mount.
+    // Running app: the tap arrives as a new intent.
+    Function("takeCallAction") { appContext.currentActivity?.intent?.let(::consumeCallAction) }
+    OnNewIntent { intent ->
+      consumeCallAction(intent)?.let { sendEvent("onCallAction", it) }
+    }
+
+    // The chat on screen: its messages are not notified, and opening it
+    // clears what was already shown for it.
+    Function("setActiveConversation") { conversationId: String? ->
+      MessageNotifications.activeConversationId = conversationId
+      if (conversationId != null) context?.let { MessageNotifications.clear(it, conversationId) }
+    }
+
     // Android 14+: full-screen intents need a user grant for non-dialer apps.
     Function("canUseFullScreenIntent") {
       val ctx = context ?: return@Function true
@@ -130,6 +147,31 @@ class PoolseCallsModule : Module() {
 
   private fun core(): CallCore? = context?.let(CallCore::getOrNull)
 
+  /**
+   * The call action an intent carries, removed from it so a later read
+   * (rotation, re-mount) cannot replay it. Acting on it from the app
+   * clears its notification too: action buttons do not auto-cancel.
+   */
+  private fun consumeCallAction(intent: Intent): Map<String, Any?>? {
+    val action = intent.getStringExtra(MissedCallNotification.EXTRA_ACTION) ?: return null
+    val conversationId = intent.getStringExtra(MissedCallNotification.EXTRA_CONVERSATION_ID) ?: return null
+    val callId = intent.getStringExtra(MissedCallNotification.EXTRA_CALL_ID)
+    val media = intent.getStringExtra(MissedCallNotification.EXTRA_MEDIA) ?: "audio"
+    for (key in listOf(
+      MissedCallNotification.EXTRA_ACTION,
+      MissedCallNotification.EXTRA_CONVERSATION_ID,
+      MissedCallNotification.EXTRA_CALL_ID,
+      MissedCallNotification.EXTRA_MEDIA,
+    )) intent.removeExtra(key)
+    if (callId != null) context?.let { MissedCallNotification.cancel(it, callId) }
+    return mapOf(
+      "type" to action,
+      "conversationId" to conversationId,
+      "callId" to callId,
+      "media" to media,
+    )
+  }
+
   private companion object {
     const val TAG = "PoolseCalls"
   }