JavaScript SDK - MagicBell

This package provides a convenient interface to query the MagicBell API. Note that some methods depend on your secret key, those methods are not to be used in browsers, as your secret key must be kept secret.

Requirements

Node 18.13 or higher.

When using older versions, you might need to polyfill fetch. See isomorphic-fetch for more information.

You also might need to polyfill eventsource when using the listen method in an environment that doesn't support it. See eventsource for more information.

Installation

Install the package with npm:

shell
npm install magicbell --save

or yarn:

shell
yarn add magicbell

Usage

The package needs to be configured with your project's secret key & api key, which are available in the MagicBell Dashboard.

js
import { ProjectClient } from 'magicbell/project-client';

const magicbell = new ProjectClient({
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
});

try {
  const broadcast = await magicbell.broadcasts.create({
    title: 'Sweet!',
    content: 'When you see it, you know it!',
    recipients: [{ email: 'customer@example.com' }],
  });
  console.log(broadcast.id);
} catch (error) {
  console.error(error);
}

or go old-school with require and promises:

js
const { ProjectClient } = require('magicbell/project-client');

const magicbell = new ProjectClient({
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
});

magicbell.broadcasts
  .create({
    title: 'Sweet!',
    content: 'When you see it, you know it!',
    recipients: [{ email: 'customer@example.com' }],
  })
  .then((broadcast) => console.log(broadcast.id))
  .catch((error) => console.error(error));

Some endpoints, like notifications.list are user scoped, and can be consumed via a user specific client, authenticated using apiKey and userEmail or apiKey and userExternalId option.

js
import { UserClient } from 'magicbell/user-client';

const magicbell = new UserClient({
  apiKey: 'your-api-key',
  userEmail: 'you@example.com',
});

const notifications = await magicbell.notifications.list();

Note that every resource method accepts an optional options object, which can be used to override client defaults and pass additional options to the request.

This can for example be used to increase the network timeout.

js
const johnsPreferences = await magicbell.notificationPreferences.list({
  timeout: 30_000,
});

Using Promises

Every method returns a promise.

js
const user = await magicbell.users.create({
  email: 'person@example.com',
  first_name: 'Person',
  last_name: 'Doe',
});

List methods return iterable promises and the response can be handled in different ways:

standard promise - this method requires manual iteration to fetch multiple pages.

js
const firstPage = await magicbell.notifications.list();
// firstPage: { page: 1, total_pages: 5, notifications: [{ id: '…', title: '…', … }, …], … }
const nextPage = await magicbell.notifications.list({ page: firstPage.current_page + 1 });

async iterator - this iterates over all items across multiple pages. Call break when you wish to step out of the iteration / auto fetching.

js
for await (const notification of magicbell.notifications.list()) {
  console.log(notification.title);
  // break to abort and stop fetching/iterating
  if (shouldStop()) break;
}

forEach - similar to the iterator, but in a callback style fashion. Return false when you wish to step out of the iteration / auto fetching.

js
await magicbell.notifications.list().forEach((notification) => {
  console.log(notification.title);
  // return false to abort and stop fetching/iterating
  if (shouldStop()) return false;
});

toArray - all items across multiple pages are fetched and returned in a single array. This method cannot be cancelled half way, and requires a limit to be set to prevent your process from running out of memory. Use the iterators above if you need to fetch lots of data.

js
const notifications = await magicbell.notifications.list().toArray({ limit: 1000 });

Configuration

Initialize with config object

The package can be initialized with several options, and in two scopes. There's an project client, and a user client.

Project Scope

The project client is used to make requests on behalf of the project, and requires the apiKey and apiSecret options to be set.

js
import { ProjectClient } from 'magicbell/project-client';

const magicbell = new ProjectClient({
  // auth
  apiKey: 'your-api-key', // required
  apiSecret: 'your-secret-key', // required

  // network
  timeout: 30_000,
  maxRetries: 3,
  maxRetryDelay: 60,
  telemetry: true,
});

User Scope

The user client is used to make requests on behalf of a user, and requires the apiKey and one of userEmail or userExternalId options to be set. If your project has HMAC enabled, the userHmac option is also required. As no apiSecret is needed, this client is suitable for client side usage and safe to be used in the browser.

js
import { UserClient } from 'magicbell/user-client';

const magicbell = new UserClient({
  // auth
  apiKey: 'your-api-key', // required
  userEmail: 'you@example.com', // required if userExternalId is not set
  userExternalId: 'your-external-id', // required if userEmail is not set
  userHmac: 'your-user-hmac', // required if HMAC is enabled

  // network
  timeout: 30_000,
  maxRetries: 3,
  maxRetryDelay: 60,
  telemetry: true,
});

