User Management

Manage user subscriptions, notification preferences, channel configurations, and topic organization. This section covers the complete user workflow from initial subscription to advanced notification management.

Prerequisites

Before managing users, ensure you have completed these steps:

App Registration: Register your app with Dialect (see the registration guide if you need to set this up)

User Management Workflow Overview

Dialect’s user management follows a three-step process:

User Subscription: User subscribes to your app (via notification widget or SDK) and automatically gets IN_APP notifications
Channel Management: User can add email and Telegram channels for additional notification delivery methods
Topic Organization: Configure notification categories and topics that users can selectively subscribe to

Step 1: Subscription Management

Before a user can receive messages, they have to be subscribed to your service.

SDK
Notification Components
API

Create a subscription for a user’s wallet address to your app. This automatically enables them to receive IN_APP notifications.

// Step 1: User subscribes to your app (gets IN_APP notifications automatically)
const subscription = await dialectSolanaSdk.wallet.dappAddresses.create({
  addressId: address.id,
  enabled: true,
  dappPublicKey,
});

Subscribe a user to channels via API. You can specify which channels to subscribe to, or omit channel to subscribe to all available channels:

curl https://alerts-api.dial.to/v2/subscribe \
  --request POST \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "appId": "YOUR_APP_ID",
    "channel": ["IN_APP", "EMAIL"]
  }'

appId: Your application’s unique identifier (optional if using client key)
channel: Channel or array of channels to subscribe to (IN_APP, EMAIL, TELEGRAM). If omitted, subscribes to all available channels
Authorization: Bearer token (see authentication section)
X-Dialect-Client-Key: Your client key

The response will be an empty JSON object indicating success:

{}

Enabling & disabling a subscription

SDK
Notification Components
API

Enable/disable a subscription programmatically:

const updatedSubscription = await dialectSolanaSdk.wallet.dappAddresses.update({
  dappAddressId: subscription.id,
  enabled: false,
});

Getting subscriptions by id

SDK
Notification Components
API

Retrieve a specific subscription using its unique ID:

const specificSubscription = await dialectSolanaSdk.wallet.dappAddresses.find({
  dappAddressId: subscription.id,
});

Getting subscriptions by wallet

SDK
Notification Components
API

Retrieve all subscriptions for a wallet address:

const allSubscriptions = await dialectSolanaSdk.wallet.dappAddresses.findAll({
  dappPublicKey, // optional parameter
  addressIds: [address.id], // optional parameter
});

Get detailed subscription information for the authenticated user:

curl https://alerts-api.dial.to/v2/apps \
  --request GET \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY'

This returns comprehensive subscription details:

{
  "apps": [
    {
      "id": "app-uuid",
      "name": "Your App Name",
      "subscribed": true,
      "channels": [
        { "channel": "IN_APP", "subscribed": true },
        { "channel": "EMAIL", "subscribed": false },
        { "channel": "TELEGRAM", "subscribed": true }
      ],
      "topics": [
        {
          "id": "topic-uuid",
          "name": "Price Alerts",
          "slug": "price-alerts",
          "subscribed": true
        }
      ]
    }
  ]
}

Getting subscribers by app

SDK
Notification Components
API

Not available via SDK. Use the API method below for server-side subscriber management.

Get all subscribers for your app (app owner perspective):

curl https://alerts-api.dial.to/v2/{appId}/subscribers \
  --request GET \
  --header 'x-dialect-api-key: YOUR_API_KEY'

appId: Your application’s unique identifier
offset: (Optional) Pagination offset (default: 0)
limit: (Optional) Pagination limit (default: 1000, max: 10000)

Response contains all wallet addresses subscribed to your app:

{
  "subscribers": [
    { "walletAddress": "6CxnSjtasq5Tzwb4b93AhLofXtiDvMpQ2vTkWdSZqTH7" },
    { "walletAddress": "AnotherWalletAddress..." }
  ]
}

Deleting a subscription

SDK
Notification Components
API

Remove a subscription completely:

await dialectSolanaSdk.wallet.dappAddresses.delete({
  dappAddressId: subscription.id,
});

Unsubscribe from an app or specific channels:

curl https://alerts-api.dial.to/v2/unsubscribe \
  --request POST \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "appId": "YOUR_APP_ID",
    "channel": ["IN_APP", "EMAIL", "TELEGRAM"]
  }'

appId: App ID or array of App IDs. If omitted, targets all apps available for the client
channel: Channel or array of channels to unsubscribe from. If omitted, unsubscribes from all channels

To completely unsubscribe from an app, omit the channel parameter:

curl https://alerts-api.dial.to/v2/unsubscribe \
  --request POST \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "appId": "YOUR_APP_ID"
  }'

