MagicBell JavaScript SDK

Welcome to the magicbell-js SDK documentation. This guide will help you get started with integrating and using the JavaScript SDK in your project.

Setup & Configuration

Installation

To get started with the SDK, we recommend installing using npm:

npm install magicbell-js

Authentication

Both the ProjectClient and the UserClient require authentication. Please read more about authentication and generation of tokens in our Authentication docs.

ProjectClient

Authentication

Access Token Authentication

The Client API uses an Access Token for authentication.

This token must be provided to authenticate your requests to the API.

Setting the Access Token

When you initialize the SDK, you can set the access token as follows:

const sdk = new Client({ token: 'YOUR_TOKEN' });

If you need to set or update the access token after initializing the SDK, you can use:

const sdk = new Client();
sdk.token = 'YOUR_TOKEN';

Setting a Custom Timeout

You can set a custom timeout for the SDK's HTTP requests as follows:

const client = new Client({ timeout: 10000 });

Sample Usage

Below is a comprehensive example demonstrating how to authenticate and call a simple endpoint:

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

(async () => {
  const client = new Client({
    token: 'YOUR_TOKEN',
  });

  const { data } = await client.broadcasts.listBroadcasts({
    limit: 1,
    startingAfter: 'starting_after',
    endingBefore: 'ending_before',
  });

  console.log(data);
})();

Services

The SDK provides various services to interact with the API.

| Name | | :------------------------------------------------------------------------- | | BroadcastsService | | ChannelsService | | EventsService | | IntegrationsService | | UsersService | | WorkflowsService |

Models

The SDK includes several models that represent the data structures used in API requests and responses. These models help in organizing and managing the data efficiently.

| Name | Description | | :----------------------------------------------------------------------------------------- | :---------- | | BroadcastCollection | | | Broadcast | | | User | | | Links | | | CategoryDeliveryConfig | | | InboxTokenResponseCollection | | | InboxTokenResponse | | | Links | | | DiscardResult | | | ApnsTokenCollection | | | ApnsToken | | | ExpoTokenCollection | | | ExpoToken | | | FcmTokenCollection | | | FcmToken | | | SlackTokenCollection | | | SlackToken | | | TeamsTokenCollection | | | TeamsToken | | | WebPushTokenCollection | | | WebPushToken | | | EventCollection | | | Event | | | Links | | | IntegrationConfigCollection | | | IntegrationConfig | | | Links | | | ApnsConfigCollection | | | ApnsConfig | | | ApnsConfigPayload | | | EventSourceConfigCollection | | | EventSourceConfig | | | EventSourceConfigPayload | | | ExpoConfigCollection | | | ExpoConfig | | | ExpoConfigPayload | | | FcmConfigCollection | | | FcmConfig | | | FcmConfigPayload | | | GithubConfigCollection | | | GithubConfig | | | GithubConfigPayload | | | InboxConfigCollection | | | InboxConfig | | | InboxConfigPayload | | | SlackBotConfigCollection | | | SlackBotConfig | | | SlackBotConfigPayload | | | MailgunConfigCollection | | | MailgunConfig | | | MailgunConfigPayload | | | PingConfigCollection | | | PingConfig | | | PingConfigPayload | | | SendgridConfigCollection | | | SendgridConfig | | | SendgridConfigPayload | | | SesConfigCollection | | | SesConfig | | | SesConfigPayload | | | SlackConfigCollection | | | SlackConfig | | | SlackConfigPayload | | | SmtpConfigObjectCollection | | | SmtpConfigObject | | | SmtpConfig | | | StripeConfigCollection | | | StripeConfig | | | StripeConfigPayload | | | TwilioConfigCollection | | | TwilioConfig | | | TwilioConfigPayload | | | WebpushConfigCollection | | | WebpushConfig | | | WebpushConfigPayload | | | UserCollection | | | User | | | Links | | | WorkflowDefinition | | | ExecuteWorkflowRequest | | | CreateRunResponse | | | GetRunResponse | | | WorkflowRunCollection | | | WorkflowRun | | | Links | |

UserClient

Authentication

Access Token Authentication

The Client API uses an Access Token for authentication.

This token must be provided to authenticate your requests to the API.

Setting the Access Token

When you initialize the SDK, you can set the access token as follows:

const sdk = new Client({ token: 'YOUR_TOKEN' });

If you need to set or update the access token after initializing the SDK, you can use:

const sdk = new Client();
sdk.token = 'YOUR_TOKEN';

Setting a Custom Timeout

You can set a custom timeout for the SDK's HTTP requests as follows:

const client = new Client({ timeout: 10000 });

Sample Usage

Below is a comprehensive example demonstrating how to authenticate and call a simple endpoint:

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

(async () => {
  const client = new Client({
    token: 'YOUR_TOKEN',
  });

  const { data } = await client.channels.listInboxTokens({
    limit: 123,
    startingAfter: 'starting_after',
    endingBefore: 'ending_before',
  });

  console.log(data);
})();

Services

The SDK provides various services to interact with the API.

| Name | | :------------------------------------------------------------------------ | | ChannelsService | | IntegrationsService | | NotificationsService |

Models

The SDK includes several models that represent the data structures used in API requests and responses. These models help in organizing and managing the data efficiently.

| Name | Description | | :---------------------------------------------------------------------------------------------- | :---------- | | InboxTokenResponseCollection | | | InboxTokenResponse | | | Links | | | InboxToken | | | DiscardResult | | | ApnsTokenCollection | | | ApnsToken | | | ApnsTokenPayload | | | ExpoTokenCollection | | | ExpoToken | | | ExpoTokenPayload | | | FcmTokenCollection | | | FcmToken | | | FcmTokenPayload | | | SlackTokenCollection | | | SlackToken | | | SlackTokenPayload | | | TeamsTokenCollection | | | TeamsToken | | | TeamsTokenPayload | | | UserPreferences | | | WebPushTokenCollection | | | WebPushToken | | | WebPushTokenPayload | | | InboxConfigPayload | | | SlackInstallation | | | SlackFinishInstallResponse | | | SlackStartInstall | | | SlackStartInstallResponseContent | | | WebPushTokenPayload | | | WebPushStartInstallationResponse | | | NotificationCollection | | | Notification | | | Links | |

Realtime

The Realtime client enables real-time notification delivery through WebSocket connections. When new notifications are created for a user, they are instantly pushed to connected clients without requiring polling.

Authentication

The Realtime client requires a user access token for authentication. This can be provided either directly or through an existing UserClient instance.

Sample Usage

import { Realtime } from 'magicbell-js/realtime';

const realtime = new Realtime({ token: 'USER_ACCESS_TOKEN' });

realtime.listen((notification) => {
  console.log('New notification received:', notification.title);
  // Handle the notification (update UI, show toast, etc.)
});

// When done listening
realtime.disconnect();

Using with UserClient

You can also initialize the Realtime client with an existing UserClient:

import { Client } from 'magicbell-js/user-client';
import { Realtime } from 'magicbell-js/realtime';

const userClient = new Client({ token: 'USER_ACCESS_TOKEN' });
const realtime = new Realtime(userClient);

realtime.listen((notification) => {
  console.log('New notification:', notification);
});

Connection Management

The Realtime client automatically handles connection management, including reconnection attempts when the connection is lost:

// Check if currently connected
if (realtime.isListening()) {
  console.log('Connected to real-time notifications');
}

// Disconnect when no longer needed
realtime.disconnect();