Options

host String

The current refresh token.

apiKey String

Your project api key which can be found on the MagicBell Dashboard. This key is required for all calls.

apiSecret String [project client only]

Your project api secret which can be found on the MagicBell Dashboard. This key is required for project scoped endpoints.

userEmail String [user client only]

The email of the user you want to make requests for. This key is required for user scoped endpoints when no userExternalId is set.

userExternalId String [user client only]

The external-id of the user you want to make requests for. This key is required for user scoped endpoints when no userEmail is set.

userHmac String [user client only]

The HMAC of the user you want to make requests for. This key is required for user scoped endpoints when HMAC is enabled.

timeout Number

A network timeout in milliseconds. Defaults to 30 seconds. Network requests will be canceled if they take longer than this.

maxRetries Number

The maximum number of times to retry a request. Defaults to 3. Set to 0 to disable retries.

maxRetryDelay Number

The maximum time in milliseconds to wait between retry requests. Note that subsequent retries can have a longer total duration than this. Defaults to 60 seconds.

telemetry Boolean

Each request - after the first - includes a header with the response time of the previous request. This helps us to improve the performance of the API. You can opt out of this by setting this option to false.

features Record<string, boolean>

A map of feature flags to get access to beta features. See Feature Flags for more information.

headers Record<string, string>

Custom headers you wish to include on the request, for example to instruct your proxy servers or to decorate your logs.

Configuring Timeout

Timeout can be set globally via the config object:

js
const magicbell = new MagicBell({
  // ...
  timeout: 20_000, // 20 seconds
});

And overridden on a per-request basis:

js
magicbell.notifications.create(
  { title: 'Hi there!' },
  { timeout: 1_000 }, // 1 second
);

Network retries

Automatic network retries can be configured with the maxRetries option. This will retry network requests - with an exponential backoff - when it makes sense to retry them. For example, a request that failed due to a network error will be retried, but a request that failed due to an invalid API key or incorrect data will not.

Note
Automatic retries are meant to handle short network disturbances. They're handled in-process, and don't use a persistent job queue. They won't survive process restarts. You might need to implement your own persistent workers with retry logic if delivery is crucial to your business.

We'll automatically add idempotency keys if you haven't provided on, to prevent duplication.

A request that was retried, will take longer, but looks exactly the same as a direct success to the caller. The caller will not be notified that a request was retried.

js
const magicbell = new MagicBell({
  maxRetries: 2, // Retry a request twice before giving up
});

Network retries can also be set on a per-request basis:

js
magicbell.notifications.create(
  { recipients: [{ email: 'person@example.com' }] },
  { maxRetries: 2 }, // Retry this specific request twice before giving up
);

Using in a package

If you're wrapping our SDK, or using it in a specific app, we'd appreciate it if you instantiated your MagicBell client with appInfo, eg;

js
const magicbell = new MagicBell({
  apiKey: '...',
  appInfo: {
    name: 'MyAwesomePlugin',
    version: '1.2.34', // Optional
    url: 'https://myawesomeplugin.info', // Optional
  },
});

Request latency telemetry

By default, the library sends request latency telemetry to MagicBell. These numbers help us to improve the overall latency of our API for all users.

You can disable this behavior if you prefer:

js
const magicbell = new MagicBell({
  telemetry: false,
});

Feature Flags

Features that in beta or early release are "hidden" behind a feature flag. You can enable them by passing a features object to the config, provided with a key for each feature that you wish to enable.

Note that these features are behind a flag for a reason. They may change or be removed at any time and are not covered by our semantic versioning (semver) policy.

js
const magicbell = new MagicBell({
  features: {
    'a-new-beta-feature': true,
  },
});

Below is a list of features that are currently behind feature flags.

There are no features in beta at this time.

Resource Methods

The SDK is divided in two scopes. Project Resources, and User Resources. Below you'll find the all supported resource methods, with their signatures. The full documentation can be found in our api-reference. When comparing the api-reference with these methods, you'll notice that the SDK removes any wrapping entities for your convenience. Meaning, instead of posting { notification: { title: 'hi' } }, you'll call create({ title: 'hi' }).

Apart from the removal of the wrappers, returned entities and provided parameters are identical between our REST API and this SDK.

Project Resource Methods