Step 2: Channel Management

After subscribing to your app, users can add additional notification channels like email and Telegram. Users manage addresses via the Dialect data service, where they may add, verify, update & remove addresses for these various channels.

Add User Email Address

SDK
Notification Components
API

Add an email address for a user to receive notifications via email. The address will need to be verified before notifications can be sent.

// Step 2: User can add additional channels like email or Telegram
const address = await dialectSolanaSdk.wallet.addresses.create({
  type: AddressType.Email,
  value: "address@mailservice.com",
});

Users add and manage channels (email, Telegram) in the notification widget’s settings screen. The component handles verification and management flows.

<DialectSolanaSdk dappAddress={DAPP_ADDRESS}>
  <NotificationsButton />
</DialectSolanaSdk>

In the settings panel, users can add, verify, and remove channels. No extra code needed!

Verify an address

SDK
Notification Components
API

Dialect uses verification codes to verify ownership of web2 channels such as email and Telegram. These codes are sent to the address in question.

// Verify address (email or telegram). Constraint: there are
// 3 attempts to verify address, otherwise use call below to send new
// verification code
const verifiedAddress = await dialectSolanaSdk.wallet.addresses.verify({
  addressId: address.id,
  code: "1337",
});

If you did not receive the verification code, or if you failed to enter the correct value after several attempts, you can send a new code via the following call:

// Resend verification code. Constraint: you must wait 60 sec before
// resending the code.
await dialectSolanaSdk.wallet.addresses.resendVerificationCode({
  addressId: address.id,
});

Get addresses owned by a wallet

SDK
Notification Components
API

Retrieve address information for a wallet. This shows all the notification channels (email, Telegram) that a user has configured.

// Find all addresses owned by wallet
const allAddresses = await dialectSolanaSdk.wallet.addresses.findAll();

// Find specific address owned by wallet
const specificAddress = await dialectSolanaSdk.wallet.addresses.find({
  addressId: address.id,
});

You can also check email subscription status using the hook:

import { AddressType } from '@dialectlabs/sdk';
import { useNotificationChannelDappSubscription } from '@dialectlabs/react-sdk';

// Check email subscription status
const {
  enabled: emailEnabled,
  isFetchingSubscriptions: emailFetching,
} = useNotificationChannelDappSubscription({
  addressType: AddressType.Email,
  dappAddress: DAPP_ADDRESS,
});

if (!emailFetching) {
  console.log('Email subscribed:', emailEnabled);
}

Get channel subscription status via the apps endpoint:

curl https://alerts-api.dial.to/v2/apps \
  --request GET \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY'

This shows which channels are subscribed for each app:

{
  "apps": [
    {
      "id": "app-uuid",
      "name": "Your App",
      "subscribed": true,
      "channels": [
        { "channel": "IN_APP", "subscribed": true },
        { "channel": "EMAIL", "subscribed": false },
        { "channel": "TELEGRAM", "subscribed": true }
      ]
    }
  ]
}

Note: This endpoint shows channel subscription status, but email/Telegram addresses must be managed via components or SDK.

SDK
Notification Components
API

Use the useNotificationChannelDappSubscription hook to manage email subscriptions:

import { AddressType } from '@dialectlabs/sdk';
import { useNotificationChannelDappSubscription } from '@dialectlabs/react-sdk';

// Subscribe to email notifications for your dapp
const {
  enabled: emailEnabled,
  isToggling: emailToggling,
  toggleSubscription: toggleEmailSubscription,
} = useNotificationChannelDappSubscription({
  addressType: AddressType.Email,
  dappAddress: DAPP_ADDRESS,
});

// Enable email notifications
await toggleEmailSubscription({ enabled: true });

Subscribe to specific channels for an app:

curl https://alerts-api.dial.to/v2/subscribe \
  --request POST \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "appId": "YOUR_APP_ID",
    "channel": ["EMAIL", "TELEGRAM"]
  }'

Note: Email and Telegram channels require the user to have already added and verified those addresses via components or SDK.

Unsubscribe from specific channels

SDK
Notification Components
API

Use the same useNotificationChannelDappSubscription hook to disable email notifications:

import { AddressType } from '@dialectlabs/sdk';
import { useNotificationChannelDappSubscription } from '@dialectlabs/react-sdk';

const {
  enabled: emailEnabled,
  isToggling: emailToggling,
  toggleSubscription: toggleEmailSubscription,
} = useNotificationChannelDappSubscription({
  addressType: AddressType.Email,
  dappAddress: DAPP_ADDRESS,
});

// Disable email notifications
await toggleEmailSubscription({ enabled: false });

