Invites

Invites help players invite friends to play with them. Invites are sent through Messenger and follow-up game play updates can be as well. There are three primary APIs supporting invites in Instant Games. You can use inviteAsync on its own, or used chooseAsync with updateAsync.

Not only do they unlock invites, but they can also be leveraged for Rewarded Referrals or Gifting.

The Invite feature is available in the Instant Games SDK.

Feature Flow

inviteAsync

The following table shows the flow of the inviteAsync version of the Invites feature.

Timeline	Details
Step 1: Encourage players to invite their friends	At appropriate times in your game, display a button that prompts users to invite their friends to play.
Step 2: Open the Play With Friends dialog	The player sees a list of friends and threads (including group threads). They can send as many invites as they like before closing the dialog. Call `inviteAsync` and pass in a base64 image, text, and an optional data parameter.
Step 3: Friends receive invites	Their friends receive the invites in Messenger. The message includes a link to the game that includes the blob of data (accessible through `FBInstant.getEntryPointData()`).
Step 4: Friends open game session	When the friend clicks the invite, the game opens in a context with the inviter.

chooseAsync

The following table shows the flow of the chooseAsync version of the Invites feature.

Timeline	Details
Step 1: Encourage players to invite their friends	At appropriate times in your game, display a button that prompts users to invite their friends to play.
Step 2: Open the Play With Friends dialog	The player sees a list of friends and threads. They can invite one to play with. Call `chooseAsync` and pass in the appropriate data.
Step 3: Send the invite	The player then plays a round of the game and when it ends, a message is sent to the person they invited with the result. Call `updateAsync` when the player has played their round.
Step 4: Friend sees invite	The friend they started a game with will see a message and a Call to Action to play.

Why You Should Integrate This Feature

Invites can improve both retention and new player acquisition. One of our partners increased their rewarded referrals by 30% with inviteAsync.

Getting Started

In Instant Games there are two types of invites to help players to invite friends to play, and the one you use depends on what you’re trying to enable.

In-game, offer your players an opportunity to “Invite”, “Find Friends” or “Play With Friends” and then call the invite API that best suits your use case to kick-off the invite flow.

inviteAsync: Allows a player to immediately send invitations to multiple friends but leaves the inviter in the same context they’re already playing in.
chooseAsync: Limits the player to choosing a single friend to play with. They’re switched into a context with the person they invite, they play their round and then updateAsync is used to send the message to invite the friend to play.

Best Practices

The optional data parameter (payload) in inviteAsync gives you flexibility in your game design. It can be used to send gifts, give rewards to players when someone joins the game from their invite, customize the opening stage of the game, track the analytics of different text and image combinations, and much more.

The context is also added to the invite link so that when the game opens, the person can play in a context with the friend who invited them. If the player sends an invite to a group thread, everyone in the group thread would be able to play in that context.

Because inviteAsync doesn’t change the player’s context, it will resolve the promise if the user exits out of the dialog without issue and will reject the promise if an error is thrown.

By sending identifiers in the payload, you can tailor the experience of the inviter and invitee in the following ways:

The payload could include an identifier for the player who invited the new user, thus allowing the game to reward that player once the new user plays the game.
Passing an identifier could be used to send a gift to the user who opens the invite.
The payload can be used to start the game at a certain point (for example, a certain area on a map, a particular level) based on what is sent through the data param.
The developer could display an accomplishment that the inviting player had achieved when the new player follows the invite. The game could open up with a visual of the inviting player's game board.

Analysis

Gaming Insights in Facebook Business Suite does not yet support reporting metrics for inviteAsync.

By passing an identifier in the data parameter, developers can track how many plays they get from invites. For example, the developer might send the following data param: {playFromInvite: 'true'}. When the friend plays the game from the invite, the developer could call FBInstant.getEntryPointData() to load the data sent along with the link. When they see playFromInvite in the data, they would know that the play originated from an invite sent through inviteAsync.

Example Player Journeys

Reward the inviter when an invitee joins the game

Grow the game organically by offering rewards to the inviter for each new player joining the game through the invite.

Timeline	Details
Step 1: Player A invites a friend to play with them	Display the `inviteAsync` dialog by making the following call. FBInstant.inviteAsync({ image: base64Picture, text: ‘Please help me defeat these goblins!’, data: {invitedBy: ‘appScopedPlayerID’} });
Step 2: Player B opens the invite	Player B (new player) clicks on the invite and opens the game session.
Step 3: Player B opens the game session	Player B accepts the Terms of Service and starts playing the game in a context with Player A.
Step 4: Game sends a reward to Player A	The game fetches the data blob from the invite and rewards the inviter.
Step 5: Player A receives the reward	Player A gets a Bot message indicating that they have received a reward because Player B joined the game. Send custom update to Player B with payload, which can contain reward. FBInstant.updateAsync(payload)

