12. Inbox
What the inbox holds
Each player has an inbox of notices (a message) and gifts (a message with currencies or items attached). A gift can be claimed once, however many times the claim is sent.
Send from the dashboard
On the app page, open Inbox and choose New message. Set:
- the Title, the text, and an image URL if you want one;
- The gift (leave it empty for a notice);
- who gets it: Player ids (empty = everyone), Platforms (none = all), From app version;
- when it Starts, UTC (empty = now) and Days in the inbox;
- whether to Also send it as a push notification (section 15).
To take a message back, choose Remove from every inbox.
You can send the same messages and gifts from a terminal or an AI agent with the MultiConnect CLI: multiconnect app inbox send.
Send from your server
For example, a leaderboard reward to last week's top 10.
Script 12.1: Server: gift last week's top 10
using System.Collections.Generic;
using System.Threading.Tasks;
using MultiConnect.App;
public static class WeeklyRewards
{
public static async Task GiftTopTen()
{
var lastWeek = await McAppServer.GetTopAsync("weekly_wins", limit: 10, periodsAgo: 1);
if (!lastWeek.Ok || lastWeek.Value == null) return;
var winners = new List<string>();
foreach (var entry in lastWeek.Value.entries) winners.Add(entry.playerId);
var gift = new McGrants();
gift.currencies["coins"] = 1000;
await McAppServer.SendMessageAsync(winners, "Top 10 last week!", "Here are 1,000 coins.", gift, days: 7, push: true);
}
}
Show the inbox in the game
Script 12.2: Client: list messages and claim gifts
using MultiConnect.App;
using UnityEngine;
public class InboxScreen : MonoBehaviour
{
private async void OnEnable()
{
var inbox = await McAppInbox.GetAsync();
if (!inbox.Ok || inbox.Value == null) return;
Debug.Log($"{inbox.Value.unread} unread, {inbox.Value.unclaimedGifts} gifts to claim");
foreach (var message in inbox.Value.messages)
{
Debug.Log($"[{message.type}] {message.title}: {message.body}");
if (!message.isRead) await McAppInbox.ReadAsync(message.messageId);
if (message.type == "gift" && !message.isClaimed)
{
var claim = await McAppInbox.ClaimAsync(message.messageId);
Debug.Log(claim.Ok ? "Gift claimed." : claim.Message);
}
}
}
}
McAppInbox.DeleteAsync(messageId) removes a message from the player's inbox.
If your game keeps its own inbox
Some games already have an inbox and a coin wallet in their own game API. You can keep them and still send messages and gifts from the Inbox page, from the MultiConnect CLI (multiconnect app inbox send), or from your game server: MultiConnectCloud hands each one to your game API, which stores it and pays the gift from its own wallet.
- Set up the webhook once: on Store products, open Your game API, enter your API's URL (https), choose Make a secret and store the secret in your API's settings (section 13).
- Under Where inbox messages and gifts go, choose Your game API's own inbox, then Save.
From then on, every message is POSTed to your URL as an inbox.message event:
| Field | What it holds |
|---|---|
messageId |
The message's id. Store it: pay a gift once per messageId and player, and use it to withdraw |
type |
notice or gift |
title, body, imageUrl |
The message |
grants |
For a gift: currencies, items and timedItems, using your game's own names (e.g. coins). They don't need to exist under Economy |
startsAt, endsAt |
When it shows, in UTC (ISO 8601) |
audience |
players (only those in players) or everyone |
players |
Each player's MultiConnect playerId and gameId, your game's own id from custom sign-in (section 5). gameId is empty for a player who never signed in with it |
platforms, minAppVersion |
For everyone: only these platforms and versions (empty = all) |
sentBy |
dashboard, cli or server |
- Answer 2xx once you've stored it. Each send waits for your answer. Anything else, or no answer within 10 seconds, means the message is not sent, and whoever sent it sees why.
- Withdrawing a message on the Inbox page or with the CLI sends
inbox.withdrawnwith itsmessageId. Remove it from your players' inboxes; gifts already claimed stay claimed. - Reads and claims happen in your game, so the Inbox page shows "—" for them.
- Push still goes through MultiConnectCloud: choose Also send it as a push notification as usual.
- The game's own inbox screen keeps reading from your API.
McAppInboxisn't used for these messages.
Script 12.3: Game API: receive inbox.message and inbox.withdrawn (ASP.NET Core)
using System.IO;
using System.Text.Json;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using MultiConnect.App;
public static class MultiConnectInboxEvents
{
/// <summary>Handle these in the same endpoint as Script 13.4: one URL receives every event.</summary>
public static async Task<IResult> Receive(HttpRequest request)
{
var body = await new StreamReader(request.Body).ReadToEndAsync();
var secret = "the secret from the dashboard, from your API's settings";
if (!McAppServer.VerifyWebhook(body, request.Headers["X-MC-Timestamp"].ToString(), request.Headers["X-MC-Signature"].ToString(), secret))
return Results.Unauthorized();
using var json = JsonDocument.Parse(body);
var kind = json.RootElement.GetProperty("event").GetString();
var data = json.RootElement.GetProperty("data");
var messageId = data.GetProperty("messageId").GetString() ?? "";
if (kind == "inbox.message")
{
var isGift = data.GetProperty("type").GetString() == "gift";
var title = data.GetProperty("title").GetString() ?? "";
var everyone = data.GetProperty("audience").GetString() == "everyone";
long coins = 0;
if (isGift && data.GetProperty("grants").GetProperty("currencies").TryGetProperty("coins", out var c)) coins = c.GetInt64();
foreach (var player in data.GetProperty("players").EnumerateArray())
{
var gameId = player.GetProperty("gameId").GetString() ?? "";
// Insert into your own inbox table, keyed by messageId and player, so a repeat is ignored.
}
// For everyone: store one row your inbox query shows to all players.
}
else if (kind == "inbox.withdrawn")
{
// Delete or hide the rows with this messageId.
}
return Results.Ok();
}
}

