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.
Learn more about targets
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://cloud.appwrite.io/v1') // Your API Endpoint
.setProject('<PROJECT_ID>') // Your project ID
.setKey('919c2d18fb5d4...a2ae413da83346ad2') // Your secret API key
;
const topic = messaging.createTopic(
'[TOPIC_ID]', // topicId
'[NAME]', // name
'[ROLES]' // permission roles for who can subscribe
);
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.
appwrite init topics
You can now push your topics with the following command:
appwrite push topics
This will create your topic in the Console with all of your appwrite.json configurations.
Learn more about the CLI topics commands
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.
Learn more about permission roles
Subscribe targets to a topic
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://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(
'[TOPIC_ID]', // topicId
'[SUBSCRIBER_ID]', // subscriberId
'[TARGET_ID]' // targetId
);