Instant Games

Instant Games SDK v8.0: FBInstant.context

Updated: May 5, 2026
Copy for LLM
See Instant Games SDK v8.0 for the SDK overview, changelog, and root FBInstant reference.

FBInstant.context

getID()

A unique identifier for the current game context. This represents a specific context that the game is being played in (for example, a facebook post). The identifier will be null if game is being played in a solo context. This function should not be called until FBInstant.startGameAsync has resolved.
Returns:?string — A unique identifier for the current game context.
Example:
// This function should be called after FBInstant.initializeAsync()
// resolves.
var contextID = FBInstant.context.getID();

getType()

The type of the current game context. POST - A facebook post. THREAD - A chat thread. GROUP - A facebook group. SOLO - Default context, where the player is the only participant.
This function should not be called until FBInstant.startGameAsync has resolved.
Returns:('POST'|'THREAD'|'GROUP'|'SOLO') — Type of the current game context.
Example:
// This function should be called after FBInstant.initializeAsync()
// resolves.
var contextType = FBInstant.context.getType();

chooseAsync()

Opens a dialog that lets the player pick a context (friend or group) to play in. You can filter and constrain the options.
Parameters:
ParameterTypeDescription
options
Object(optional)
An object specifying filtering and size constraints.
options.filters
Array<ContextFilter>(optional)
Array of ContextFilter values to limit which contexts are shown.
options.maxSize
number(optional)
Maximum number of participants allowed.
options.minSize
number(optional)
Minimum number of participants required.
Returns:Promise<void> — A promise that resolves when the game has switched into the chosen context, or rejects otherwise.
Throws:
  • INVALID_PARAM
  • SAME_CONTEXT
  • NETWORK_FAILURE
  • USER_INPUT
  • PENDING_REQUEST
  • CLIENT_UNSUPPORTED_OPERATION
Example:
FBInstant.context
  .chooseAsync()
  .then(function() {
    console.log(FBInstant.context.getID());
  });
FBInstant.context
  .chooseAsync({
    filters: ['NEW_CONTEXT_ONLY'],
    minSize: 2,
    maxSize: 5,
  })
  .then(function() {
    console.log(FBInstant.context.getID());
  });

switchAsync()

Request a switch into a specific context. If the player does not have permission to enter that context, or if the player does not provide permission for the game to enter that context, this will reject. Otherwise, the promise will resolve when the game has switched into the specified context.
Parameters:
ParameterTypeDescription
id
string
ID of the desired context, or "SOLO" to switch to a solo context.
switchSilentlyIfSolo
boolean(optional)
If true, skip the confirmation dialog when switching to solo. Defaults to false.
Returns:Promise<void> — A promise that resolves when the game has switched into the specified context, or rejects otherwise.
Throws:
  • INVALID_PARAM
  • SAME_CONTEXT
  • NETWORK_FAILURE
  • USER_INPUT
  • PENDING_REQUEST
  • CLIENT_UNSUPPORTED_OPERATION
Example:
console.log(FBInstant.context.getID());
// 1122334455
FBInstant.context
  .switchAsync('1234567890')
  .then(function() {
    console.log(FBInstant.context.getID());
    // 1234567890
  });

createAsync()

Attempts to create a context between the current player and a specified player or a list of players. This API supports 3 use cases: 1) When the input is a single playerID, it attempts to create or switch into a context between a specified player and the current player 2) When the input is a list of connected playerIDs, it attempts to create a context containing all the players 3) When there’s no input, a friend picker will be loaded to ask the player to create a context with friends to play with
For each of these cases, the returned promise will reject if any of the players listed are not Connected Players of the current player, or if the player denies the request to enter the new context. Otherwise, the promise will resolve when the game has switched into the new context.
Parameters:
ParameterTypeDescription
suggestedPlayerIDs
string \| Array<String>(optional)
A list of game suggested playerIDs or a single suggested playerID or no input
Returns:Promise<void> — A promise that resolves when the game has switched into the new context, or rejects otherwise.
Throws:
  • INVALID_PARAM
  • SAME_CONTEXT
  • NETWORK_FAILURE
  • USER_INPUT
  • PENDING_REQUEST
  • CLIENT_UNSUPPORTED_OPERATION
Example:
console.log(FBInstant.context.getID());
// 1122334455
FBInstant.context
  .createAsync('12345678')
  .then(function() {
    console.log(FBInstant.context.getID());
    // 5544332211
  });
console.log(FBInstant.context.getID());
// 1122334455
FBInstant.context
  .createAsync(['12345678', '87654321'])
  .then(function() {
    console.log(FBInstant.context.getID());
    // 55443322112232
  });
console.log(FBInstant.context.getID());
// 1122334455
FBInstant.context
  .createAsync()
  .then(function() {
    console.log(FBInstant.context.getID());
    // 55443322112232
  });

getPlayersAsync()

Gets an array of ContextPlayer objects containing information about active players in the current context (people who played the game in the current context in the last 90 days). This may include the current player.
Returns:Promise<Array<ContextPlayer>> — A promise that resolves with a list of ContextPlayer objects. NOTE: This function should not be called until FBInstant.initializeAsync() has resolved.
Throws:
  • NETWORK_FAILURE
  • CLIENT_UNSUPPORTED_OPERATION
  • INVALID_OPERATION
Example:
var contextPlayers = FBInstant.context.getPlayersAsync()
  .then(function(players) {
    console.log(players.map(function(player) {
      return {
        id: player.getID(),
      }
    }));
  });
// [{id: '123456789'}, {id: '987654321'}]

Types

ContextFilter

A filter that may be applied to a Context Choose operation ‘NEW_CONTEXT_ONLY’ - Prefer to only surface contexts the game has not been played in before. ‘INCLUDE_EXISTING_CHALLENGES’ - Include the “Existing Challenges” section, which surfaces actively played-in contexts that the player is a part of. ‘NEW_PLAYERS_ONLY’ - In sections containing individuals, prefer people who have not played the game.