Content Providers

Build Android apps and connected devices that integrate with Beeper using standard Android ContentProvider APIs. Content providers encapsulate data and provide mechanisms for defining data security, serving as the standard interface between processes.

Experimental

Content providers are experimental and APIs are subject to change.

Get in touch

What You Can Build

• Universal Search - Search across all chats and messages
• Widgets & Dashboards - Display chat summaries and unread counts
• Automation - Send messages and react to changes
• Wearables - Integrate with watches and IoT devices

Key Features

• Authority: com.beeper.api
• Permissions: Runtime (request at first use)
• Data Access: Chats, messages, contacts
• Operations: Query, insert, observe changes
• Protocol Support: WhatsApp, Telegram, Signal, and more

Quick Start

1. Add permissions to your manifest

   AndroidManifest.xml

   <uses-permission android:name="com.beeper.android.permission.READ_PERMISSION" />
   <uses-permission android:name="com.beeper.android.permission.SEND_PERMISSION" />

   Caution

   These are custom Beeper permissions. Declare them in the manifest and request them at runtime with a permission prompt.

   // Request at runtime (e.g., in an Activity or Fragment)
   val requestPermissions = registerForActivityResult(
       ActivityResultContracts.RequestMultiplePermissions()
   ) { results ->
       val hasRead = results["com.beeper.android.permission.READ_PERMISSION"] == true
       val hasSend = results["com.beeper.android.permission.SEND_PERMISSION"] == true
       // Handle granted/denied states
   }
   
   requestPermissions.launch(arrayOf(
       "com.beeper.android.permission.READ_PERMISSION",
       "com.beeper.android.permission.SEND_PERMISSION"
   ))

2. Query recent chats

   import androidx.core.net.toUri
   
   val uri = "content://com.beeper.api/chats?limit=50".toUri()
   contentResolver.query(uri, null, null, null, null)?.use { cursor ->
       val titleIdx = cursor.getColumnIndexOrThrow("title")
       val previewIdx = cursor.getColumnIndexOrThrow("messagePreview")
       val unreadIdx = cursor.getColumnIndexOrThrow("unreadCount")
   
       while (cursor.moveToNext()) {
           val title = cursor.getString(titleIdx)
           val preview = cursor.getString(previewIdx)
           val unread = cursor.getInt(unreadIdx)
           // Display chat info in your UI
       }
   }

3. Send a message

   import android.net.Uri
   import androidx.core.net.toUri
   
   val message = "Hello from my app!"
   val roomId = "!room:server.com"
   
   val result = contentResolver.insert(
       ("content://com.beeper.api/messages?" +
        "roomId=$roomId&text=${Uri.encode(message)}").toUri(),
       null
   )
   
   result?.let {
       val messageId = it.getQueryParameter("messageId")
       // Message sent successfully
   }

4. Observe changes

   import android.os.Handler
   import android.os.Looper
   import android.database.ContentObserver
   import androidx.core.net.toUri
   
   contentResolver.registerContentObserver(
       "content://com.beeper.api/chats".toUri(),
       true,
       object : ContentObserver(Handler(Looper.getMainLooper())) {
           override fun onChange(selfChange: Boolean) {
               // Re-query and refresh your UI
           }
       }
   )

   Note

   Only content://com.beeper.api/chats currently emits change notifications. Observers for messages or contacts will not fire.

Common Use Cases

Unread Counter

// Get total unread count across all chats
val uri = "content://com.beeper.api/chats/count?isUnread=1".toUri()
val cursor = contentResolver.query(uri, null, null, null, null)
val unreadTotal = cursor?.use {
    if (it.moveToFirst()) {
        it.getInt(it.getColumnIndexOrThrow("count"))
    } else 0
} ?: 0

Search Messages

// Search with surrounding context
val searchTerm = "meeting"
val uri = ("content://com.beeper.api/messages?" +
          "query=${Uri.encode(searchTerm)}" +
          "&contextBefore=2&contextAfter=2").toUri()

contentResolver.query(uri, null, null, null, null)?.use { cursor ->
    val textIdx = cursor.getColumnIndexOrThrow("text_content")
    val matchIdx = cursor.getColumnIndexOrThrow("is_search_match")

    while (cursor.moveToNext()) {
        val text = cursor.getString(textIdx)
        val isMatch = cursor.getInt(matchIdx) == 1
        // Highlight matches in UI
    }
}

Protocol Filter

// Get WhatsApp chats only
val uri = "content://com.beeper.api/chats?protocol=whatsapp".toUri()
contentResolver.query(uri, null, null, null, null)?.use { cursor ->
    // Process WhatsApp-specific chats
}

Performance Tips

Best Practices

1. Always Set Limits - Default limit is 100, but always specify limit to avoid large queries
2. Use Filters - Filter by roomIds, protocol, or other parameters to reduce data
3. Batch Operations - Combine multiple filters in one query instead of multiple queries
4. Lifecycle Awareness - Register/unregister observers with your component lifecycle

Supported Protocols

Protocol	Identifier	Features
WhatsApp	whatsapp	Full
Telegram	telegram	Full
Signal	signal	Full
Matrix/Beeper	beeper, matrix	Full
Discord	discord	Full
Slack	slack	Full
Google Messages	gmessages	Full
Others	Various	Query

Learn More

• API Reference → - Complete API documentation for all endpoints
• Integration Guide → - Permissions, notifications, and troubleshooting
• Android Docs → - Official ContentProvider documentation