🔔 Send In-App Notifications

Prerequisites

A NotificationAPI account - sign up for free
An in-app notification configured in the dashboard (see Configure Notification)

Overview

In-app notifications are messages that appear directly inside your web application, typically displayed in a notification center or as popups. These notifications provide real-time updates to users without requiring them to check emails or external channels.

NotificationAPI makes it easy to send and display personalized in-app notifications with features like real-time delivery, custom UI components, batching, and user interaction tracking.

This comprehensive guide covers everything you need to know about in-app notifications: sending them from your backend and displaying them in your frontend.

Step 1: Verify Your In-App Notification

If you haven’t already configured an in-app notification, follow our Configure Notification guide to create one with the In-App channel enabled.

Once configured, note the Notification Type - you’ll need this in your code (e.g., user_mention, task_assigned, system_alert).

Backend Integration - Sending Notifications

Step 2: Install the Server-Side SDK

Install the node package using one of the following package managers:

npm install notificationapi-node-server-sdk

yarn add notificationapi-node-server-sdk

pnpm add notificationapi-node-server-sdk

pip install notificationapi_python_server_sdk

composer require notificationapi/notificationapi-php-server-sdk

go get github.com/notificationapi-com/notificationapi-go-server-sdk

dotnet add package NotificationAPI --version 0.5.0

Add the following dependency to your Maven project:

<dependency>
    <groupId>com.notificationapi</groupId>
    <artifactId>notificationapi-java-server-sdk</artifactId>
    <version>0.2.0</version>
</dependency>

For optimal functionality, you’ll also need:

<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5.14</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.15.2</version>
</dependency>

Add the NotificationAPI class to your application - see the full Ruby implementation.

Step 3: Send a Basic In-App Notification

Here’s how to send a basic in-app notification that will appear in your user’s notification center:

import notificationapi from 'notificationapi-node-server-sdk';

// Initialize (default US region)
// For CA region: add 'https://api.ca.notificationapi.com' after CLIENT_SECRET
// For EU region: add 'https://api.eu.notificationapi.com' after CLIENT_SECRET
notificationapi.init('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');

// Send in-app notification
notificationapi.send({
  type: 'task_assigned',
  to: {
    id: 'user123' // Required: user ID for in-app notifications
  },
  parameters: {
    taskName: 'Review quarterly report',
    assignedBy: 'Sarah Johnson',
    dueDate: 'March 15, 2024'
  }
});

import asyncio
from notificationapi_python_server_sdk import notificationapi

# Initialize (default US region)
notificationapi.init("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")

async def send_inapp():
    await notificationapi.send({
        "type": "task_assigned",
        "to": {
            "id": "user123"  # Required: user ID for in-app notifications
        },
        "parameters": {
            "taskName": "Review quarterly report",
            "assignedBy": "Sarah Johnson",
            "dueDate": "March 15, 2024"
        }
    })

# Run the async function
asyncio.run(send_inapp())

use NotificationAPI\NotificationAPI;

// Initialize
$notificationapi = new NotificationAPI('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');

// Send in-app notification
$notificationapi->send([
    "type" => "task_assigned",
    "to" => [
        "id" => "user123"  // Required: user ID for in-app notifications
    ],
    "parameters" => [
        "taskName" => "Review quarterly report",
        "assignedBy" => "Sarah Johnson",
        "dueDate" => "March 15, 2024"
    ]
]);

package main

import (
    notificationapi "github.com/notificationapi-com/notificationapi-go-server-sdk"
)

func main() {
    // Initialize
    notificationapi.Init("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET", "https://api.notificationapi.com")

    // Prepare parameters
    parameters := make(map[string]interface{})
    parameters["taskName"] = "Review quarterly report"
    parameters["assignedBy"] = "Sarah Johnson"
    parameters["dueDate"] = "March 15, 2024"

    // Send in-app notification
    notificationapi.Send(
        notificationapi.SendRequest{
            Type: "task_assigned",
            To: notificationapi.User{
                Id: "user123",  // Required: user ID for in-app notifications
            },
            Parameters: parameters,
        },
    )
}

using NotificationApi.Server;
using NotificationApi.Server.Models;

// Initialize
var notificationApi = new NotificationApiServer("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");

// Create user
var user = new NotificationUser("user123");  // Required: user ID for in-app notifications

// Create parameters
var parameters = new Dictionary<string, object>
{
    { "taskName", "Review quarterly report" },
    { "assignedBy", "Sarah Johnson" },
    { "dueDate", "March 15, 2024" }
};

