Introduction

Welcome to the ultimate synchronization infrastructure. BeeZync is a dual engine that includes two enterprise-grade services seamlessly integrated into your plan:

Service 1

WEBSOCKETS

Live bidirectional messaging for browsers and apps. Millisecond latency for dashboards, chats, and collaborative tools while the user has the app open.

Service 2

PUSH NOTIFICATIONS

Reconnect with your users even when the app is closed or running in the background. Direct native alerts to the operating system (iOS, Android, macOS).

Key Concepts & Magical Synergy

BeeZync's unfair advantage over traditional services lies in the intelligent combination of our engines. You are not buying two isolated services; you are accessing a next-generation messaging orchestrator.

1
Hybrid Project (Dual Engine) Every application you create natively encompasses both the WebSockets engine and the Push Notifications ecosystem. You don't need to configure separate architectures.
2
Smart Delivery (Intelligent Routing) Killer Feature
This is the true superpower of BeeZync to take your app to the next level. When you dispatch a notification, our intelligent engine makes a decision in milliseconds:

If the user has the app open (Active): BeeZync intercepts the dispatch and delivers it directly via the WebSocket. This ensures instant delivery (zero latency), saves battery, bypasses provider limits/delays (Apple/Google), and enables super smooth animations (in-app alerts) within your app.

If the user has the app closed (Inactive): The engine silently delegates the payload to Firebase (FCM) or Apple (APNs). The phone's operating system takes care of waking up the screen and displaying the native Push alert. All this automatically without you writing conditional logic!
3
Unified Asynchronous Dispatch Whether you send a massive Push to a million users or a single WebSocket event, we queue the request and distribute it globally without throttling your backend server resources.

Quick Start

A quick glance at how to interact with the platform's two main engines in under a minute.

// 1. Connect client to the WEBSOCKET engine
const wsUrl = `wss://api.beezync.com/v1/ws?app_id=YOUR_APP_ID&api_key=YOUR_APP_KEY`;
const socket = new WebSocket(wsUrl);

socket.onopen = () => {
    // Subscribe to a channel
    socket.send(JSON.stringify({ action: "subscribe", channel: "general" }));
};

socket.onmessage = (event) => {
    console.log('Socket Event Received!', JSON.parse(event.data));
};

// 2. Dispatch WEBSOCKET message from Laravel
Http::withHeaders([
    'Authorization' => 'Bearer YOUR_APP_KEY',
])->post('https://api.beezync.com/v1/api/send-ws', [
    'app_id'  => 'YOUR_APP_ID',
    'channel' => 'general',
    'payload' => [
        'message' => 'Hello world in real-time!'
    ]
]);

curl -X POST https://api.beezync.com/v1/api/send-ws \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "channel": "general",
    "payload": { "message": "Hello from terminal" }
  }'

// Dispatch a massive PUSH notification from Laravel
Http::withHeaders([
    'Authorization' => 'Bearer YOUR_APP_KEY',
])->post('https://api.beezync.com/v1/api/send-push', [
    'app_id'      => 'YOUR_APP_ID',
    'target_type' => 'all',
    'title'       => 'Great Sale!',
    'body'        => 'Discover our new promotions.'
]);

curl -X POST https://api.beezync.com/v1/api/send-push \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "target_type": "all",
    "title": "Great Sale!",
    "body": "Discover our new promotions."
  }'

Authentication Global

All requests to the BeeZync REST API (to send WebSocket or Push messages) require secure authentication. You must send your App Key in the HTTP Authorization header using the Bearer scheme.

Security: Keep your App Key a secret (e.g., in your .env file). Never expose your App Key in frontend client code. The frontend only uses it temporarily to initialize the secure WebSocket connection, not for REST requests.

WebSocket Dispatch WEBSOCKET

This service broadcasts real-time messages to browsers/apps that have an active connection to the BeeZync socket. Endpoint: POST /v1/api/send-ws

Request Body (JSON)

Parameter	Type	Description
app_id	string (required)	The UUID of your application.
channel	string (required)	The name of the WebSocket channel to dispatch to (e.g. `chat.room.12`).
payload	object (required)	JSON object with the data you want to broadcast to connected clients.

Push Notifications PUSH NOTIFICATION