Reward the invitee

Reward players for joining or returning to the game by giving them a gift when they enter the game through an invite.

Timeline Details

Timeline	Details
Step 1: Player A sends a gift to Player B	Player A (current player) sends a gift to a friend. Display the inviteAsync dialog by making the following call. FBInstant.inviteAsync({ image: base64Picture, text: ‘I’ve sent you a gift! Open it!’, data: {gift:’giftID’} });
Step 2: Player B opens the game session	Player B (new player) clicks on the invite and opens the game session.
Step 3: Game rewards Player B	The game fetches the payload from the invite and rewards Player B. On player open game fetch gift ID from `FBInstant.getEntrypointData()`.

Step 1: Player A sends a gift to Player B

Player A (current player) sends a gift to a friend.

Display the inviteAsync dialog by making the following call.

FBInstant.inviteAsync({
  image: base64Picture,
  text: ‘I’ve sent you a gift! Open it!’,
  data: {gift:’giftID’}
});

Step 2: Player B opens the game session

Player B (new player) clicks on the invite and opens the game session.

Step 3: Game rewards Player B

The game fetches the payload from the invite and rewards Player B.

On player open game fetch gift ID from FBInstant.getEntrypointData().

Display a specific accomplishment or game area when the invite Is opened

Allow players to share an accomplishment that they’re proud of.

Timeline Details

Timeline	Details
Step 1: Player A invites Player B to play	Player A (current player) invites a friend to play with them. Display the invite dialog by making the following call. FBInstant.inviteAsync({ image: base64Picture, text: ‘I added a room to my castle! Check it out!’, data: {roomID:’roomID’} });
Step 2: Player B opens the game session	Player B (new player) clicks on the invite and opens the game session.
Step 3: Game displays info to Player B	The game fetches the data blob from the invite and displays the accomplishment or game area to Player B. On player open game fetch the room ID from `FBInstant.getEntrypointData()` and display Player A’s new room to Player B.

Step 1: Player A invites Player B to play

Player A (current player) invites a friend to play with them.

Display the invite dialog by making the following call.

FBInstant.inviteAsync({
  image: base64Picture,
  text: ‘I added a room to my castle! Check it out!’,
  data: {roomID:’roomID’}
});

Step 2: Player B opens the game session

Player B (new player) clicks on the invite and opens the game session.

Step 3: Game displays info to Player B

The game fetches the data blob from the invite and displays the accomplishment or game area to Player B.

On player open game fetch the room ID from FBInstant.getEntrypointData() and display Player A’s new room to Player B.

Other scenarios that could utilize this feature

Player invites a friend to play a real time game with them
Player invites a friend to play a turn based game with them
Player invites all of their friends within a group thread to play with them
Player invites a friend who then becomes their in-game friend when they join
Player invites a friend and is rewarded once their friend joins the game

Feature FAQ

What’s the difference between inviteAsync and chooseAsync + updateAsync (a.k.a. Custom Update)?

The updateAsync API only allows sending a single message at a time, and it has to be with a person the user is in a context with. That can be very limiting if the developer is hoping to send out many messages. The inviteAsync API allows players to send multiple invites to their friends without switching contexts, allowing for a smoother invite flow.

Additionally, because updateAsync only sends to the users in the current context, it can only send messages to users that the current player has an existing context with. The inviteAsync API allows sending invites to friends who are not in an existing context with the player.

Some games currently use a combination of chooseAsync and updateAsync to send out messages. Those games would be ideal candidates for using inviteAsync either instead of the existing flow or in addition to it.

What’s the difference between inviteAsync and chooseAsync (a.k.a. context choose)?

The inviteAsync API sends messages, and can be used to send as many messages as the player wants, allowing the user to send many invites very quickly. Also, inviteAsync can send invites to group threads that have users within the European Union (EU), which is not possible with chooseAsync.

The chooseAsync API allows players to switch into a single context. The developer can then send a custom update using updateAsync if they want, but it would only be to a single context, and the messaging itself is not part of the chooseAsync functionality.

Many games use contexts for more than just messaging, and chooseAsync is an easy way to switch into a new or existing context. For games that use chooseAsync and updateAsync solely to send messages, though, inviteAsync could be a much more effective replacement.