The project scope contains everything you need to manage your project and send notifications. You'll need to be authenticated using apiKey and apiSecret to use these methods.

js
import { ProjectClient } from 'magicbell/project-client';

const magicbell = new ProjectClient({
  apiKey: 'your-api-key', // required
  apiSecret: 'your-secret-key', // required
});

Broadcasts

Create broadcasts

Create a broadcast to send notifications to upto a 1,000 recipients - users or topic subscribers. You can identify users by their email address or by an external_id.

You don't have to import your users into MagicBell. If a user does not exist we'll create it automatically.

You can send user attributes like first_name, custom_attributes, and more when creating a broadcast.

A new notification will be shown in the inbox of each recipient in real-time. It will also be delivered to each recipient through all channels you have enabled for your project.

js
await magicbell.broadcasts.create({
  title: "We're processing your order",
  content: "Thank you for your order. We'll notify you when these items are ready.",
  category: 'order_created',
  topic: 'order:33098',
  recipients: [
    {
      email: 'dan@example.com',
    },
    {
      external_id: '83d987a-83fd034',
      first_name: 'Person',
      last_name: 'Doe',
      custom_attributes: {
        plan: 'enterprise',
        pricing_version: 'v10',
        preferred_pronoun: 'They',
      },
      phone_numbers: ['+1 5005550001'],
    },
  ],
  overrides: {
    channels: {
      email: {
        title: "[MagicBell] We're processing your order",
        content:
          "Thank you for your order. If you need help, or have any questions please don't hesitate to reach out to us directly at hello@magicbell.com",
      },
    },
  },
});

List broadcasts

List all broadcasts. Broadcasts are sorted in descending order by the sent_at timestamp.

js
await magicbell.broadcasts.list({
  page: 1,
  per_page: 1,
});

Fetch a broadcast by its ID

Fetch a broadcast by its ID.

js
await magicbell.broadcasts.get('{broadcast_id}');

Broadcasts Notifications

Fetch notifications by broadcast id.

Fetch the notifications for a broadcast.

js
await magicbell.broadcasts.notifications.list('{broadcast_id}', {
  page: 1,
  per_page: 1,
});

Users

Create a user

Create a user. Please note that you must provide the user's email or the external id so MagicBell can uniquely identify the user.

The external id, if provided, must be unique to the user.

js
await magicbell.users.create({
  external_id: '56780',
  email: 'hana@supportbee.com',
  first_name: 'Hana',
  last_name: 'Mohan',
  custom_attributes: {
    plan: 'enterprise',
    pricing_version: 'v10',
    preferred_pronoun: 'She',
  },
  phone_numbers: ['+15005550001'],
});

Fetch users

Fetches users for the project identified by the auth keys. Supports filtering, ordering, and pagination.

js
await magicbell.users.list({
  page: 1,
  per_page: 1,
  'last_seen_at:before': '…',
  'last_seen_at:after': '…',
  'last_notified_at:before': '…',
  'last_notified_at:after': '…',
  order_by: '…',
});

Get user by ID

Fetch a user by id, for the project identified by the auth keys.

js
await magicbell.users.get('{user_id}');

Update a user

Update a user's data. If you identify users by their email addresses, you need to update the MagicBell data, so this user can still access their notifications.

js
await magicbell.users.update('{user_id}', {
  email: 'hana@magicbell.io',
});

Update a user identified by email

Update a user's data. If you identify users by their email addresses, you need to update the MagicBell data, so this user can still access their notifications.

js
await magicbell.users.updateByEmail('{user_email}', {
  external_id: '56780',
  email: 'hana@supportbee.com',
  first_name: 'Hana',
  last_name: 'Mohan',
  custom_attributes: {
    plan: 'enterprise',
    pricing_version: 'v10',
    preferred_pronoun: 'She',
  },
  phone_numbers: ['+15005550001'],
});

Update a user identified by external ID

Update a user's data. If you identify users by their email addresses, you need to update the MagicBell data, so this user can still access their notifications.

js
await magicbell.users.updateByExternalId('{external_id}', {
  external_id: '56780',
  email: 'hana@supportbee.com',
  first_name: 'Hana',
  last_name: 'Mohan',
  custom_attributes: {
    plan: 'enterprise',
    pricing_version: 'v10',
    preferred_pronoun: 'She',
  },
  phone_numbers: ['+15005550001'],
});

Delete a user

Immediately deletes a user.

js
await magicbell.users.delete('{user_id}');

Delete a user identified by email

Immediately deletes a user.

js
await magicbell.users.deleteByEmail('{user_email}');