// Check current subscription status
console.log('Email notifications enabled:', emailEnabled);
console.log('Currently toggling:', emailToggling);

Unsubscribe from specific channels while maintaining subscription to others:

curl https://alerts-api.dial.to/v2/unsubscribe \
  --request POST \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "appId": "YOUR_APP_ID",
    "channel": ["EMAIL"]
  }'

This will unsubscribe from EMAIL notifications while keeping IN_APP and TELEGRAM active.

Update an address

SDK
Notification Components
API

You can update an address at any time. All of your subscriptions will remain intact, but won’t be sent until you re-verify.

// Update address value
const updatedAddress = await dialectSolanaSdk.wallet.addresses.update({
  addressId: address.id,
  value: "updated.address@example.com",
});

Remove an address

SDK
Notification Components
API

You can delete an address at any time. This will remove all subscriptions associated with that address.

// Delete address
await dialectSolanaSdk.wallet.addresses.delete({
  addressId: address.id,
});

Push Notifications

Push Notifications require a more complex setup and you can find a full walkthrough in the API section.

Step 3: Topic Management

Create and manage notification topics to organize and categorize your app’s notifications. Topics help users subscribe to specific types of alerts they care about.

Create a new notification type

SDK
Notification Components
API

Define a new category of notifications for your app. Each notification type represents a specific kind of alert that users can subscribe to independently.

// Create a new notification type
const dapp = await dialectSolanaSdk.dapps.find();

if (!dapp) {
  throw new IllegalStateError(
    "Dapp doesn't exist, please create dapp before using it"
  );
}

const notificationType = await dapp.notificationTypes.create({
  humanReadableId: "announcements",
  name: "Announcements",
  orderingPriority: 0,
  trigger: "Notification description or triggering event/conditions",
  defaultConfig: {
    enabled: true,
  },
});

Update an existing notification type

SDK
Notification Components
API

Modify the properties of an existing notification type, such as changing its name or trigger description. This is useful when refining your notification categories.

const allNotificationTypes = await dapp.notificationTypes.findAll();

if (allNotificationTypes.length < 1) return;

const notificationType = allNotificationTypes[0];

const patched = await dapp.notificationTypes.patch(notificationType.id, {
  name: "New feature announcements",
});

Get all topics

SDK
Notification Components
API

Retrieve all notification types (topics) for your app:

const dapp = await dialectSolanaSdk.dapps.find();
const allNotificationTypes = await dapp.notificationTypes.findAll();

// Or find a specific topic by human-readable ID
const specificTopic = await dapp.notificationTypes.find({ 
  humanReadableId: "price-alerts" 
});

Get all available topics for a user:

curl https://alerts-api.dial.to/v2/topics?appId=YOUR_APP_ID \
  --request GET \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY'

This returns topics organized by app with subscription status:

{
  "byApp": {
    "app-uuid": {
      "items": [
        {
          "id": "topic-uuid",
          "name": "Price Alerts",
          "description": "Receive alerts when prices drop",
          "slug": "price-alerts",
          "subscribed": true
        }
      ]
    }
  }
}

SDK
Notification Components
API

Use the useNotificationSubscriptions hook to manage topic subscriptions:

import { useNotificationSubscriptions } from '@dialectlabs/react-sdk';

const {
  subscriptions,
  update,
  isFetching,
  isUpdating,
} = useNotificationSubscriptions({
  dappAddress: DAPP_ADDRESS,
});

// Subscribe to a specific topic
const subscribeToTopic = async (topicId: string) => {
  await update({
    notificationTypeId: topicId,
    config: {
      enabled: true,
    },
  });
};

// Example: Subscribe to price alerts topic
await subscribeToTopic('price-alerts-topic-id');

Users can subscribe to topics directly in the notification widget’s settings screen.
When a user toggles a topic on, the component handles the subscription automatically.

<DialectSolanaSdk dappAddress={DAPP_ADDRESS}>
  <NotificationsButton />
</DialectSolanaSdk>

In the settings panel, users can toggle topics on/off. No extra code needed!

Subscribe to a specific topic:

curl https://alerts-api.dial.to/v2/topics/subscribe \
  --request POST \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "topicId": "123e4567-e89b-12d3-a456-426614174000"
  }'

Unsubscribe from topics

SDK
Notification Components
API

Use the same useNotificationSubscriptions hook to unsubscribe from topics:

import { useNotificationSubscriptions } from '@dialectlabs/react-sdk';

const {
  subscriptions,
  update,
  isUpdating,
} = useNotificationSubscriptions({
  dappAddress: DAPP_ADDRESS,
});