Use this service to wake up the user's device even if the app is closed. Natively interconnected with APNs and FCM. Endpoint: POST /v1/api/send-push

{
  "app_id": "YOUR_APP_ID",
  "target_type": "all", // "all", "device", "user" or "segmented"
  "title": "New update",
  "body": "Discover the new app features.",
  "data": {
    // Silent payload for the mobile app to process in the background
    "screen": "home",
    "id": 123
  }
}

Filters & Segmentation PUSH NOTIFICATION

For massive campaigns or group transactional notifications, the BeeZync engine allows you to reach your audience using the dynamic compiler with target_type: "segmented".

1. Device Attributes (Native)

Properties that identify the device's subscription and control delivery. These are registered automatically.

Attribute	Description
platform	Client operating system (`ios`, `android`, `web`).
device_id	Unique hardware identifier (UUID generated by the client).
external_user_id	The internal ID of your own database, useful for linking multiple devices (phone and tablet) to a single real user.

2. Custom Metadata (Tags)

Customizable key-value pairs that you send inside the metadata object when registering the device. They are crucial for grouping audiences.

Field	Relation	JSON Filter Example
platform	`=, !=`	`{"field": "platform", "relation": "=", "value": "ios"}`
tag	`=, !=, >, <`	`{"field": "tag", "key": "level", "relation": ">", "value": "10"}`
tag	`contains, array_contains`	`{"field": "tag", "key": "preferences", "relation": "array_contains", "value": "sports"}`

Segmentation Use Cases

Sports News (Array Contains)

Send alert only to users subscribed to the sports channel.

{"field": "tag", "key": "topics", "relation": "array_contains", "value": "sports"}

Regional Promotion (Equality)

Exclusive offer for customers in a specific country.

{"field": "tag", "key": "country", "relation": "=", "value": "US"}

Gamification (Greater than)

Notify players level 50+ about a tournament.

{"field": "tag", "key": "level", "relation": ">", "value": "50"}

Platform Segmentation

Remind only iOS users to update the app.

{"field": "platform", "relation": "=", "value": "ios"}

Web / JS Connection WEBSOCKET

The frontend integration for WebSockets is extremely lightweight. You only need to use the native WebSocket browser API, with no heavy libraries.

// Keep the connection alive in the user's session
const socket = new WebSocket('wss://api.beezync.com/v1/ws?app_id=XYZ&api_key=XYZ');

socket.onmessage = (e) => {
    const payload = JSON.parse(e.data);
    if (payload.channel === 'my_channel') {
        // Update UI, charts, or live counters
        updateDashboard(payload.data);
    }
};

Mobile Registration (iOS/Android) PUSH NOTIFICATION

The Push engine needs to know who your user is. To receive Push notifications, the mobile app must capture and send its physical Token (Google FCM or Apple APNs) to BeeZync. Endpoint: POST /v1/api/register-device

Telemetry Updates: If a user's preferences change (e.g. they buy a premium plan or change their language), simply send this JSON again. BeeZync will perform an automatic `upsert` updating the device's metadata without duplicating it based on its device_id.

{
  "token": "c3a_XYZ_...", // Token generated by the OS (Firebase/APNs)
  "platform": "android", // "ios", "android", or "web"
  "device_id": "unique-phone-uuid",
  "external_user_id": "user_555", // (Optional) Link to an ID from your backend
  "metadata": {
    // Custom tags to use with target_type: "segmented"
    "language": "en",
    "plan": "pro",
    "topics": ["sports", "news"],
    "level": 12
  }
}

Lifecycle and Telemetry GLOBAL

Understanding the device lifecycle is vital to maintaining a clean database and accurate segmentation.

WebSockets (Ephemeral Connections)

WebSocket connections are real-time and do not persist. When a user closes the tab or app, the socket is destroyed. To know who is "online", your backend must register onopen and onclose events or use the upcoming Presence API.

Push Notifications (Persistent Subscriptions)

Push tokens (FCM/APNs) are persistent. If a user uninstalls the app, BeeZync won't know immediately. When you send a Push and the provider (e.g. Google) responds that the token is invalid, BeeZync will automatically mark the device as Unsubscribed (inactive) cleaning your database.