Delete a user identified by external ID

Immediately deletes a user.

js
await magicbell.users.deleteByExternalId('{external_id}');

Users Notifications

Fetch notifications by user id.

Fetch the notifications and deliveries for a user.

js
await magicbell.users.notifications.list('{user_id}', {
  page: 1,
  per_page: 1,
});

Users Push Subscriptions

Fetch user's push subscriptions

Fetch a user's push subscriptions. Returns a paginated list of web and mobile push subscriptions for all platforms.

js
await magicbell.users.pushSubscriptions.list('{user_id}', {
  page: 1,
  per_page: 1,
});

Imports

Create a import

Enqueues an import - currently only supported for users. Amongst other things, the users import allows associating slack channels (if you have already setup the oauth apps).

js
await magicbell.imports.create({
  users: [
    {
      external_id: 'ugiabqertz',
      email: 'johndoe@example.com',
      first_name: 'John',
      last_name: 'Doe',
      custom_attributes: {
        age: 32,
        country: 'Spain',
      },
      channels: {
        slack: {
          providers: [
            {
              oauth: {
                channel_id: 'U039446XF3Y',
                app: {
                  app_id: 'your_slack_app_id',
                  team_id: 'workspace_id_from_slack',
                },
              },
            },
          ],
        },
      },
    },
  ],
});

Get the status of an import

Query the status of the import for a summary of imported records and failures for each record that could not be imported successfully.

js
await magicbell.imports.get('{import_id}');

Metrics

Get notification metrics

Query the metrics of broadcasts and their recipients.

js
await magicbell.metrics.get();

Metrics Categories

Get notification metrics grouped by category

Query the metrics of broadcasts and their recipients, grouped by category.

js
await magicbell.metrics.categories.get();

Metrics Topics

Get notification metrics grouped by topic

Query the metrics of broadcasts and their recipients, grouped by topic.

js
await magicbell.metrics.topics.get();

User Resource Methods

The user scope contains everything a specific user needs to display their notifications and manage their settings. They'll need to be authenticated using apiKey, either userEmail or userExternalId, and userHmac when HMAC is enabled on your project.

As you don't need to authenticate using the apiSecret, this scope is safe to use in the browser.

js
import { UserClient } from 'magicbell/user-client';

const magicbell = new UserClient({
  apiKey: 'your-api-key', // required
  userEmail: 'you@example.com', // required if userExternalId is not set
  userExternalId: 'your-external-id', // required if userEmail is not set
  userHmac: 'your-user-hmac', // required if HMAC is enabled
});

Notifications

Archive a notification

Mark a user notification as archived.

js
await magicbell.notifications.archive('{notification_id}');

Mark all notifications as read

Mark all notifications of a user as read. When you call this endpoint, the notification inboxes of this user will be updated in real-time.

js
await magicbell.notifications.markAllRead({
  archived: true,
  read: true,
  seen: true,
  category: '…',
  topic: '…',
});

Mark all notifications as seen

Mark all notifications of a user as seen. When you call this endpoint, the notification inboxes of this user will be updated in real-time.

js
await magicbell.notifications.markAllSeen({
  archived: true,
  read: true,
  seen: true,
  category: '…',
  topic: '…',
});

Mark a notification as read

Mark a user notification as read. The notification will be automatically marked as seen, too.

The new state will be reflected in the user's notification inbox in real-time.

js
await magicbell.notifications.markAsRead('{notification_id}');

Mark a notification as unread

Mark a user notification as unread. The new state will be reflected in the user's notification inbox in real-time.

js
await magicbell.notifications.markAsUnread('{notification_id}');

Fetch notifications for a user

Fetch a user's notifications. Notifications are sorted in descending order by the sent_at timestamp.

js
await magicbell.notifications.list({
  per_page: 1,
  page: 1,
  read: true,
  seen: true,
  archived: true,
  category: '…',
  topic: '…',
});

Fetch notification by ID

Fetch a user's notification by its ID.

js
await magicbell.notifications.get('{notification_id}');

Delete a notification

Delete a user's notification by its ID. The notification is deleted immediately and removed from the user's notification inbox in real-time.

js
await magicbell.notifications.delete('{notification_id}');

Unarchive a notification

Mark a user notification as unarchived.

js
await magicbell.notifications.unarchive('{notification_id}');

Push Subscriptions

Register a device token for a user

Please keep in mind that mobile push notifications will be delivered to this device only if the channel is configured and enabled.