// Unsubscribe from a specific topic
const unsubscribeFromTopic = async (topicId: string) => {
  await update({
    notificationTypeId: topicId,
    config: {
      enabled: false,
    },
  });
};

// Example: Unsubscribe from price alerts topic
await unsubscribeFromTopic('price-alerts-topic-id');

Unsubscribe from a specific topic:

curl https://alerts-api.dial.to/v2/topics/unsubscribe \
  --request POST \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "topicId": "123e4567-e89b-12d3-a456-426614174000"
  }'

Get topic subscription status

SDK
Notification Components
API

Use the useNotificationSubscriptions hook to get topic subscription status:

import { useNotificationSubscriptions } from '@dialectlabs/react-sdk';

const {
  subscriptions,
  isFetching,
} = useNotificationSubscriptions({
  dappAddress: DAPP_ADDRESS,
});

// Check if a specific topic is subscribed
const isTopicSubscribed = (topicId: string) => {
  const subscription = subscriptions.find(
    (sub) => sub.notificationType.id === topicId
  );
  return subscription?.subscription?.config?.enabled || false;
};

// Get all subscribed topics
const subscribedTopics = subscriptions.filter(
  (sub) => sub.subscription?.config?.enabled
);

if (!isFetching) {
  console.log('Price alerts subscribed:', isTopicSubscribed('price-alerts-topic-id'));
  console.log('All subscribed topics:', subscribedTopics);
}

Get topic subscription status via the apps endpoint:

curl https://alerts-api.dial.to/v2/apps \
  --request GET \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  --header 'X-Dialect-Client-Key: YOUR_CLIENT_KEY'

This returns apps with their topics and subscription status:

{
  "apps": [
    {
      "id": "app-uuid",
      "name": "Your App",
      "subscribed": true,
      "topics": [
        {
          "id": "topic-uuid",
          "name": "Price Alerts",
          "slug": "price-alerts",
          "subscribed": true
        }
      ]
    }
  ]
}

Best Practices

💡 User Experience Tips:

Start users with a simple subscription, then let them add channels as needed
Create meaningful notification types that users actually want to subscribe to
Good topics are specific enough to be useful but broad enough to generate regular content
Always respect user preferences and make unsubscribing easy

💡 Technical Tips:

Always subscribe users to your app first using dappAddresses.create() before adding additional notification channels
Implement proper error handling for address verification flows
Use batch operations when managing multiple users to avoid rate limits

Next Steps

Now that you understand user management concepts, you’re ready to implement notification components:

NotificationsButton - Complete done-for-you solution
Notifications - Standalone component for custom integration

The components handle all the user management workflows described above, providing your users with intuitive interfaces for managing their notification preferences.

GETTING STARTED

SETUP

INTEGRATE AN INBOX

SEND ALERTS

MOBILE ALERTS STACK

EVENTS (Beta)

MONITORING

API REFERENCE

Prerequisites

User Management Workflow Overview

Step 1: Subscription Management

Enabling & disabling a subscription

Getting subscriptions by id

Getting subscriptions by wallet

Getting subscribers by app

Deleting a subscription

Step 2: Channel Management

Add User Email Address

Verify an address

Get addresses owned by a wallet

Unsubscribe from specific channels

Update an address

Remove an address

Push Notifications

Step 3: Topic Management

Create a new notification type

Update an existing notification type

Get all topics

Unsubscribe from topics

Get topic subscription status

Best Practices

Next Steps

​Prerequisites

​User Management Workflow Overview

​Step 1: Subscription Management

​Subscribe user

​Enabling & disabling a subscription

​Getting subscriptions by id

​Getting subscriptions by wallet

​Getting subscribers by app

​Deleting a subscription

​Step 2: Channel Management

​Add User Email Address

​Verify an address

​Get addresses owned by a wallet

​Subscribe to specific channels

​Unsubscribe from specific channels

​Update an address

​Remove an address

​Push Notifications

​Step 3: Topic Management

​Create a new notification type

​Update an existing notification type

​Get all topics

​Subscribe to topics

​Unsubscribe from topics

​Get topic subscription status

​Best Practices

​Next Steps

Prerequisites

User Management Workflow Overview

Step 1: Subscription Management

Subscribe user

Enabling & disabling a subscription

Getting subscriptions by id

Getting subscriptions by wallet

Getting subscribers by app

Deleting a subscription

Step 2: Channel Management

Add User Email Address

Verify an address

Get addresses owned by a wallet

Subscribe to specific channels

Unsubscribe from specific channels

Update an address

Remove an address

Push Notifications

Step 3: Topic Management

Create a new notification type

Update an existing notification type

Get all topics

Subscribe to topics

Unsubscribe from topics

Get topic subscription status

Best Practices

Next Steps