> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Receiving invites

> Add multiplayer game invite handling to your XBOX services title by registering the multiplayer protocol and XGameActivation invite event callbacks.

Use this topic to add game invites to your XBOX services title. To receive multiplayer invites, your game registers for the multiplayer protocol and game invite callbacks. Your game receives invites for the local user, and then joins that user to the multiplayer session.

## Prerequisite

To receive game invite notifications on a Windows PC, install the XBOX Game Bar. The XBOX Game Bar app is installed by default on Windows 10, OS version 1903 or later. Select **Windows Key**+**G** to launch the XBOX Game Bar app to verify that it's installed correctly.

<Note>
  If XBOX Game Bar isn't installed on your Windows PC, you can install it from the [Microsoft Store](https://www.microsoft.com/store/productId/9NZKPSTSNW4P).
</Note>

## Registering for multiplayer protocol

Registering for multiplayer protocol tells the system how to launch your game when the user accepts a multiplayer game invite. To register the multiplayer protocol, you need to add a `MultiplayerProtocol` element to your [MicrosoftGame.config](/build/core-features/common/game-config/MicrosoftGameConfig-toc) file as shown in the following code.

```xml theme={null}
    <MultiplayerProtocol>true</MultiplayerProtocol>
```

If you have multiple executables in the package, you can specify which executable handles the multiplayer protocol by using the `Executable` attribute as shown in the following code.

```xml theme={null}
    <MultiplayerProtocol Executable="MyExecutableForMultiplayer.exe">true</MultiplayerProtocol>
```

## Registering for multiplayer game invite callbacks

