Share via

Sending invites

  • Article

Use this topic to configure user-to-user multiplayer game sessions on Xbox services.

Your game sends invites to other users to join your game session. There are two ways to send a game invite to other users. You can use the Title-Callable UI (TCUI) (System UI overlay), or you can use a title-implemented custom UI.

Using the Title-Callable UI (TCUI) (System UI overlay)

Calling the XGameUiShowSendGameInviteAsync API retrieves the standard System UI overlay for inviting friends. This displays a UI that the user can navigate to select friends or users from the Recent Players list to invite to the game. When the user selects Confirm, the invite is sent to the selected users.

Using a title-implemented custom UI

Your title can implement a custom UI for viewing online friends and inviting them to game sessions. Use the XblMultiplayerSendInvitesAsync API to send invites to a set of users that are defined by their XboxUserId (XUID) as shown in the following code. This is useful if you prefer to use your own in-game UI instead of the stock System UI.

Flat C

auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->queue = queue;
asyncBlock->context = nullptr;
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take ownership of the XAsyncBlock*
    size_t handlesCount = 1; // must be equal to invites that are requested
    XblMultiplayerInviteHandle handles[1] = {};
    HRESULT hr = XblMultiplayerSendInvitesResult(asyncBlock, handlesCount, handles);
};

uint64_t xuids[1] = {};
xuids[0] = targetXuid;
size_t xuidsCount = 1;

HRESULT hr = XblMultiplayerSendInvitesAsync(
    xblContextHandle,
    &sessionReference,
    xuids,
    xuidsCount,
    titleId,
    contextStringId,
    customActivationContext,
    asyncBlock.get());
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* since the callback will take ownership.
    // If the call fails, the std::unique_ptr will keep ownership and delete the XAsyncBlock*
    asyncBlock.release();
}

See also

XAsyncBlock
XblMultiplayerInviteHandle
XblMultiplayerSendInvitesAsync
XblMultiplayerSendInvitesResult
XGameInvite (API Reference)
Handling protocol activation to start a game, using Multiplayer Manager
Sending game invites using Multiplayer Manager