Game Updates

With Instant Games, you can send a custom message in a Messenger conversation between the people who are playing.

Custom Updates

This message can be fully customized with an image, description, and even a Call to Action (CTA) button with custom text. By default, only the last update message will be expanded for a given game in a conversation. Earlier messages 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 will be blocked from posting more updates until either:

  1. The context changes; or
  2. Another player posts an update to the context.

Note: 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.


The update should contain the most important information from that gameplay session and inform the player of the game's context. For example:

  • [FRIEND] just played [GAME]. It's your turn!
  • [FRIEND] beat the weekly high score in [GAME]. See if you can do better!

Call to Action

The Call to Action button is used to guide the player to their next step. Use a simple verb that clearly conveys what the player will do when they click the button. For example:

  • Play
  • Join
  • Challenge
  • Help

Avoid terms like “Go”; “Yes”; “Accept” or any term that does not explain what the CTA will do when it is clicked.


We only support base64 encoded images at the moment. If you try to put a link to an image or anything else than a base64 encoded image, the request will be invalid.

// 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. 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');

Best Practices for Game Updates

Here are a few tips for creating engaging, quality custom updates messages:

Write in active voice: use active voice to make your text sound lively, inviting and exciting. Examples:

[FRIEND] is challenging you to a [GAME] match.

You were challenged to a match.

Put the most important information first: make it easy to find key information at a glance. Make the value of the message clear to the reader. Examples:

Try [GAME] now!

Who doesn't like games? You should play [GAME] now!

Keep it short: the shorter the message, the more likely it is to be read. Examples:

Join [NAME] for a round of [GAME]!

If you're looking for adventure, action, and excitement, you should join your [FRIEND] and play a thrilling match of [GAME].

Stick to one idea: don't overwhelm the reader with information. Try simple, single idea prompts one at a time, and see which one performs best. Examples:

Rise to the top of the leaderboard in [GAME]!

Want to improve your strategy in [GAME] and rise to the top of the leaderboard?

Don't speak for the player or their opponent: don't make assumptions or speak for your players; no one likes having words put in their mouth. Examples:

[NAME] is inviting you to play [GAME]. Accept the challenge!

Come play [GAME] with me! I bet I will win!