Notify User Groups Using Notify API

ROQ offers a convenient Notifications API that allows users to easily send information to one or multiple user groups. By using the userGroups() or GraphQL, we can get all the registered groups and then we can send the notifications to any groups.

ROQ GraphQL Query

The ROQ Node.js SDK provide graphqlRequest() API to run a GraphQL query natively so you don't need to add any additional packages. You just need to provide GraphQL query string. For more information about this API, please read the GraphQL Query documentation.

For example, for development purposes, let's use GraphQL query to get all the registered user groups.

The GraphQL API URL server can be found in the ROQ Console. Go to the menu Application Details → Super Admin Tokens. You will need the URL and tokens.

To use this code sample, make sure to install the npm packages @roq/nodejs and dotenv.

import 'dotenv/config'
import { Platform } from '@roq/nodejs'
 
/**
 * Connect to the ROQ Platform
 */
const roqClient = new Platform({
    apiKey: process.env.ROQ_API_KEY,
    environmentId: process.env.ROQ_ENVIRONMENT_ID,
    host: process.env.ROQ_PLATFORM_URL
})
 
const query = `
{
   userGroups {
    totalCount
    data {
      id
      name
      reference
      users {
        totalCount
        data {
          id
        }
      }
    }    
  }
}
`
 
const roqGraphQLRequest = await roqClient.asSuperAdmin().graphqlRequest(query);
console.log(roqGraphQLRequest);

Below is the JSON representation of the data variable:

{
    "userGroups": {
        "totalCount": 3,
        "data": [
            {
                id: '554a2843-66dd-4c9a-adc1-0c48484591b6',
                name: 'General Affair',
                reference: 'general-affair',
                users: { totalCount: 2, data: [Array] }
            },
            {
                id: 'a3040727-4142-44e5-a2be-14c383f53506',
                name: 'Sales',
                reference: 'sales',
                users: { totalCount: 0, data: [] }
            },
            {
                id: 'b2b2b399-746f-49cc-bec1-d43101ffb138',
                name: 'Marketing',
                reference: 'marketing',
                users: { totalCount: 0, data: [] }
            }
        ]
    }
}

We can use the group IDs from the output response as references for our notifications and to determine which users should receive them.

Send Notifications

To add a new notification template in the ROQ Console, please read this add notifications tutorial.

For example to send a notification for group General Affair which has a group id 554a2843-66dd-4c9a-adc1-0c48484591b6:

// Suppose you have the group IDs as follows:
const selectedGroupIds = ["554a2843-66dd-4c9a-adc1-0c48484591b6"];
 
// Filter the groups with the provided IDs.
const selectedGroups = roqGraphQLRequest.data.userGroups.data.filter(group => selectedGroupIds.includes(group.id));
 
if (selectedGroups.length === 0) {
    console.log("No groups found with the provided IDs.");
} else {
    // Extract the user IDs from the selected groups.
    const userIds = selectedGroups.flatMap(group => group.users.data.map(user => user.id));
 
    const notifyStatus = await roqClient.asSuperAdmin().notify({
        notification: {
            key: "news-update",
            recipients: {
                userIds: userIds,
                allUsers: false,
                userGroups: {
                    operator: "AND",
                    userGroupIds: selectedGroupIds
                }
            },
            data: [
                { key: "platform_name", value: "AnimFig" },
                { key: "your_name", value: "Anna W." },
                { key: "company_name", value: "AnimFig Ltd." }
            ]
        }
    });
 
    console.log(notifyStatus);
}

If you log in as a user with a member of the group General Affair in the generated application, you will receive the notification.

notification popup

Overview Send Email to User Groups