Social Features

With Instant Games there are many ways to enable social interaction between your players. Below you can find detailed information about each one of these features.

  1. Custom Updates
  2. Custom Sharing
  3. Connected Players
  4. Changing Contexts
  5. Game Bots

Custom Updates

With Instant Games, you have the ability to send a custom message into the Messenger conversation where the game is being played. This message can be fully customized with an image, description, and even a "call to action" button with custom text.

By default, only the last update message will be expanded for a given game in a conversation. Previous messages, however, can be expanded by anyone in the conversation.

An update message can also pass along a custom data blob of up to 1kb. This data will be available to any player who opens the game from that message via FBInstant.getEntryPointData().

There's a limit of one consecutive message per context per session. Once your game posts an update of any type into the context, it'll be blocked from posting more updates until either the context changes or another player posts an update to the context. It should contain the most important information from that gameplay session. For example, in a turn-based game, it should indicate that a move is over and it's now the next player's turn. But usage is not limited to turn-based games — because it's fully customizable, the message is flexible enough to indicate meaningful updates about any in-game action.

// This will post a custom update. If the game is played in a messenger
// chat thread, this will post a message into the thread with the specified
// image and text message. And when people launch the game from this
// message, those game sessions will be able to access the specified blob
// of data through FBInstant.getEntryPointData().
  action: 'CUSTOM',
  cta: 'Play',
  image: base64Picture,
  text: {
    default: 'Edgar just played BASH for 9 points!',
    localizations: {
      en_US: 'Edgar just played BASH for 9 points!',
      pt_BR: 'Edgar jogou BASH por 9 pontos!',
  template: 'WORD_PLAYED',
  data: { myReplayData: '...' },
  strategy: 'IMMEDIATE',
  notification: 'NO_PUSH',
}).then(function() {
  console.log('Message was sent successfully');

Custom Sharing

Enable players to share your game's meaningful moments. The SDK call works similar to the Custom Updates call above, but instead of updating content in the current conversation, the method FBInstant.shareAsync() prompts the player to share the moment elsewhere.

Players can share it in their News Feed or in Messenger conversations. If they share it in their News Feed, they can include a custom message.

Both the News Feed story and Messenger message will contain an image, text, and a button, all set when calling the API. Using the button launches the game. From that entry point, the developer has access to FBInstant.getEntrypointData(), which returns the data object passed via the data: argument in FBInstant.shareAsync().

  intent: 'REQUEST',
  image: myBase64Picture,
  text: 'Hey I\'m stuck on this puzzle! Can you help me?',
  data: { myReplayData: '...' },

Connected Players

The FBInstant.player.getConnectedPlayersAsync() method retrieves a list of users that are connected to the current player on Messenger, and who have granted permission to the game.

Note that the method will not provide any differentiation between players who have been playing in the same context or not. You can fetch information specific to that context from FBInstant.context.getPlayersAsync()

Fetch player's friends

  .then(function(players) {

Fetch context players

  .then(function(players) {

Changing Contexts

Instant Games can be played in many different contexts, such as Messenger conversations or News Feed stories. With the SDK calls below, you can switch contexts from any session, regardless of its entry point. This means you can allow your players to switch to other conversations without requiring them to quit and re-open the game.

In order to change to a new context, we offer three different methods:

  • FBInstant.context.chooseAsync() opens a native dialog that allows the player to select which conversation they want to change to.
  • FBInstant.context.switchAsync(contextId) allows the developer to send the player to a pre-defined context, for instance, to continue a match that has previously started in a different conversation.
  • FBInstant.context.createAsync(playerId) attempts to create a context with the specified player. This can be used, for example, to start a match between a player and a suggested friend.

Game Bots

Game Bots can help you create re-engagement experiences. They are conversational bots, built on top of the Messenger Platform, that can interact with your players and invite them to return to your game in meaningful moments. You can use Game Bots to offer side quests, story modes, player progression updates, nudges, and more.

Whenever a player closes your game, your Game Bot's server will receive a webhook notification that will allow it to send a message directly to the player. Your bot can also offer a "Play Game" button that can be customized for context choosing.

Note: We offer multiple entry points to opt-in and out of bot conversations so you should never assume that all players are connected to your bot, nor should your gameplay experience depend completely on the bot messages. These should be complimentary to the gameplay but not necessary.