Arifa, Realtime Event Delivery Simplified

Get user-centric realtime features live in your app in minutes, not days. Arifa delivers notifications, alerts, and live UI updates with a single HTTP request no complex channels, no connection management, and zero reconnection logic to write.

Forget configuration overhead. With Arifa, you think about users, not channels. Send events directly to a user and let our managed infrastructure handle the rest, including built-in presence tracking.

Arifa is lightweight, fast, and made for production use.

Why Arifa is Different

• User-Centric, Not Channel-Centric: Our core model is built around users (user_uuid), not pub/sub channels. It’s intuitive and cuts your code in half.

• Built-In Presence: See Success or Pending events instantly, tracked automatically per API key. No extra setup or code required.

• Predictable Pricing: Simple, monthly plans based on concurrent connections. Scale your users, not your billing anxiety.

• Production Ready & Lightweight: Built with Redis and Actix-Web for low-latency delivery at scale, following a lean "deliver and forget" philosophy.

Get Started in Under 5 Minutes

1. Sign up for a free Arifa account.

2. Grab your API Key from the dashboard (use the free Test Key for development).

3. Install the client SDK and connect a user.

4. Send your first event with a simple POST request.

Core Features

• Instant WebSocket Delivery: Events are routed directly to the target user's active connection.

• Offline Queue: Messages for offline users are queued and delivered on their next connection.

• Automatic Cleanup: Delivered messages are automatically cleaned from the queue weekly.

• End-to-End Security: All connections are secured with TLS.

What You Need

1. An Arifa account (Start with a free Developer plan).

2. A subscription plan for Live API Keys (Hobby: $6/mo, Startup: $25/mo).

3. A Test Key (valid 4 hours) for initial development and prototyping.

Ready to build? Visit Arifa to get started.

Explore the SDK: npm install arifa-client, npm i arifa-notifications

Getting Started, Live in Minutes

Welcome to Arifa. You're about 5 minutes away from adding real-time features to your app. This guide walks you from sign-up to your first live event.

1. Create a Free Account

Visit app.arifa.dev to sign up and verify your email. This gives you instant access to your dashboard and a free Developer plan.

2. Choose Your Path: Test or Live

You can start building immediately. Choose the path that fits your stage:

Prototype & Test (Free & Instant)

Arifa provides Test API Key in your dashboard. Use it to build and validate your integration.

• Valid for 4 hours (one-time generation).
• Perfect for your first POST request and SDK connection.
• No payment required.

Go Live with a Plan

To obtain a permanent Live API Key and connect real users, subscribe to a plan.

• Plans Start At: Hobby (Ksh 900/mo), Startup (Ksh 3,500/mo).
• Payment: Securely handled via M-Pesa.
• Upgrade anytime from your dashboard when you're ready to launch.

3. Install & Integrate

With your API key in hand, the real magic happens in your code,

Vistit these sdks for fast Integration:

• arifa client

JavaScript/TypeScript client SDK for Arifa Realtime Notification Service.Allows you to connect via WebSocket, listen to events, and send notifications using HTTP.

• arifa notifications

A React notification component with WebSocket support for real-time notifications from Arifa.Allows developers to easily integrate notifications in any React app and fully control how notifications are rendered.

That's it. Your app now has real-time capabilities. No channel configuration, no complex setup, just users and events.

Next Steps

• Visit your Dashboard to monitor connections and events.
• Check your plan usage and upgrade when needed.

Need help? Reach out at support

Authentication & API Keys

Arifa uses API keys to authenticate and identify your application when connecting to realtime services

Types of Keys

How to Use Your API Key

Your API key needs to be included in two places:

1. When connecting (in the WebSocket URL)

2. When sending notifications (in the HTTP request)

Passing the API Key

API keys are included in:

• WebSocket URL query parameters
• HTTP POST body when sending notifications

Example (WebSocket URL)

wss://notifications.arifa.dev/ws/connect?api_key=YOUR_API_KEY&recipient=UUID&client=web or mobile

Parameters:

1. api_key - Your authentication key (required)

2. recipient - Target user UUID (required, must be valid UUID v4)

3. client - Client type: web or mobile (required)

Security Requirements

UUID Format Validation

The recipient parameter must adhere to UUID v4 format specifications:

• Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx

• Version: 4 (indicated by the third group starting with '4')

• Variant: RFC 4122 (indicated by 'y' being 8, 9, A, or B)

• Examples:

  • Valid: 550e8400-e29b-41d4-a716-446655440000

  • Invalid: user-123, 12345678, 550e8400-e29b-11d4-a716-446655440000 (version 1)

Key Management Best Practices

• Store keys securely - Never commit API keys to version control

• Key rotation - Regularly rotate production keys

• Access control - Restrict key usage to authorized applications only

• Monitoring - Monitor API key usage for suspicious activity

Troubleshooting

Error Responses

• 429 Too Many Requests - Concurrent connection limit reached

• 401 Unauthorized - Invalid or missing API key

• 400 Bad Request - Invalid UUID format or missing required parameters

• 403 Forbidden - Insufficient permissions or rate limit exceeded

How We Do It!

Arifa is a realtime event delivery platform that enables applications to send and receive data/events/notifications instantly using WebSockets, with automatic fallback to offline persistence when users are not connected.

This documentation covers:

• Realtime WebSocket behavior

• HTTP notification dispatch

• React notification UI component

• Best practices and lifecycle management

Architecture Overview

Arifa uses a hybrid real-time model that combines WebSockets and HTTP to ensure reliable event delivery.

Flow summary

• Client connects via WebSocket using API key

• Client subscribes to a recipient UUID

• Server pushes events in real time

• If recipient is offline, notifications are stored

• Stored notifications are delivered on reconnection

Arifa SDK – Powering RealTime Experiences

Deliver instant events and notifications with arifa-client and arifa-notifications.
Reliable, flexible, and easy to integrate into web or mobile apps.

Overview

Everything you need to send, receive, and display notifications in real time.

ArifaClient SDK

JavaScript/TypeScript client SDK for Arifa Realtime Event Service.
Allows you to connect via WebSocket, listen to events, and send Events using HTTP.

Installation

npm install arifa-client

or using Yarn:

yarn add arifa-client

Usage

Import and Initialize

import ArifaClient from "arifa-client";

const client = new ArifaClient({
  apiKey: "YOUR_API_KEY",
  client: "web", // "web" or "mobile"
});

Listen to Connection State

client.onConnectionChange((state) => {
  console.log("Connection state:", state); // "connected" or "disconnected"
});

Subscribe Recipient

Note: Recipient must be UUID

const sub = client.subscribe("RECIPIENT_UUID");

// Listen for events
sub.listen((event) => {
  console.log("Received event:", event);
});

// Unsubscribe when done
sub.unsubscribe();

Send a Event/Notification/Data

const res = await client.notify({
  recipient: "RECIPIENT_UUID",
  payload: {
    title: "Hello",
    message: "Welcome to Arifa!",
  }, // Can be any JSON data
  origin: "https://your-registered-domain.com", // Optional, use if web
  client: "web", // Optional, "web" or "mobile"
});

console.log(res);

• recipient → UUID of the user

• payload→ Any JSON object

• orign→ Optional string; typically your registered domain when sending from web.

• client → Optional, "web" or "mobile"

Note: The notify method returns a result object with the notification status. Example responses:

• "sent" → Notification successfully sent to a connected user

• "User offline, notification saved" → User is offline; the message was stored for later delivery

• "Failed to send/save notification" → There was an error sending or saving the notification

Disconnect

client.disconnect();

Check Connection Status

if (client.connected()) {
  console.log("WebSocket is connected");
} else {
  console.log("WebSocket is disconnected");
}

Arifa Notifications SDK

Note: The notification bell icon turns green when the WebSocket is connected and red when disconnected.

A React notification component with WebSocket support for real-time notifications from Arifa.
Allows developers to easily integrate notifications in any React app and fully control how notifications are rendered.

Features

• Real-time notifications via WebSocket
• Fully headless: you control rendering of messages
• Unread indicators and notification sounds
• Flexible: works with any data shape (object, array, or custom)
• Easy to integrate in React apps

Installation

npm install arifa-notifications react-icons

Peer dependencies: React and ReactDOM (>= 18.0.0)

Usage

