Message Reminders

Message reminders let users schedule notifications for specific messages, making it easier to follow up later. When a reminder includes a timestamp, it’s like saying “remind me later about this message,” and the user who set it will receive a notification at the designated time. If no timestamp is provided, the reminder functions more like a bookmark, allowing the user to save the message for later reference.

Reminders require Push V3 to be enabled - see details here

Enabling reminders

The Message Reminders feature must be activated at the channel level before it can be used. You have two configuration options: activate it for a single channel using configuration overrides, or enable it globally for all channels of a particular type.

// Enabling it for a channel
await channelClient.PartialUpdateAsync(channel.Type, channel.Id, new PartialUpdateChannelRequest
{
    Set = new Dictionary<string, object>
    {
        { "config_overrides", new Dictionary<string, object> { { "user_message_reminders", true } } }
    }
});

// Enabling it for a channel type
await channelTypeClient.UpdateChannelTypeAsync("messaging", new ChannelTypeWithStringCommandsRequest
{
    UserMessageReminders = true
});

Message reminders allow users to:

  • schedule a notification after given amount of time has elapsed
  • bookmark a message without specifying a deadline

Limits

  • A user cannot have more than 250 reminders scheduled
  • A user can only have one reminder created per message

Creating a message reminder

You can create a reminder for any message. When creating a reminder, you can specify a reminder time or save it for later without a specific time.

// Create a reminder with a specific due date
var reminder = await messageClient.CreateReminderAsync("message-id", "user-id", DateTimeOffset.Now.AddHours(1));

// Create a "Save for later" reminder without a specific time
var reminder = await messageClient.CreateReminderAsync("message-id", "user-id");

Updating a message reminder

You can update an existing reminder for a message to change the reminder time.

// Update a reminder with a new due date
var updatedReminder = await messageClient.UpdateReminderAsync("message-id", "user-id", DateTimeOffset.Now.AddHours(2));

// Convert a timed reminder to "Save for later"
var updatedReminder = await messageClient.UpdateReminderAsync("message-id", "user-id", null);

Deleting a message reminder

You can delete a reminder for a message when it’s no longer needed.

// Delete the reminder for the message
await messageClient.DeleteReminderAsync("message-id", "user-id");

Querying message reminders

The SDK allows you to fetch all reminders of the current user. You can filter, sort, and paginate through all the user’s reminders.

// Query reminders for a user
var reminders = await messageClient.QueryRemindersAsync("user-id");

// Query reminders with filters
var filter = new Dictionary<string, object> { { "channel_cid", "messaging:general" } };
var reminders = await messageClient.QueryRemindersAsync("user-id", filter);

Filtering reminders

You can filter the reminders based on different criteria:

  • message_id - Filter by the message that the reminder is created on.
  • remind_at - Filter by the reminder time.
  • created_at - Filter by the creation date.
  • channel_cid - Filter by the channel ID.

The most common use case would be to filter by the reminder time. Like filtering overdue reminders, upcoming reminders, or reminders with no due date (saved for later).

// Filter overdue reminders
var overdueFilter = new Dictionary<string, object>
{
    { "remind_at", new Dictionary<string, object> { { "$lt", DateTimeOffset.Now } } }
};
var overdueReminders = await messageClient.QueryRemindersAsync("user-id", overdueFilter);

// Filter upcoming reminders
var upcomingFilter = new Dictionary<string, object>
{
    { "remind_at", new Dictionary<string, object> { { "$gt", DateTimeOffset.Now } } }
};
var upcomingReminders = await messageClient.QueryRemindersAsync("user-id", upcomingFilter);

// Filter reminders with no due date (saved for later)
var savedFilter = new Dictionary<string, object> { { "remind_at", null } };
var savedReminders = await messageClient.QueryRemindersAsync("user-id", savedFilter);

Pagination

If you have many reminders, you can paginate the results.

// Load reminders with pagination
var options = new Dictionary<string, object> { { "limit", 10 }, { "offset", 0 } };
var reminders = await messageClient.QueryRemindersAsync("user-id", null, options);

// Load next page
var nextPageOptions = new Dictionary<string, object> { { "limit", 10 }, { "offset", 10 } };
var nextReminders = await messageClient.QueryRemindersAsync("user-id", null, nextPageOptions);

Events

The following WebSocket events are available for message reminders:

  • reminder.created, triggered when a reminder is created.
  • reminder.updated, triggered when a reminder is updated.
  • reminder.deleted, triggered when a reminder is deleted.
  • notification.reminder_due, triggered when a reminder’s due time is reached.

When a reminder’s due time is reached, the server will also send a push notification to the user. Make sure you have configured push notifications in your app to handle these reminders.

// Backend SDK
client.on("reminder.created", (event) => {
  console.log("Reminder created for message:", event.message_id);
});

client.on("reminder.updated", (event) => {
  console.log("Reminder updated for message:", event.message_id);
});

client.on("reminder.deleted", (event) => {
  console.log("Reminder deleted for message:", event.message_id);
});

client.on("notification.reminder_due", (event) => {
  console.log("Reminder due for message:", event.message_id);
});

// JavaScript SDK
const { unsubscribe } = client.on("reminder.created", handler);
const { unsubscribe } = client.on("reminder.updated", handler);
const { unsubscribe } = client.on("reminder.deleted", handler);
const { unsubscribe } = client.on("notification.reminder_due", handler);
Previous
Draft Messages
Next
Location Sharing
© Getstream.io, Inc. All Rights Reserved.