// Send in-app notification
await notificationApi.Send(new SendNotificationData("task_assigned", user)
{
    Type = "task_assigned",
    To = user,
    Parameters = parameters
});

import com.notificationapi.NotificationApi;
import com.notificationapi.model.NotificationRequest;
import com.notificationapi.model.User;
import java.util.HashMap;
import java.util.Map;

// Initialize
NotificationApi api = new NotificationApi("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");

// Create user
User user = new User("user123");  // Required: user ID for in-app notifications

// Create parameters
Map<String, Object> parameters = new HashMap<>();
parameters.put("taskName", "Review quarterly report");
parameters.put("assignedBy", "Sarah Johnson");
parameters.put("dueDate", "March 15, 2024");

// Send in-app notification
NotificationRequest request = new NotificationRequest("task_assigned", user)
    .setType("task_assigned")
    .setTo(user)
    .setParameters(parameters);

String response = api.send(request);

# Initialize
notificationapi = NotificationAPI.new("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")

# Send in-app notification
notificationapi.send({
  type: 'task_assigned',
  to: {
    id: 'user123'  # Required: user ID for in-app notifications
  },
  parameters: {
    taskName: 'Review quarterly report',
    assignedBy: 'Sarah Johnson',
    dueDate: 'March 15, 2024'
  }
})

INFO

Get your CLIENT_ID and CLIENT_SECRET from your Environment Settings.

Step 4: Advanced In-App Features

Custom Click Actions and Redirects

You can configure in-app notifications to redirect users to specific pages when clicked:

notificationapi.send({
  type: 'user_mention',
  to: {
    id: 'user456'
  },
  parameters: {
    mentionedBy: 'Alex Smith',
    commentText: 'Great job on the new feature!',
    postTitle: 'Q1 Product Updates'
  },
  // Optional: URL to redirect when notification is clicked
  redirectUrl: 'https://yourapp.com/posts/q1-updates#comment-123'
});

await notificationapi.send({
    "type": "user_mention",
    "to": {
        "id": "user456"
    },
    "parameters": {
        "mentionedBy": "Alex Smith",
        "commentText": "Great job on the new feature!",
        "postTitle": "Q1 Product Updates"
    },
    "redirectUrl": "https://yourapp.com/posts/q1-updates#comment-123"
})

$notificationapi->send([
    "type" => "user_mention",
    "to" => [
        "id" => "user456"
    ],
    "parameters" => [
        "mentionedBy" => "Alex Smith",
        "commentText" => "Great job on the new feature!",
        "postTitle" => "Q1 Product Updates"
    ],
    "redirectUrl" => "https://yourapp.com/posts/q1-updates#comment-123"
]);

Rich Content with Images and Custom Icons

Enhance your in-app notifications with visual elements:

notificationapi.send({
  type: 'system_alert',
  to: {
    id: 'user789'
  },
  parameters: {
    alertType: 'security',
    message: 'New login detected from San Francisco',
    deviceInfo: 'Chrome on MacOS',
    time: '2:45 PM PST'
  },
  // Optional: Custom image for the notification
  imageUrl: 'https://yourapp.com/icons/security-alert.png'
});

await notificationapi.send({
    "type": "system_alert",
    "to": {
        "id": "user789"
    },
    "parameters": {
        "alertType": "security",
        "message": "New login detected from San Francisco",
        "deviceInfo": "Chrome on MacOS",
        "time": "2:45 PM PST"
    },
    "imageUrl": "https://yourapp.com/icons/security-alert.png"
})

$notificationapi->send([
    "type" => "system_alert",
    "to" => [
        "id" => "user789"
    ],
    "parameters" => [
        "alertType" => "security",
        "message" => "New login detected from San Francisco",
        "deviceInfo" => "Chrome on MacOS",
        "time" => "2:45 PM PST"
    ],
    "imageUrl" => "https://yourapp.com/icons/security-alert.png"
]);

Step 5: In-App Notification Personalization with Parameters

Parameters allow you to inject dynamic content into your in-app notifications:

Common In-App Use Cases

// Team collaboration notification
notificationapi.send({
  type: 'document_shared',
  to: {
    id: 'collaborator123'
  },
  parameters: {
    sharedBy: 'Emily Chen',
    documentName: 'Marketing Strategy 2024',
    accessLevel: 'Editor',
    teamName: 'Marketing Team'
  },
  redirectUrl: 'https://yourapp.com/documents/marketing-strategy-2024'
});

