Skip to main content

Discord Social SDK

Version Requirements

Minimum compatible OS: Minimum version supported by the INTLDiscord plugin

  • Android 5
  • iOS 11
  • Windows 10

Minimum supported OS: Minimum version that supports Discord related functions

  • Android 7
  • iOS 15.1
  • Windows 10

If the OS version is between the two, the INTLDiscord plugin can be integrated, but Discord social functions will be blocked.
info

This functions only provide access to data and does not provide any UI. The game needs to designed game UI according to Discord Social SDK Design Guidelines.

Discord Social features allow players to connect with Discord friends within the game to enhance the social experience of the game.

Discord Social and Login are independent of each other. You can log in to the Discord channel and bind Discord friend relationships, or you can log in to other channels and bind Discord friend relationships.

Step1：Configuring app on Discord Developer Portal​

info

If you have already integrated the Discord login feature, you can skip step 1.1.

1. Create a Discord app

  1. Register an account on the Discord official website and complete the account authentication (by email) according to the prompts.

  2. From the top right corner of the Applications page, click New Application. Image: Create an app

  3. In the app creation popup, enter the application name and click Create.

  4. From the General Information page, view the APPLICATION ID.
    Users must configure the app ID in the INTLConfig.ini file. Image: Get the ID

2. Apply for access permission for Discord SDK
  1. Go to Discord Developer Platform.
  2. Click your app on the Applications page.
  3. Click Getting Started in the left side navigation bar, enter your details, then click Submit to obtain the access permission. Image: Enter info Image: Complete info
caution

Caution: Before the official launch of your game, please inform the Discord team in advance to enable access permission on production environment.

3. Configure the app

  1. Go to Discord Developer Platform.

  2. Click your app on the Applications page.

  3. Click OAuth2 in the left side navigation bar.

  4. Toggle PUBLIC CLIENT on. Image: Toggle PUBLIC CLIENT

  5. Under Redirects, fill in the below redirect URLs, which are used to receive callbacks after Discord web authorization. Click Add Another to add more empty fields if required:

    • Android/iOS - discord-{YOUR_APP_ID}:/authorize/callback
      • Replace {YOUR_APP_ID} with your app ID.
    • PC - http://127.0.0.1/callback

    Image: Configure Redirect

    note

    If your game needs the function for users to click the invitation link in the Discord App and be redirected to the game App on mobile Platforms(like iOS and Android) , you will also need to configure a deeplink. Please add the DeepLink URL that redirects to your application in the Deep Link URL section on the General Information page. Image：deeplink on mobile Platforms

  6. Click Rich Presence in the left navigation bar to go to Rich Presence Art Assets page.

  7. Click Add Image(s) button to configure the graphic resources of your application. Image：configure graphic resources

Step2：Callbacks​

Developers can register the following callbacks as needed to receive notifications for relevant events.

DiscordBaseResultObserver​

// add the callback
INTLAPI.AddDiscordBaseResultObserver(OnDiscordBaseResult);

// remove the callback
INTLAPI.RemoveDiscordBaseResultObserver(OnDiscordBaseResult);

