Get started with the XMTP Android SDK
Use the XMTP Kotlin SDK to build secure, private, and decentralized messaging into your Android app.
The guide provides some quickstart code, as well as a map to building a secure messaging app with XMTP, including support for:
- End-to-end encrypted direct message and group chat conversations
- Rich content types (attachments, reactions, replies, and more)
- Spam-free inboxes using user consent preferences
Quickstart
// 1. Create an EOA or SCW signer.
// Details depend on your app's wallet implementation.
class EOAWallet : SigningKey {
override val publicIdentity: PublicIdentity
get() = PublicIdentity(IdentityKind.ETHEREUM, key.publicAddress)
override val type: SignerType
get() = SignerType.EOA
override suspend fun sign(message: String): SignedData {
return SignedData(key.sign(message = message))
}
}
// 2. Create the XMTP client
val client = Client.create(
account = SigningKey,
options = ClientOptions(
ClientOptions.Api(XMTPEnvironment.PRODUCTION, true),
appContext = ApplicationContext(),
dbEncryptionKey = keyBytes // 32 bytes
)
)
// 3. Start conversations
val group = client.conversations.newGroup(inboxIds = listOf(bo.inboxId, caro.inboxId))
val groupWithMeta = client.conversations.newGroup(
inboxIds = listOf(bo.inboxId, caro.inboxId),
permissionLevel = GroupPermissionPreconfiguration.ALL_MEMBERS,
name = "The Group Name",
imageUrl = "www.groupImage.com",
description = "The description of the group"
)
// 4. Send messages
val dm = client.conversations.findOrCreateDm(recipientInboxId)
dm.send(text = "Hello world")
group.send(text = "Hello everyone")
// 5. List, stream, and sync
// List existing conversations
val conversations = client.conversations.list()
val filteredConversations = client.conversations.list(consentState = ConsentState.ALLOWED)
// Stream all new conversations and new messages from allowed conversations
client.conversations.streamAllMessages(consentStates = listOf(ConsentState.ALLOWED)).collect {
// Received a message
}
// Sync all new welcomes, preference updates, conversations,
// and messages from allowed conversations
client.conversations.syncAll(consentStates = ConsentState.ALLOWED)
🛠️ Phase 0: Explore XMTP developer tools
-
Use llms-full.txt to provide the full text of the XMTP developer documentation to an AI coding assistant.
-
Use xmtp.chat, the official web inbox for developers, to interact with and test your app
-
Run a local XMTP node for development and testing.
💬 Phase I: Build core messaging
-
Create a group chat or direct message (DM) conversation.
With XMTP, "conversation" refers to both group chat and DM conversations.
-
Send messages in a conversation.
-
Manage group chat permissions and metadata.
-
Be sure to observe rate limits.
📩 Phase II: Manage conversations and messages
-
List existing conversations from local storage.
-
Stream new conversations from the network.
-
Stream new messages from the network.
-
Sync new conversations from the network.
-
Sync a specific conversation's messages and preference updates from the network.
💅🏽 Phase III: Enhance the user experience
-
Implement user consent, which provides a consent value of either unknown, allowed or denied to each of a user's contacts. You can use these consent values to filter conversations. For example:
- Conversations with allowed contacts go to a user's main inbox
- Conversations with unknown contacts go to a possible spam tab
- Conversations with denied contacts are hidden from view.
-
Support rich content types.
- Attachments
- Single remote attachment
- Multiple remote attachments
- Attachments smaller than 1MB
- Reactions
- Replies
- Read receipts
- Onchain transactions
- Onchain transaction references
- Attachments
-
Implement push notifications, if applicable.
🧪 Phase IV: Test and debug
-
Stress and burn-in test your inbox app.
-
Found a bug or need help? Contact dev support.