// Achievement notification
notificationapi.send({
  type: 'achievement_unlocked',
  to: {
    id: 'user456'
  },
  parameters: {
    achievementName: 'First Sale',
    achievementDescription: 'Congratulations on your first successful sale!',
    pointsEarned: 100,
    badgeUrl: 'https://yourapp.com/badges/first-sale.png'
  }
});

// Project update notification
notificationapi.send({
  type: 'project_status_update',
  to: {
    id: 'team_lead789'
  },
  parameters: {
    projectName: 'Website Redesign',
    newStatus: 'In Review',
    updatedBy: 'Development Team',
    completionPercentage: 85,
    nextMilestone: 'User Testing'
  },
  redirectUrl: 'https://yourapp.com/projects/website-redesign'
});

Using Parameters in In-App Templates

In your in-app notification template designer, reference parameters using double curly braces:

Title: {{achievementName}} unlocked!
Message: {{achievementDescription}} You earned {{pointsEarned}} points.

TIP

In-app notifications support rich HTML content, emojis, and can include action buttons for enhanced user interaction.

Real-Time Delivery and Batching

Real-Time Features

In-app notifications are delivered in real-time through WebSocket connections:

Instant delivery: Notifications appear immediately when sent
Live updates: No page refresh required
Automatic reconnection: Handles network interruptions gracefully
Offline support: Queues notifications when user is offline

Smart Batching

Group related notifications to avoid overwhelming users:

// Multiple comments on the same post will be batched together
notificationapi.send({
  type: 'new_comment',
  to: {
    id: 'post_author123'
  },
  parameters: {
    commenterName: 'John Doe',
    commentText: 'This is really helpful!',
    postId: 'post-456',
    postTitle: 'Getting Started with React'
  },
  // Batching key: notifications with same key will be grouped
  batchingKey: 'post-456'
});

await notificationapi.send({
    "type": "new_comment",
    "to": {
        "id": "post_author123"
    },
    "parameters": {
        "commenterName": "John Doe",
        "commentText": "This is really helpful!",
        "postId": "post-456",
        "postTitle": "Getting Started with React"
    },
    "batchingKey": "post-456"
})

Frontend Integration - Display Notifications

WARNING

Unlike emails or SMS, in-app notifications require frontend integration to display in your application. Both backend sending (above) and frontend display (below) are required.

Step 6: Install the Frontend SDK

Choose the appropriate SDK for your framework:

For React applications, install the React SDK:

npm install @notificationapi/react

yarn add @notificationapi/react

pnpm add @notificationapi/react

For other frameworks or custom implementations, install the JS Core SDK:

npm install @notificationapi/js-core

yarn add @notificationapi/js-core

pnpm add @notificationapi/js-core

The widget automatically connects to our servers and displays notifications in real-time. Choose your implementation:

Use the React SDK for React/Next.js applications:

import {
  NotificationAPIProvider,
  NotificationPopup
} from '@notificationapi/react';

function App() {
  return (
    <NotificationAPIProvider clientId="YOUR_CLIENT_ID" userId="USER_ID">
      <div>
        {/* Your app content */}
        <NotificationPopup />
      </div>
    </NotificationAPIProvider>
  );
}

export default App;

For Next.js, wrap your app in _app.js or layout:

// _app.js or layout.js
import { NotificationAPIProvider } from '@notificationapi/react';

export default function MyApp({ Component, pageProps }) {
  return (
    <NotificationAPIProvider clientId="YOUR_CLIENT_ID" userId="USER_ID">
      <Component {...pageProps} />
    </NotificationAPIProvider>
  );
}

Use JS Core for custom implementations and headless integrations. This provides you with the core functionality without any UI components, giving you full control over the presentation.

What JS Core provides:

Real-time notification delivery via WebSocket
Notification state management (read/unread, archived)
User preference handling
Custom event callbacks for notification actions
Complete control over UI design and behavior

Basic Integration:

<div id="notification-container"></div>

<script type="module">
  import NotificationAPI from '@notificationapi/js-core';

  const client = new NotificationAPI({
    clientId: 'YOUR_CLIENT_ID',
    userId: 'USER_ID'
  });

  // Option 1: Use built-in UI widget
  client.showInApp({
    root: 'notification-container'
  });

  // Option 2: Build custom UI with headless mode
  client.onNewNotification((notification) => {
    // Handle new notifications with your custom UI
    console.log('New notification:', notification);
  });
</script>