Skip to main content
Game Requests allow players to invite their friends to play a game or re-engage friends who haven’t played in a while. This feature is specifically designed for gaming applications.

Basic Usage

Sending a Game Request

import { GameRequestDialog } from 'react-native-fbsdk-next';

const gameRequestContent = {
  message: "Join me in this awesome game!",
};

async function sendGameRequest() {
  try {
    const canShow = await GameRequestDialog.canShow();
    
    if (canShow) {
      const result = await GameRequestDialog.show(gameRequestContent);
      
      if (result.isCancelled) {
        console.log("Game request cancelled");
      } else {
        console.log("Request ID:", result.requestId);
        console.log("Recipients:", result.to);
      }
    }
  } catch (error) {
    console.log("Error:", error);
  }
}

Request Types

Send Request

Send an object to friends (e.g., send a gift):
const gameRequestContent = {
  message: "I sent you a gift!",
  actionType: "send",
  objectId: "gift_12345",
  data: "extra_data_here",
};

GameRequestDialog.show(gameRequestContent);

Ask For Request

Ask friends for an object (e.g., request lives):
const gameRequestContent = {
  message: "Can you send me some extra lives?",
  actionType: "askfor",
  objectId: "lives_request",
  data: "lives_needed:5",
};

GameRequestDialog.show(gameRequestContent);

Turn Request

Notify friends it’s their turn in a game:
const gameRequestContent = {
  message: "It's your turn to play!",
  actionType: "turn",
  data: "game_id:abc123,match_id:xyz789",
};

GameRequestDialog.show(gameRequestContent);

Targeting Recipients

Specific Friends

Send requests to specific friends:
const gameRequestContent = {
  message: "Let's play together!",
  recipients: ["friend_user_id_1", "friend_user_id_2"],
};

GameRequestDialog.show(gameRequestContent);

Suggested Friends

Suggest specific friends in the dialog:
const gameRequestContent = {
  message: "Challenge your friends!",
  suggestions: ["suggested_user_id_1", "suggested_user_id_2"],
};

GameRequestDialog.show(gameRequestContent);
You cannot use both recipients and suggestions in the same request. Use recipients to send to specific users, or suggestions to pre-populate the friend selector.

Filtering Recipients

App Users Only

Show only friends who already use the app:
const gameRequestContent = {
  message: "Let's play another round!",
  filters: "app_users",
};

GameRequestDialog.show(gameRequestContent);

Non-App Users

Show only friends who don’t use the app (for invitations):
const gameRequestContent = {
  message: "Join me in this game!",
  filters: "app_non_users",
};

GameRequestDialog.show(gameRequestContent);
You cannot use filters together with suggestions. If you need to suggest specific friends, you cannot also apply user filters.

Custom Request Data

Adding Tracking Data

Include custom data for tracking (max 255 characters):
const gameRequestContent = {
  message: "Help me beat this level!",
  data: JSON.stringify({
    level: 42,
    campaign: "summer_2024",
    source: "level_failed_screen",
  }),
};

GameRequestDialog.show(gameRequestContent);

Custom Title

Set a custom title for the request dialog:
const gameRequestContent = {
  message: "Let's compete!",
  title: "Challenge Your Friends",
};

GameRequestDialog.show(gameRequestContent);

Complete Examples

import React from 'react';
import { View, Button, Alert } from 'react-native';
import { GameRequestDialog } from 'react-native-fbsdk-next';

export default function InviteFriends() {
  const inviteFriends = async () => {
    const content = {
      message: "Join me in this awesome game!",
      title: "Invite Friends to Play",
      filters: "app_non_users",
      data: JSON.stringify({
        source: "invite_button",
        campaign: "new_player_invite",
      }),
    };

    try {
      const canShow = await GameRequestDialog.canShow();
      
      if (!canShow) {
        Alert.alert("Error", "Cannot show game request dialog");
        return;
      }

      const result = await GameRequestDialog.show(content);
      
      if (!result.isCancelled) {
        Alert.alert(
          "Success",
          `Invites sent to ${result.to.length} friend(s)`
        );
        console.log("Request ID:", result.requestId);
      }
    } catch (error) {
      Alert.alert("Error", error.message);
    }
  };

  return (
    <View>
      <Button title="Invite Friends" onPress={inviteFriends} />
    </View>
  );
}

TypeScript Support

GameRequestContent Type

type GameRequestContent = {
  message: string;                    // Required
  actionType?: 'send' | 'askfor' | 'turn';
  data?: string;                      // Max 255 characters
  filters?: 'app_users' | 'app_non_users';
  objectId?: string;                  // Required for 'send' and 'askfor'
  recipients?: Array<string>;
  suggestions?: Array<string>;
  title?: string;
};

type GameRequestDialogResult = {
  isCancelled: boolean;
  requestId: string;
  to: Array<string>;
};

API Reference

GameRequestDialog Methods

MethodDescription
canShow()Check if the dialog can be shown
show(content)Show the game request dialog

GameRequestContent Properties

PropertyTypeRequiredDescription
messagestringYesPlain-text message for the request
actionTypestringNoType of request: ‘send’, ‘askfor’, or ‘turn’
objectIdstringConditionalRequired for ‘send’ and ‘askfor’ action types
datastringNoCustom tracking data (max 255 chars)
filtersstringNoFilter friends: ‘app_users’ or ‘app_non_users’
recipientsstring[]NoSpecific user IDs to send to
suggestionsstring[]NoUser IDs to suggest in dialog
titlestringNoCustom dialog title

GameRequestDialogResult Properties

PropertyTypeDescription
isCancelledbooleanWhether the request was cancelled
requestIdstringID of the created request
tostring[]Array of recipient user IDs

Best Practices

  1. Always check canShow() before attempting to show the dialog
  2. Use actionType appropriately - Choose the right type for your use case
  3. Include meaningful data - Track request sources and contexts
  4. Keep messages clear - Use concise, action-oriented language
  5. Don’t spam - Limit how frequently users can send requests
  6. Target wisely - Use filters to show relevant friends
  7. Handle cancellations - Users may cancel the dialog, handle gracefully

Limitations

  • Cannot use filters with suggestions
  • Cannot use recipients with suggestions
  • data field is limited to 255 characters
  • objectId is required when actionType is ‘send’ or ‘askfor’
  • Game requests are designed for gaming apps only

Build docs developers (and LLMs) love