// process DiscordBaseResult callback event
private void OnDiscordBaseResult(INTLBaseResult baseRet)
{
    string methodTag = "";

    if (baseRet.MethodId == (int)INTLMethodID.INTL_FRIEND_DISCORD_AUTHORIZE) {
        methodTag = "DiscordAuthorize";
    } else if (baseRet.MethodId == (int)INTLMethodID.INTL_FRIEND_DISCORD_CREATE_LOBBY) {
        methodTag = "DiscordCreateLobby";
    } else if (baseRet.MethodId == (int)INTLMethodID.INTL_FRIEND_DISCORD_LEAVE_LOBBY) {
        methodTag = "DiscordLeaveLobby";
    } else if (baseRet.MethodId == (int)INTLMethodID.INTL_FRIEND_DISCORD_SET_RICH_PRESENCE) {
        methodTag = "DiscordSetRichPresence";
    } else if (baseRet.MethodId == (int)INTLMethodID.INTL_FRIEND_DISCORD_SEND_MESSAGE) {
        methodTag = "DiscordSendMessage";
    } else if (baseRet.MethodId == (int)INTLMethodID.INTL_FRIEND_DISCORD_REMOVE_FRIEND) {
        methodTag = "DiscordRemoveFriend";
    } else if (baseRet.MethodId == (int)INTLMethodID.INTL_FRIEND_DISCORD_ADD_FRIEND_BY_ID) {
        methodTag = "DiscordAddFriendByID";
    } else if (baseRet.MethodId == (int)INTLMethodID.INTL_FRIEND_DISCORD_ADD_FRIEND_BY_NAME) {
        methodTag = "DiscordAddFriendByName";
    } else if (baseRet.MethodId == (int)INTLMethodID.INTL_FRIEND_DISCORD_ACCEPT_FRIEND_REQUEST) {
        methodTag = "DiscordAcceptFriendRequest";
    } else if (baseRet.MethodId == (int)INTLMethodID.INTL_FRIEND_DISCORD_SEND_INVITE_TO_FREIND) {
        methodTag = "DiscordSendInviteToFriend";
    } else if (baseRet.MethodId == (int)INTLMethodID.INTL_FRIEND_DISCORD_ACCEPT_INVITE_FROM_FRIEND) {
        methodTag = "DiscordAcceptInviteFromFriend";
    } else if (baseRet.MethodId == (int)INTLMethodID.INTL_FRIEND_DISCORD_ON_RELATIONSHIP_CHANGED) {
        methodTag = "DISCORD_ON_RELATIONSHIP_CHANGED";
    } else if (baseRet.MethodId == (int)INTLMethodID.INTL_FRIEND_DISCORD_ON_LOBBY_MEMBER_CHANGED) {
        methodTag = "DISCORD_ON_LOBBY_MEMBER_CHANGED";
    }
}

DiscordUserResultObserver​

// add the callback
INTLAPI.AddDiscordUserResultObserver(OnDiscordUserResult);

// remove the callback
INTLAPI.RemoveDiscordUserResultObserver(OnDiscordUserResult);

// process OnDiscordUserResult callback event
private void OnDiscordUserResult(INTLDiscordUserResult userRet)
{
     string methodTag = "";
     if (userRet.MethodId == (int)INTLMethodID.INTL_FRIEND_DISCORD_GET_CONNECTED_USER)
     {
         methodTag = "DiscordGetConnectedUser";
     }
 }

DiscordFriendsResultObserver​

// add the callback
INTLAPI.AddDiscordFriendsResultObserver(OnDiscordFriendResult);

// remove the callback
 INTLAPI.RemoveDiscordFriendsResultObserver(OnDiscordFriendResult);

// process OnDiscordFriendResult callback event
private void OnDiscordFriendResult(INTLDiscordFriendResult friendRet)
 {
    string methodTag = "";
    if (friendRet.MethodId == (int)INTLMethodID.INTL_FRIEND_DISCORD_QUERY_FRIENDS)
    {
        methodTag = "DiscordQueryFriends";
    }
}

DiscordMessageResultObserver​

// add the callback
INTLAPI.AddDiscordMessageResultObserver(OnDiscordMessageResult);

// remove the callback
INTLAPI.RemoveDiscordMessageResultObserve(OnDiscordMessageResult);

// process OnDiscordMessageResult callback event
private void OnDiscordMessageResult(INTLDiscordMessageResult messageRet)
{
    string methodTag = "";
    if (messageRet.MethodId == (int)INTLMethodID.INTL_FRIEND_DISCORD_ON_MESSAGE_CHANGED)
    {
        methodTag = "DISCORD_ON_MESSAGE_CHANGED";
    }
}

DiscordInviteResultObserver​

// add the callback
INTLAPI.AddDiscordInviteResultObserver(OnDiscordInviteResult);

// remove the callback
INTLAPI.RemoveDiscordInviteResultObserver(OnDiscordInviteResult);

// process OnDiscordInviteResult callback event
private void OnDiscordInviteResult(INTLDiscordInviteResult inviteRet)
{
    string methodTag = "";
    if (inviteRet.MethodId == (int)INTLMethodID.INTL_FRIEND_DISCORD_ON_INVITE_ACCEPTED)
    {
        methodTag = "DISCORD_ON_INVITE_ACCEPTED";
    }
}
note

It is strongly recommended to register the callbacks within the startup function of your game.

Step3：Functions​

DiscordAuthorize​

To use the following features about Discord, users must complete Discord account binding and grant friend permissions. The Scope for granting friend permissions is different from the Scope for granting login permissions.

