@pubnub/mcp/resources/how_to_understand_channels.md

PubNub Model Context Protocol MCP Server for Cursor and Claude

# Understanding PubNub Channels

Channels are the fundamental concept for routing messages in the PubNub Data Stream Network. They act as named pathways or conduits through which publishers send messages and subscribers receive them.

## What is a Channel?

*   **Message Pathway:** A channel is essentially a label or a name. When a message is published, it's sent *to* a specific channel name. Clients that are *subscribed* to that same channel name will receive the message.
*   **Dynamic and Lightweight:** Channels are created dynamically. They don't need to be pre-registered or configured before use.
    *   A channel comes into existence simply by publishing a message to its name or by a client subscribing to its name.
    *   If no one is publishing or subscribed to a channel, it effectively doesn't consume active resources (though its name might be known to features like App Context if metadata was set for it).
*   **No Intrinsic Properties:** Channels themselves don't have predefined properties that you need to set up (like capacity or type, in the way some other messaging systems might). Their behavior is defined by how your application uses them and by the PubNub features you enable (e.g., Message Persistence, Access Manager).

## Key Characteristics of PubNub Channels

*   **Naming:**
    *   **UTF-8 Compatible:** Channel names support UTF-8 characters.
    *   **Length:** Up to 92 characters.
    *   **Case-Sensitive:** `MyChannel` and `mychannel` are different channels.
    *   **Invalid Characters:** Avoid `,`, `:`, `*`, `/`, `\`, spaces, and non-printable ASCII. The period `.` is reserved for wildcard features. (Refer to "How to Define Valid Channel Names" for details).
*   **Unlimited Channels:** Your application can use as many channels as it needs. There is no additional PubNub charge based on the *number* of channels you use. Your billing is typically based on transaction volume and feature usage.
*   **Decoupling:** Publishers and subscribers are decoupled.
    *   A publisher can send messages to a channel even if no clients are currently subscribed to it.
    *   A client can subscribe to a channel even if no messages are currently being published to it.
*   **Message Capacity (Short-Term Cache):**
    *   While a channel can logically handle an unlimited stream of messages over time, PubNub servers maintain a short-term in-memory cache (or buffer) for each channel. This typically holds the last **100 messages** or messages published within a brief window (e.g., up to ~20 minutes, but messages are pushed out if the publish rate is high).
    *   This cache is used for quick "catch-up" for clients that briefly disconnect and reconnect.
    *   For long-term storage, you need to enable the Message Persistence add-on.
*   **Fan-Out (Broadcast):** One message published to a channel can be received by many (potentially millions of) subscribers to that channel simultaneously.
*   **Fan-In:** Many different publishers can send messages to the same channel.

## How Channels Are Used

The way you define and use channels is entirely up to your application's requirements. 

*   **Global Broadcast:** A single channel like `global_announcements` where an administrator publishes messages to all users.
*   **Group Chat:** A channel for each chat room, e.g., `room_project_alpha`, `room_social_lounge`.
*   **Private Chat (1-to-1):** A channel dedicated to two users, often named using a convention involving their `userId`s, e.g., `chat_userA_userB` (ensure a consistent naming order).
*   **User-Specific Updates:** A channel for updates relevant only to a specific user, e.g., `user_notifications:<userID>`.
*   **Device Telemetry:** A channel for a specific IoT device to publish its sensor data, e.g., `device_sensor_data:<deviceID>`.
*   **Hierarchical Topics:** Using a naming convention with delimiters (like periods, carefully, due to wildcard implications) to represent topics and subtopics, e.g., `sports.football.scores`, `iot.floor1.room101.temp`.

## Managing Access to Channels

By default, any client with your Subscribe Key can subscribe to any channel, and any client with your Publish Key can publish to any channel. To control access:
*   **PubNub Access Manager (PAM):** This add-on allows you to grant specific read and/or write permissions to authenticated users (via auth-keys) for specific channels or channel patterns. This is crucial for securing your channels.

Channels are a flexible and powerful core component of PubNub, providing the addressing mechanism for all real-time communication.