import React from "react";
import { ArifaNotification } from "arifa-notifications";
import "arifa-notifications/styles/arifa-notification.css";
import "arifa-notifications/styles/notification-dropdown.css";

export default function App() {
  return (
    <div>
      <h1>My App</h1>

      <ArifaNotification
        apikey="YOUR_API_KEY"
        userID="USER_ID"
        path="YOUR FULL NOTIFICATIONS PAGE PATH"
        soundUrl="" // path to your bell ring file or leave blank
        dropdownClassName="my-dropdown"
        headerClassName="my-header"
        titleClassName="my-title"
        closeButtonClassName="my-close-btn"
        contentClassName="my-content"
        emptyStateClassName="my-empty"
        footerClassName="my-footer"
        viewAllClassName="my-view-all"
        poweredByClassName="my-powered-by"
        poweredByLinkClassName="my-powered-by-link"
      >
        {(data) => (
          <div>
            {data.map((item: any, i: number) => (
              <NotificationCard key={i} payload={item} />
            ))}
          </div>
        )}
      </ArifaNotification>
    </div>
  );
}

Props

Customizing Styles

You can control every style of the dropdown by passing custom class names via the props above. Tip: If your custom styles are not applied due to default CSS specificity, use !important in your CSS rules.

WebSocket Connection

Arifa uses secure WebSocket (WSS) connections.

Connection Format

wss://notifications.arifa.dev/ws/connect?api_key=YOUR_API_KEY&recipient=UUID&client=web/mobile

Required Parameters:

Example in JavaScript

const ws = new WebSocket(
  "wss://notifications.arifa.dev/ws/connect?api_key=TEST_123&recipient=2fdb5a8e-62fc-4af2-9c41-807c3e9a8b17&client=web/mobile"
);

ws.onmessage = (msg) => {
  console.log("Received:", msg.data);
};

When WebSocket Opens

The user is considered online, and notifications will be delivered instantly.

Sending Notifications

Notifications are sent using a POST request.

Endpoint

POST https://notifications.arifa.dev/notify

Notes

If you are running this from a script, make sure to include the Origin header. The value must match the domain you registered when creating a web API key; otherwise, the request will be rejected.

Required JSON Body

{
  "recipient": "UUID_of_user",
  "payload": {   # Payload can be any JSON structure based on your need
    "title": "Hello",
    "body": "Welcome to Arifa!"
  },
  "api_key": "YOUR_API_KEY",
  "client" : <"web" or "mobile">
}

Notes

• recipient → must be a valid UUID
• payload → must be valid JSON
  • The payload field can contain any JSON structure based on your needs — as long as it is valid JSON.
    • You can include custom keys
    • Nested objects
    • Arrays
    • Any format your application requires
• api_key → must be included and valid
• client → "web" or "mobile"

curl -X POST https://notifications.arifa.dev/notify \
  -H "Content-Type: application/json" \
  -H "Origin: http://localhost:5173" \ # The registred domain for the api key if web
  -d '{
    "recipient": "e3ec1c15-baf1-4ebf-82df-3d0b66ed9982",
    "payload": { "message": "Test" }, // Message can b
    "api_key": <API KEY>,
    "client" : "web"
  }'

Offline Delivery & Storage Behavior

Arifa does not permanently store user notifications.

When a User Is Online

• Notifications are delivered instantly via WebSocket.
• Messages are not saved.

When a User Is Offline

• Notification is stored temporarily.
• Delivered automatically when the user reconnects.

Weekly Cleanup

• All delivered messages are deleted weekly.
• Undelivered messages remain until the user comes online.

Privacy

• Arifa never stores your data permanently.
• Only offline pending messages are kept.

FAQ

Do you store user notifications?

Only when a user is offline.
Delivered messages are deleted weekly.

How long are test keys valid?

4 hours. Test keys are one-time generated.

Can I regenerate a test key?

No , you may request support to reset it.

Why must user_id be a UUID?

It ensures unique users and prevents collisions across unrelated apps.

Where do I send notifications?

POST https://notifications.arifa.dev/bff_v001/notify

How do I connect to WebSocket?

Use: wss://notifications.arifa.dev/ws/connect?api_key=KEY&recipient=UUID&client=web or mobile

Do you support mobile apps?

Yes: Android, iOS, and React Native via WebSocket.