Documentation Release Notes - December 2025

December brought powerful new analytics capabilities, expanded Chat SDK features, and a major update to our AI-assisted development tools to help you build smarter real-time applications.

The biggest additions this month were Query Builder for Illuminate, a preview feature that lets you create flexible queries for ranking and spam detection use cases, and PubNub MCP Server 2.0, which adds API key authentication, support for Codex and Gemini CLI, and an expanded toolset for AI-powered development.

We also documented file sharing and push notifications in the Unity Chat SDK and added comprehensive Service Integrations documentation for programmatic Admin API access.

On the SDK modernization front, we continued removing deprecated push notification services (GCM and MPNS) from the Objective-C SDK, documented IPv6 support and DNS verification in the C-Core SDK, and updated JavaScript SDK logging to use logLevel instead of logVerbosity.

Illuminate 💡

Query Builder documentation

Type: New feature

We documented the new Query Builder feature, currently available in preview. Query Builder extends metrics by adding flexibility and richer logic, letting you define conditions and relationships in a more natural, visual way.

Query Builder includes four predefined queries with default configurations:

Predefined Query	Purpose
Top N	Reward the top 10 users who are most engaged by message count
Bottom N	Incentivize users who are least engaged
Cross-posting spam	Detect users sending duplicate messages across multiple channels
Chat flooding spam	Detect users posting excessive or repetitive messages in a single channel

Each predefined query lets you:

• Select an active Business Object as the data source
• Automatically preselect data fields that best match the use case (User, Channel, Message Text)
• Choose aggregation methods (count of records, count, average, sum, max, min)
• Configure time windows (last 1 minute, 10 minutes, 1 hour)
• Add filters to refine results

Query Builder is ideal for quickly setting up ranking and spam detection use cases, viewing results, and automating actions through Decisions.

Illuminate as a moderation approach

Type: Enhancement

We updated the moderation overview to add Illuminate as a moderation approach for automated spam detection and prevention.

The updated documentation now positions Illuminate alongside other moderation tools:

Approach	When to use
Auto Moderation (AI)	Automated, AI-powered content filtering
Channel Monitor	Manual review of live conversations
Chat SDK Moderation	SDK-level user controls (mute/ban/flag)
Custom Functions	Custom logic with third-party services
Illuminate	Automated pattern detection (chat flooding, cross-posting spam)

Illuminate operates as a reactive moderation approach, analyzing messages after publish to detect spam patterns and automatically take action through Decisions (such as muting or banning users).

Illuminate field updates

Type: Enhancement

We updated the Illuminate documentation with improved field descriptions and clearer guidance on configuring Business Objects, metrics, and Decisions. These updates make it easier to understand how data flows through Illuminate and how to configure each component effectively.

SDKs 📦

Files and push notifications in Unity Chat SDK

Type: New feature

We documented two major features in the Unity Chat SDK: file sharing and mobile push notifications.

File sharing:

The file sharing documentation covers how to attach multiple files to messages, retrieve files from messages and channels, and delete files. Files can be of any format with a maximum size of 5 MB each.

1// Attach a file to a text message
2var files = new List<ChatInputFile>
3{
4    new ChatInputFile
5    {
6        Name = "document.pdf",
7        Type = "application/pdf",
8        Source = "/path/to/document.pdf"
9    }
10};
11

12await channel.SendText("Here's the document", new SendTextParams { Files = files });

Key methods documented:

• SendText() with Files parameter - Send files directly with a message
• MessageDraft.Files - Attach files to draft messages
• GetFiles() - Retrieve all files from a channel with pagination
• DeleteFile() - Remove files from a channel

Mobile push notifications:

The push notifications documentation provides comprehensive guidance on setting up APNs (Apple) and FCM (Firebase) push notifications for Unity chat applications.

The Unity Chat SDK simplifies push notification setup by:

• Handling configuration once during SDK initialization via PushNotifications property
• Providing wrapper methods for channel registration without repeating configuration
• Automatically creating push notification payloads for every message

Key methods documented:

