Messaging: a real inbox

Player-to-Player Events: the closest sibling service, and the comparison worth understanding before picking either one.

brainCloud's Messaging service gives players a persistent inbox: unread counts, message boxes, mark-as-read state, all retained until the recipient deletes the message explicitly. That's a different durability model than an Event, which is consumed once, or a Lobby Signal, which is never stored. bcchat's direct-message feature sends through this service, via sendSimpleMessage.

How it works

1. Sending is one call, addressed by a profile id list. sendSimpleMessage(profileIds, text, callback) posts a plain string message to one or more recipients, with no channel, lobby, or prior connection required.
2. The richer sendMessage variant takes a structured payload, conventionally with a text field, for anything beyond plain strings. bcchat only uses the simple form.
3. Reading is a separate, multi-step API surface. getMessageBoxes lists boxes, getMessageCounts returns total and unread counts per box, getMessagesPage fetches content, and markMessagesRead updates read state. None of these are called in bcchat's running code path.
4. Unlike Events, nothing here is auto-consumed. A message persists until deleteMessages removes it. There's no drain-the-queue behavior the way GetEvents effectively empties the event queue.

Code

sendDirectMessage(friend, message)
{
    this.bcWrapper.messaging.sendSimpleMessage([friend.id], message, result =>
    {
        if (result.status === 200) { /* ... */ }
        else { this.dieWithMessage("Failed to send message"); }
    });
}

// Fetch mailboxes
// this.fetchMailBoxes();     <-- never actually invoked

fetchMailBoxes()
{
    this.bcWrapper.messaging.getMessageCounts(result =>
    {
        if (result.status === 200) { /* never reached in practice */ }
        else { this.dieWithMessage("Failed to retrieve messageboxes: " + result.status_message); }
    });
}

Gotchas worth knowing up front

• Choose between Messaging and Events based on payload durability. A message sits in an inbox until explicitly deleted (deleteMessages), suited to "you have mail" patterns a player checks on their own time. An Event follows a drain-the-queue-at-login pattern (see Article 16), better suited to transient state like invites that stop mattering once handled.
• sendSimpleMessage takes a list of profile ids. A single call can address several specific players at once; it isn't limited to a 1:1 primitive.