<Info>
  The `XGameInviteRegisterForEvent` and `XGameInviteUnregisterForEvent` APIs are now deprecated. Use [XGameActivationRegisterForEvent](/reference/system/xgameactivation/functions/xgameactivationregisterforevent) and [XGameActivationUnregisterForEvent](/reference/system/xgameactivation/functions/xgameactivationunregisterforevent) instead. For migration guidance, see [XGameActivation](/reference/system/xgameactivation/xgameactivation_members#remarks).
</Info>

To receive multiplayer game invite callbacks, you must register for activation callbacks by using the [XGameActivationRegisterForEvent](/reference/system/xgameactivation/functions/xgameactivationregisterforevent) API as shown in the following code.

For more information about registering and unregistering activation callbacks, see [XGameActivationRegisterForEvent](/reference/system/xgameactivation/functions/xgameactivationregisterforevent) and [XGameActivationUnregisterForEvent](/reference/system/xgameactivation/functions/xgameactivationunregisterforevent).

### Flat C

```cpp theme={null}
#include <XTaskQueue.h>
#include <XGameActivation.h>  
  
XTaskQueueHandle g_taskQueue;  
XTaskQueueRegistrationToken g_activationToken;  
  
void CALLBACK OnActivation(void* context, const XGameActivationInfo* activationInfo)  
{  
    if (activationInfo->type == XGameActivationType::AcceptedGameInvite)
    {
        if (activationInfo->inviteUri != nullptr)
        {
            std::string inviteString(activationInfo->inviteUri);
            auto pos = inviteString.find("handle=");
            auto handleId = inviteString.substr(pos + 7, 36);
            // Now call XblMultiplayerManagerJoinLobby
        }
    }
}  
  
void InitializeGame()  
{  
    XGameActivationRegisterForEvent(g_taskQueue, nullptr, OnActivation, &g_activationToken);  
}  
  
void ShutdownGame()  
{  
    XGameActivationUnregisterForEvent(g_activationToken, true);  
}  
```

To properly handle the "accepted invite from a suspended state" scenario, the title must store the `inviteUri` that's passed into the `OnActivation()` handler method in the sample code above from the [XGameActivationRegisterForEvent](/reference/system/xgameactivation/functions/xgameactivationregisterforevent) callback. Then the title must wait for the `RegisterAppStateChangeNotification` which notifies when the game has fully resumed before the title proceeds to operate on the session by using the details that are provided in the `inviteUri`.

For more information about `RegisterAppStateChangeNotification`, see [XBOX Game Life Cycle (NDA topic)](/build/console-features/console-workflows/xbox-game-life-cycle).

## Parsing inviteUri from XGameActivationCallback

When your game receives the [XGameActivationCallback](/reference/system/xgameactivation/functions/xgameactivationcallback) event with an activation type of `AcceptedGameInvite`, you can access the `inviteUri` string from the [XGameActivationInfo](/reference/system/xgameactivation/structs/xgameactivationinfo) structure. The `inviteUri` is in one of the following formats.

### For accepting a game invite

When the user accepts a game invite, the game receives the game invite callback with an `inviteUri` as shown in the following code.

```cpp theme={null}
    "ms-xbl-multiplayer://inviteHandleAccept?handle=%s&invitedXuid=%s&senderXuid=%s&context=%s"
    
    // for example:
    // "ms-xbl-multiplayer://inviteHandleAccept?handle=00000000-0000-1234-5678-1234567890ab&invitedXuid=1234567890123456&senderXuid=6543210987654321&context="
```

The URI always starts with "ms-xbl-multiplayer//", and then the following handles.

* `inviteHandleAccept` indicates that the callback was initiated because the user accepted a game invite.
* `handle` is the invite handle you use to join the multiplayer session.
* `invitedXuid` is the ID of the XBOX services user who's invited to the multiplayer session.
* `senderXuid` is the ID of the XBOX services user who sent the game invite.
* `context` is the additional (optional) context the sender might have included.

### For joining a game session in progress

When the user attempts to join a multiplayer session, the game would receive an invite callback with an `inviteUri` as shown in the following code.

```cpp theme={null}
    "ms-xbl-multiplayer://activityHandleJoin?&handle=%s&joinerXuid=%s&joineeXuid=%s"
```

The URI always starts with "ms-xbl-multiplayer//", and then the following handles.

* `activityHandleJoin` indicates that the callback was initiated because the user accepted a game invite.
* `handle` is the activity handle you use to join the multiplayer session.
* `joinerXuid` is the ID of the XBOX services user who's attempting to join the multiplayer session.
* `joineeXuid` is the ID of the XBOX services user who's currently in the multiplayer session.

## Joining a multiplayer game session with handleId

### Using Multiplayer Manager

If you're using Multiplayer Manager, you can join the user to the multiplayer session by using the [XblMultiplayerManagerJoinLobby](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby) API and passing in the `handleId` that's extracted from the `inviteUri`. You can also use the `xblUserHandle` for the `invitedXuid` as shown in the following code.

#### Flat C

```cpp theme={null}
HRESULT hr = XblMultiplayerManagerJoinLobby(handleId, xblUserHandle);
```

### Using Multiplayer API directly

If you're using Multiplayer API, use the following steps to configure multiplayer sessions and invites for your title.

1. Fetch the multiplayer session document by using the [XblMultiplayerGetSessionByHandleAsync](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayergetsessionbyhandleasync) API and pass it in the `handleId`.
2. Join the local user to the multiplayer session document by using the [XblMultiplayerSessionJoin](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionjoin) API.
3. Write the multiplayer session document to the service to commit this change by using the [XblMultiplayerWriteSessionByHandleAsync](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionbyhandleasync) API.

## Reference API documentation

* [Xgameactivation (API contents)](/reference/system/xgameactivation/xgameactivation_members)
  * Functions
    * [XGameActivationRegisterForEvent](/reference/system/xgameactivation/functions/xgameactivationregisterforevent)
    * [XGameActivationUnregisterForEvent](/reference/system/xgameactivation/functions/xgameactivationunregisterforevent)
    * [XGameActivationCallback](/reference/system/xgameactivation/functions/xgameactivationcallback)
  * Structures
    * [XGameActivationInfo](/reference/system/xgameactivation/structs/xgameactivationinfo)
* [multiplayer\_manager\_c (API contents)](/reference/live/xsapi-c/multiplayer_manager_c/multiplayer_manager_c_members)
  * Functions
    * [XblMultiplayerManagerJoinLobby](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby)
    * [XblMultiplayerGetSessionByHandleAsync](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayergetsessionbyhandleasync)
    * [XblMultiplayerSessionJoin](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionjoin)
    * [XblMultiplayerWriteSessionByHandleAsync](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionbyhandleasync)

## See also

[XGameActivation API](/reference/system/xgameactivation/xgameactivation_members) [Handling protocol activation to start a game, using Multiplayer Manager](/services/xbox-services/multiplayer/mpm/how-to/live-handle-protocol-activation)


## Related topics

- [Example code for Multiplayer Activity](/services/xbox-services/multiplayer/mpa/how-to/live-mpa-client-how-to.md)
- [Invites](/services/xbox-services/multiplayer/invites/index.md)
- [Lobby invites](/services/playfab/multiplayer/lobby/lobby-invites.md)
- [Invites example code](/services/xbox-services/multiplayer/invites/how-to/live-invites-howto-nav.md)
- [XblMultiplayerManagerLobbySessionInviteUsers](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessioninviteusers.md)