Topics_

Allow groups of users to subscribe to a common topic and receive the same notifications.

2 min read

In Appwrite Messaging, you can use topics to deliver messages to groups of users at once.

Topics and targets

A user can have multiple targets, such as emails, phone numbers, and devices with your app installed. These targets can subscribe to a topic, so when messages are published to a topic, all subscribed targets receive the message.

Organizing topics

A topic should have semantic meaning. For example, a topic can represent a group of customers that receiving a common announcemennt or publishing public updates. It's important to keep privacy in mind when using topics. Prefer sending private information like chat messages by addressing individual targets attached to a user.

Topics are optimized for delivering the same message to large groups of users. If you need to deliver messages to all devices of the same user, you can find a user's targets by calling account.get().

Create a topic

You can create topics

Navigate to your Appwrite Console > Messaging > Topics > Create topic.

const sdk = require('node-appwrite');

// Init SDK
const client = new sdk.Client();

const messaging = new sdk.Messaging(client);

client
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<PROJECT_ID>')                 // Your project ID
    .setKey('919c2d18fb5d4...a2ae413da83346ad2')                  // Your secret API key
;

const topic = messaging.createTopic({
    topicId: '<TOPIC_ID>',
    name: '<NAME>',
    subscribe: ['<ROLE>']
});

Before proceeding

Ensure you install the CLI, log in to your Appwrite account, and initialize your Appwrite project.

You can create a topic using the CLI command appwrite init topics to initialize a topic.

Bash

appwrite init topics

You can now push your topics with the following command:

Bash

appwrite push topics

This will create your topic in the Console with all of your appwrite.config.json configurations.

Permissions

Before you can subscribe to a topic, a user needs the appropriate permission. You can set permission by navigating to Messaging > Topics > select a topic to configure > Subscription access.

During development, you can subscribe targets to a topic for testing right in the Appwrite console.

Navigate to your Appwrite Console > Messaging > Topics > click on your topic > Subscribers > Create topic > Add subscriber.

If you can't find the targets you'd like to add, see the targets page.

const sdk = require('node-appwrite');

const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')    // Your API Endpoint
    .setProject('<PROJECT_ID>')                    // Your project ID
    .setJWT('eyJhbVCJ9.eyJ...');                    // Your secret JSON Web Token

const messaging = new sdk.Messaging(client);

const subscriber = await messaging.createSubscriber({
    topicId: '<TOPIC_ID>',
    subscriberId: '<SUBSCRIBER_ID>',
    targetId: '<TARGET_ID>'
});

Was this page helpful?

Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.

Topics and targets

Organizing topics

Create a topic

Permissions

Subscribe targets to a topic