js
await magicbell.pushSubscriptions.create({
  device_token: 'x4doKe98yEZ21Kum2Qq39M3b8jkhonuIupobyFnL0wJMSWAZ8zoTp2dyHgV',
  platform: 'ios',
});

List user's device tokens

Returns the list of device tokens registered for push notifications.

js
await magicbell.pushSubscriptions.list();

Delete user's device token

Deletes the registered device token to remove the mobile push subscription.

js
await magicbell.pushSubscriptions.delete('{device_token}');

Notification Preferences

Fetch user notification preferences

Fetch a user's notification preferences. If a user does not disable a channel explicitly, we would send notifications through that channel as long as your project is enabled.

js
await magicbell.notificationPreferences.get();

Update user notification preferences

Update a user's notification preferences. These preferences will be applied only to channels you enabled for your project.

js
await magicbell.notificationPreferences.update({
  categories: [
    {
      slug: 'billing',
      channels: [
        {
          slug: 'email',
          enabled: false,
        },
        {
          slug: 'web_push',
          enabled: false,
        },
      ],
    },
  ],
});

Subscriptions

Create a topic subscription

Set a user's subscription status to subscribed for a particular topic (and optional categories). If the user previously unsubscribed, the user will be resubscribed.

js
await magicbell.subscriptions.create({
  categories: [
    {
      slug: 'comments',
      reason: 'watching-the-repo',
    },
  ],
  topic: 'acme-inc.orders.1234',
});

Unsubscribe from a topic

Unusbscribe a user from a particular topic (and optional categories).

js
await magicbell.subscriptions.unsubscribe('{topic}', {
  categories: [
    {
      slug: 'comments',
    },
  ],
});

Fetch user's topic subscriptions

Fetch a user's topic subscriptions.

js
await magicbell.subscriptions.list();

Show a topic subscription

Show a user's subscription status for a particular topic and categories.

js
await magicbell.subscriptions.get('{topic}');

Delete topic subscription(s)

js
await magicbell.subscriptions.delete('{topic}', {
  categories: [
    {
      slug: 'comments',
    },
  ],
});

js
const magicbell = new MagicBell({
  apiKey: 'your-api-key',
  userEmail: 'someone@example.com',
});

magicbell.listen();

async iterator - this iterates over all events. Call break when you wish to step out of the iteration and stop listening.

js
for await (const notification of magicbell.listen()) {
  console.log(notification.data.id);
  // break to abort and stop listening
  if (shouldStop()) break;
}

forEach - similar to the iterator, but in a callback style fashion. Return false when you wish to stop listening.

js
magicbell.listen().forEach((notification) => {
  console.log(notification.data.id);
  // return false to abort and stop listening
  if (shouldStop()) return false;
});

close - stop listening. This will close the connection and stop the auto-reconnect.

js
const listener = magicbell.listen();

listener.forEach((notification) => {
  console.log(notification.data.id);
});

// stop listening after 5 seconds
setTimeout(() => {
  listener.close();
}, 5_000);

Realtime events

The following events are emitted by the client:

event.name	description
`notifications/new`	a new notification has been created
`notifications/read`	a notification has been read
`notifications/unread`	a notification has been marked as unread
`notifications/delete`	a notification has been deleted
`notifications/read/all`	all notifications have been marked as read
`notifications/seen/all`	all notifications have been marked as seen

Realtime with extended data

Note that the realtime listener returns a limited set of data. We do this intentionally, so that the listener stays fast, and doesn't use more bandwidth or battery than necessary. If you need more data, you can complement it using the notification resource method.

js
for await (let event of client.listen()) {
  if ('id' in event.data) {
    const notification = await client.notifications.get(event.data.id);
    doSomething({ event, notification });
  } else {
    doSomething({ event });
  }
}

Errors

Errors returned by the SDK are instances of MagicBellError. This is a subclass of the native Error class, and contains the properties defined below. Error types can be imported from magicbell/errors.

message String

A human-readable message providing more details about the error.

code String

A short machine-readable string identifying the error.

status Number

The HTTP status code returned by the API.

statusText String

The HTTP status text returned by the API.

responseBody unknown

The raw response body returned by the API

suggestion String

A suggestion to resolve the error.

docsUrl String

A link to the documentation for the error.

Support

New features and bug fixes are released on the latest major version of the magicbell package. If you are on an older major version, we recommend that you upgrade to the latest in order to use the new features and bug fixes including those for security vulnerabilities. Older major versions of the package will continue to be available for use, but will not be receiving any updates.