MultiConnectMultiConnectDocs Website home
MultiConnectSDK › SDK Apps

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:

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.

  1. 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).
  2. 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

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();
    }
}