First authorize : On mobile platforms, the Discord authorization page will be opened via browsers; On PC, if the Discord desktop application is installed, the app will be launched for authorization; if not, the browsers will be used to open the authorization page. After users enter their username and password and agree to the authorization, their Discord accounts will be bound to their game accounts.

Re-authorize : Local Cache is used for directly authorizing. If the same user changes physical devices or reinstalls the app, the authorization page will be opened again for authorizing.

De-authorize : To unbind the Discord account, users must operate on the game side (e.g., LI PASS account center). Simply deauthorizing app on the Discord platform will not really unbind the game account from the Discord account. If the users try to bind another different Discord accounts after authorizing, a conflict error will be returned.

info

This function should be called after each login and before calling any other Discord functions. Only after getting a SUCCESS result in the callback should other functions be called.

Authorization page style as follows: Image：authorize window

// function definition
public static void DiscordAuthorize();

// code sample
INTLAPI.DiscordAuthorize();

Observers : DiscordBaseResultObserver

DiscordGetConnectedUser​

Query the user information associated with the current Discord client. Return the DiscordUserResult via callback. For details on the user data structure, see DiscordUserInfo

// function definition
public static void DiscordGetConnectedUser();

// code sample
INTLAPI.DiscordGetConnectedUser();

Observers : DiscordUserResultObserver

DiscordSetRichPresence​

Set the rich presence for the current bound user on the Discord client. The input parameter presence can be referenced from : DiscordRichPresence

// function definition
public static void DiscordSetRichPresence(INTLDiscordRichPresence presence);

// code sample 
INTLDiscordRichPresence richPresence = new INTLDiscordRichPresence();
            
richPresence.GameName = "Sample";
richPresence.State = "HappyTime";
richPresence.Details = "This is INTL Sample Game";
richPresence.LargeText = "largeText";
richPresence.LargeImage = "http://mat1.gtimg.com/www/qq2018/imgs/qq_logo_2018x2.png";
richPresence.SmallText = "smallText";
richPresence.SmallImage = "http://mat1.gtimg.com/www/qq2018/imgs/qq_logo_2018x2.png";
richPresence.StartTime = 0;
richPresence.EndTime = 0;
richPresence.PartyMaxSize = 5;
richPresence.SupportedPlatforms = 1 | 8 | 16;
            
INTLAPI.DiscordSetRichPresence(richPresence);

Observers : DiscordBaseResultObserver

DiscordQueryFriends​

Get the Discord friend list of the currently bound user, including friends to whom the user has sent friend requests and friends from whom the user has received friend requests. For details on the friend data structure, see DiscordUserInfo.

Function definition​

public static void DiscordQueryFriends(int page, int count);

Input parameters​

ParameterTypeDescriptionRequiredFormat
pageintthe page number of the friend listyes>0
countintthe count of friends in every pageyes>0

Code sample​

INTLAPI.INTLDiscordQueryFriends(1, 10);

Observers : DiscordFriendsResultObserver

DiscordAddFriendByName​

Add a Discord friend with username, requiring the target user's confirmation. After the friend request is sent, the recipient can be found via DiscordQueryFriends.

Once the recipient accepts the request, the user who sent the friend request will receive a callback indicating that the friend list has changed.

// function definition
public static void DiscordAddFriendByName(string username);

// code sample
INTLAPI.DiscordAddFriendByName("xiaoming");

Observers : DiscordBaseResultObserver

DiscordAddFriendByID​

Add a Discord friend with uid, requiring the target user's confirmation. After the friend request is sent, the recipient can be found via DiscordQueryFriends.

Once the recipient accepts the request, the user who sent the friend request will receive a callback indicating that the friend list has changed.

// function definition
public static void DiscordAddFriendById(string userId);

// code sample
INTLAPI.DiscordAddFriendById("123456789");

Observers : DiscordBaseResultObserver

DiscordRemoveFriend​

Remove a specified Discord friend without confirmation.

The person who deletes and the person who is deleted will both receive callbacks indicating that their friend lists has changed.

// function definition
public static void DiscordRemoveFriend(string userId);

// code sample
INTLAPI.DiscordRemoveFriend("123456789");

Observers : DiscordBaseResultObserver

DiscordAcceptFriendRequest​

Accept another person's Discord friend request with userid.

After acceptance, both the requester and the recipient will receive callbacks indicating that their friend list has changed.

