Receive Push Notifications

In this section, you will learn how you can implement push notifications in your application using Dialect's push notification API. Push notifications allow your application to notify users about important events even when they're not actively using your application.

Prerequisites

Before implementing push notifications with Dialect:

Set up Firebase Cloud Messaging in your application
- Follow Firebase's documentation to add the Firebase SDK to your app
- Implement the necessary code to request and receive an FCM token
Implement wallet integration for Solana signature verification
- Your app must be able to request message signing from the user's wallet

Once these prerequisites are in place, you can proceed with the authentication and subscription flows.

Get Auth Token

This is the first step and required to receive a Bearer token, which is used to authenticate the user with Dialect's APIs and manage the user's subscription. The authentication process uses a message format that is similar to Sign-in with Solana (SIWS), which forces users to sign a message with their wallet to prove ownership and login to your application.

1. Request a message to sign

First, request a message containing a nonce (a one-time value) that the user will sign:

curl https://alerts-api.dial.to/v2/auth/solana/prepare \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "walletAddress": "YOUR_WALLET_ADDRESS"
}'

The response will contain a message with a nonce:

{
  "message": "Sign this message to authenticate. Nonce: 1638471298347"
}

If you want to test the endpoints, visit the /prepare endpoint in our API docs.

2. Sign the message

In this step, the user has to sign this message with their Solana wallet. The exact implementation depends on which wallet provider you're using, but typically involves calling a ⁠signMessage method. You can find a sign and verify message example in the Solana Cookbook.

3. Verify the signature

After obtaining the signature, send it back to the server for verification:

curl https://alerts-api.dial.to/v2/auth/solana/verify \
 --request POST \
 --header 'Content-Type: application/json' \
 --data '{
   "message": "Sign this message to authenticate. Nonce: 1638471298347",
   "signature": "WALLET_SIGNATURE"
}'

If verification was successful, the server will return an authentication token:

{
   "token": "YOUR_AUTH_TOKEN",
   "subscriber": {
      "walletAddress": "YOUR_WALLET_ADDRESS"
   }
}

This token should be stored securely and used for the API calls that require authentication.

If you want to test the endpoints, visit the /verify endpoint in our API docs.

4. Check status (optional)

To ensure that a user is authenticated and can receive notifications, you can use the /auth endpoint.

curl https://alerts-api.dial.to/v2/auth \
  --request GET \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN'

This endpoint will either return a 401 error, if user is unauthenticated or the wallet address if authentication was successful.

{
  "walletAddress": "6CxnSjtasq5Tzwb4b93AhLofXtiDvMpQ2vTkWdSZqTH7"
}

If you want to test the endpoints, visit the /auth endpoint in our API docs.

tip

We recommend to subscribe for push notifications on app start and when adding new wallets.

Once a user is authenticated, you can register their device to receive push notifications. This involves obtaining an FCM token and associating it with the user's wallet address via our subscribe endpoint.

1. Obtain Firebase Cloud Messaging (FCM) Token

Before you can subscribe to push notifications, you need to obtain an FCM token from Firebase.

Android
iOS
Web

// Assuming you have Firebase initialized in your application
// FirebaseMessaging instance is obtained from the Firebase SDK
FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
    if (!task.isSuccessful) {
        // Handle error
        Log.w("FCM", "Failed to get FCM token", task.exception)
        return@addOnCompleteListener
    }
    
    // Get FCM token
    val fcmToken = task.result
    
    // Store token for later use or send to your server
    // ...
}

// Assuming you have Firebase initialized in your application
// Messaging instance is obtained from Firebase SDK
Messaging.messaging().token { token, error in
    if let error = error {
        // Handle error
        print("Error fetching FCM token: \(error)")
        return
    }
    
    if let token = token {
        // Store FCM token for later use or send to your server
        // ...
    }
}

// Import required Firebase modules
import { getMessaging, getToken } from "firebase/messaging";

// Assuming Firebase is already initialized in your application
// Get messaging instance from Firebase
const messaging = getMessaging();

try {
    // Get registration token with your VAPID key
    // Initially this makes a network call, subsequent calls return
    const currentToken = await getToken(messaging, {
        vapidKey: 'YOUR_PUBLIC_VAPID_KEY_HERE'
    });
    
    if (currentToken) {
        // Store FCM token for later use
        // ...
    } else {
        // Show permission request UI
        console.log('No registration token available. Request permission to generate one.');
        // ...
    }
} catch (err) {
    console.error('An error occurred while retrieving token:', err);
    // Handle error appropriately
    // ...
}

For more detailed implementation instructions please visit the Firebase Cloud Messaging documentation for iOS, Android and Web.

2. Verify Authentication (Optional)

Before subscribing, you can optionally verify that the user is properly authenticated.

curl https://alerts-api.dial.to/v2/push/subscribe \
 --request POST \
 --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
 --header 'Content-Type: application/json' \
 --data '{
   "appId": "YOUR_APP_ID",
   "deviceId": "UNIQUE_DEVICE_ID",
   "fcmToken": "FIREBASE_FCM_TOKEN"
}'

Parameters:

⁠appId: Your application's unique identifier (provided by Dialect)
⁠deviceId: (Optional) Identifier for the user's device
⁠fcmToken: Firebase Cloud Messaging token from the FCM SDK

The subscription process associates the user's wallet address with their device, allowing your application to send targeted push notifications to this specific device.

If you want to test the endpoints, visit the /subscribe endpoint in our API docs.

Unsubscribe from Push Notifications

The unsubscribe endpoint allows you to remove a device from the notification system.

tip

Always use unsubscribe when removing wallets from app.

curl https://alerts-api.dial.to/v2/push/unsubscribe \
 --request POST \
 --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
 --header 'Content-Type: application/json' \
 --data '{
   "appId": "YOUR_APP_ID",
   "deviceId": "UNIQUE_DEVICE_ID",
   "fcmToken": "FIREBASE_FCM_TOKEN"
}'

The unsubscribe endpoint requires the same parameters as the subscribe endpoint:

⁠appId: Your application's unique identifier (provided by Dialect)
⁠deviceId: (Optional) Identifier for the user's device
⁠fcmToken: Firebase Cloud Messaging token from the FCM SDK

After unsubscribing, the device will no longer receive push notifications from your application.

If you want to test the endpoints, visit the /unsubscribe endpoint in our API docs.

Prerequisites​

Get Auth Token​

1. Request a message to sign​

2. Sign the message​

3. Verify the signature​

4. Check status (optional)​

Subscribe to Push Notifications​

1. Obtain Firebase Cloud Messaging (FCM) Token​

2. Verify Authentication (Optional)​

3. Subscribe to Notifications​

Unsubscribe from Push Notifications​