• RegisterForPush() / RegisterPushChannels() - Register channels for push notifications
• GetPushChannels() - List all registered push channels
• UnRegisterFromPush() / UnRegisterPushChannels() - Unregister specific channels
• UnRegisterAllPushChannels() - Disable push notifications on all channels

JavaScript SDK logging configuration update

Type: Enhancement

We updated the JavaScript SDK configuration documentation to reflect the new logging mechanism. The SDK now uses logLevel instead of logVerbosity for configuring log output.

1const pubnub = new PubNub({
2    subscribeKey: "demo",
3    publishKey: "demo",
4    userId: "myUserId",
5    logLevel: PubNub.LogLevel.Debug // New property
6});

Available log levels:

Log Level	Description
PubNub.LogLevel.None	Disable all logging
PubNub.LogLevel.Error	Log errors only
PubNub.LogLevel.Warn	Log warnings and errors
PubNub.LogLevel.Info	Log info, warnings, and errors
PubNub.LogLevel.Debug	Log all messages including debug information
PubNub.LogLevel.Trace	Log everything including detailed trace information

The previous logVerbosity boolean property is deprecated but still supported for backward compatibility.

C-Core SDK updates

Type: Enhancement

We expanded the C-Core SDK documentation with several updates:

HereNow limit parameter:

The HereNow API now supports a limit parameter to control the number of occupants returned per channel, matching the pagination improvements added to other SDKs in November.

IPv6 support:

We documented IPv6 address support for applications that need to work with IPv6 networks. When built with PUBNUB_USE_IPV6 enabled, the SDK:

• Requests both A (IPv4) and AAAA (IPv6) DNS records when resolving the PubNub origin
• Detects available IPv6 routes and selects the optimal connection interface
• Supports IPv6 DNS servers for name resolution
• Handles IPv6 proxy addresses from automated (PAC) proxy discovery

The SDK provides a pubnub_ipv6_address structure for working with IPv6 addresses:

1struct pubnub_ipv6_address {
2    uint8_t ipv6[16];
3};

DNS server validation:

We documented the PUBNUB_DNS_SERVERS_VALIDATION_TIMEOUT configuration option, which validates discovered system DNS servers by sending an actual DNS query during discovery.

1// Validate DNS servers with a 5-second timeout
2#define PUBNUB_DNS_SERVERS_VALIDATION_TIMEOUT 5000

When set to a value greater than 0, the SDK validates that discovered DNS servers are reachable and responsive before using them. This is useful in environments where some DNS servers may be unresponsive or unreachable. Set to 0 (default) to skip validation and use discovered DNS servers directly.

Python SDK HereNow and FCM updates

Type: Enhancement

We updated the Python SDK documentation with HereNow pagination support and Firebase Cloud Messaging (FCM) updates, continuing the SDK modernization effort from previous months.

The updates ensure Python SDK documentation aligns with the latest API capabilities for presence operations and mobile push notifications.

Objective-C SDK push notification modernization

Type: Enhancement

We removed deprecated GCM (Google Cloud Messaging) and MPNS (Microsoft Push Notification Service) references from the Objective-C SDK documentation, completing the push notification modernization for this SDK.

The Objective-C SDK now exclusively uses:

• FCM (Firebase Cloud Messaging) for Android push notifications
• APNs2 (Apple Push Notification service) for iOS push notifications

If your application still references PNPushTypeGCM or PNPushTypeMPNS, update to PNPushTypeFCM and PNPushTypeAPNS2 respectively.

App Context configuration requirement

Type: Enhancement

We added important notes to the App Context documentation clarifying that the "Get All User Metadata" and "Get All Channel Metadata" operations require specific Admin Portal configuration.

To use these operations:

1. Navigate to your keyset in the Admin Portal
2. Enable App Context for your keyset
3. Configure the Disallow Get All User Metadata and Disallow Get All Channel Metadata options as needed

This clarification helps developers understand why these operations might fail even with valid authentication tokens.

AI 🤖

PubNub MCP Server 2.0

Type: New feature

We released PubNub MCP Server 2.0, a major update to our Model Context Protocol server that helps AI-powered development environments build real-time PubNub applications using natural language.