// function definition
public static void DiscordAcceptFriendRequest(string userId);

// code sample
INTLAPI.DiscordAcceptFriendRequest("123456789");

Observers : DiscordBaseResultObserver

note

No matter whether you call DiscordAddFriendByName, DiscordAddFriendByID, DiscordRemoveFriend, or DiscordAcceptFriendRequest, as long as it is successful, the friend list will change, and both the sender and the receiver will receive a callback.

You can receive the callback by observing DiscordBaseResult with the id kMethodIDFriendDiscordOnRelationshipChanged. This callback does not contain any user information, it simply notifies that the user's friend list has changed. If you need more details about friend information, please call DiscordQueryFriends to query.

DiscordSendMessage​

Sends a direct message to the specified user. The content of the message is restricted to 2,000 characters maximum.

After sending, both the sender and the receiver will receive a callback with the message content.

caution

Send messages may involve user privacy. The game side needs to provide appropriate notifications.

// function definition
public static void DiscordSendMessage(string recipientId, string content);

// code sample
INTLAPI.DiscordSendMessage("123456789", "hello world!");

Observers : DiscordBaseResultObserver

About sending messages, there are the following situations:

  • User A and user B are friends : A can send a message to B successfully.
  • User A and user B have never been friends : A fails to send a message to B.
  • User A and user B were friends before, but B has been removed by A:
    • If B is online, the DiscordSendMessage function callback returns success, but the Discord client does not display the message.
    • If B is offline, the DiscordSendMessage function callback returns an error with code 50007.
info

After setting the DiscordMessageResultObserver, you can listen for message changes from Discord friends. Messages may contain non-text content such as emojis, which need to be handled by the game. Messages can be of three types: created, edited, or deleted, which can be determined by the type member.

DiscordCreateLobby​

Joins the user to the specified lobby, creating one if it does not exist.

Currently, a user can only be in one lobby at a time. If the user are already in a lobby, please call DiscordLeaveLobby to leave the current lobby before joining a new one. Exiting the game does not automatically leave the lobby; the game need to call the function manually.

Note: Lobbies are not persistent. When all members leave, if no user joins the lobby within a few minutes, the created lobby will automatically expire.

secret: The lobby is specified by the supplied string, which should be a hard to guess secret generated by the game. All users who join the lobby with the same secret will be placed in the same lobby. The "secret" value expires after about 30 days, at which point the existing lobby cannot be joined and a new one would be created instead.

// function definition
public static void DiscordCreateLobby(string secret);

// code sample
INTLAPI.DiscordCreateLobby("testsecret");

Observers : DiscordBaseResultObserver

DiscordLeaveLobby​

Leave the lobby that the user is currently in.

// function definition
public static void DiscordLeaveLobby();

// code sample
INTLAPI.DiscordLeaveLobby();

Observers : DiscordBaseResultObserver

info

Whenever any member joins or leaves the lobby, every member in the lobby will receive a callback from DiscordBaseResultObserver.

DiscordSendInviteToFriend​

Send a party invitation to a friend.

To successfully send a game invitation, you must strictly follow the steps below:

  1. Create a game lobby
  2. Set the rich presence
  3. Send the game invitation

If the Invitees accept the invitation, the sender will receive a callback indicating a change of the lobby members.

// function definition
public static void DiscordSendInviteToFriend(string userId, string content);


// code sample
INTLAPI.DiscordSendInviteToFriend("123456789", "hi,come to play with me");

Observers : DiscordBaseResultObserver

DiscordAcceptInviteFromFriend​

There are two ways to accept game invitations from Discord:
Method 1: Function-based approach
Register DiscordInviteResultObserver. When the game detects an invitation from a Discord friend, you can call the function to accept the invitation within the callback.
Method 2: Click the join button in the Discord client
After clicking the join button in the Discord client, if the invitation is valid, the PC client will automatically join the inviter's lobby. On mobile, the app will be launched via deeplink. You should parse the deeplink according to the settings in Discord developer portal to obtain the lobby joinsecret from the deeplink, and then call DiscordCreateLobby to allow the invited player to join the inviter's lobby.

// function definition
public static void DiscordAcceptFriendRequest(string userId);


// code sample
INTLAPI.DiscordAcceptInviteFromFriend("123456789");

Observers : DiscordBaseResultObserver