What's new in version 2.0:

• API key authentication - Secure authentication using Service Integrations API keys, replacing the deprecated email/password approach
• Expanded AI agent support - Now supports VS Code, Cursor IDE, Claude Code, Claude Desktop, Codex, and Gemini CLI
• Dynamic and fixed key modes - Choose between working with multiple keysets dynamically or locking to a single keyset for focused workflows
• Docker support - Run the MCP server as a Docker container for Claude Desktop and other environments
• Enhanced toolset - Comprehensive tools for SDK documentation, app/keyset management, real-time messaging, presence, and App Context operations
• Built-in prompts - Pre-configured prompts for common use cases including HIPAA-compliant chat, React applications, game lobbies, and multi-tenant onboarding

New AI agent setup guides:

Codex

codex mcp add PubNub \
  --env PUBNUB_API_KEY=<your-pubnub-api-key> \
  -- npx -y @pubnub/mcp@latest

Gemini CLI

"mcpServers": {
  "pubnub": {
    "command": "npx",
    "args": ["-y", "@pubnub/mcp@latest"],
    "env": {
      "PUBNUB_API_KEY": "<your-api-key>"
    }
  }
}

API key authentication:

The MCP Server now uses API key authentication via the PUBNUB_API_KEY environment variable. This is the recommended authentication method.

API keys provide:

• More secure authentication without storing credentials
• Granular permission control through the Admin Portal
• Easier integration with CI/CD pipelines and automation

The previous PUBNUB_EMAIL and PUBNUB_PASSWORD variables still work but will be deprecated in a future release.

Available tools in MCP Server 2.0:

Category	Tools
Documentation	get_sdk_documentation, get_chat_sdk_documentation
Account & Apps	get_account_info, list_apps, create_app, update_app
Keysets	list_keysets, create_keyset, update_keyset
Real-time	send_pubnub_message, subscribe_and_receive_pubnub_messages
App Context	manage_app_context (users, channels, memberships)
Presence	get_pubnub_presence (HereNow, WhereNow)

Other 🌟

"Return to SDK" navigation banner

Type: New feature

We added a floating navigation banner that appears when you navigate from SDK documentation to General documentation pages. This helps you easily return to your SDK context after reading shared content.

How it works:

• When viewing SDK docs (for example, JavaScript SDK) and clicking a General link in the sidebar, a floating banner appears
• The banner shows "Continue reading [SDK Name] SDK documentation" with a link back to the last SDK page
• The banner persists while navigating within General pages and survives page refresh
• You can dismiss the banner for the entire session

This improvement addresses feedback from developers who found it difficult to return to their SDK documentation after reading related General content.

Service Integrations documentation

Type: New feature

We added comprehensive documentation for Service Integrations, the new way to authenticate programmatic access to the PubNub Admin API using API keys instead of user credentials.

Service Integrations are machine identities in the Admin Portal that represent programs or services consuming the Admin API. The documentation covers:

Use cases:

• Automation scripts that create apps and keysets as part of CI/CD pipelines
• Partner customer onboarding that automatically provisions PubNub resources
• Infrastructure as code tools like Terraform that manage PubNub configuration
• AI-powered development tools like the PubNub MCP Server

Permissions model:

Resource	Scope
Account	All apps and keysets in your account
Application	A specific app and all its keysets
Keyset	A single keyset
Secret key	Secret key of a specific keyset
Usage & Monitoring	Read usage metrics for accounts, apps, and keysets
OEM Customer	Partner Portal management

API key lifecycle:

• Maximum of 3 active API keys per Service Integration
• Configurable expiration up to 1 year
• Key rotation and revocation procedures
• Best practices for security and maintenance

Admin API updates

Type: Enhancement

We published the latest Admin API specification versions, ensuring the documentation reflects current API capabilities for programmatic management of PubNub applications and keysets.

Documentation bug fixes

Type: Enhancement

We addressed several documentation issues this month:

• Fixed Markdown rendering issues affecting some documentation pages
• Fixed invisible examples in REST API documentation
• Resolved OpenAPI specification validation issues