Thread Context

Messenger Extensions SDK

This method is a part of the Messenger Extensions SDK. For information on including the SDK in your site, see Add Messenger Extensions SDK.

Availability
To check for its availability on a given client, call getSupportedFeatures() and check for the context property in the response.

The getContext() method retrieves additional information about the person and the thread that opened the webview. It is useful for creating interactive group experiences and games, as well as restricting any content that was intended to be shared only to a certain thread.

getContext() should be used instead of getUserID(), which is now deprecated.

Retrieving Thread Context
Validating the signed_request
Using Thread IDs with Global Pages

Retrieving Thread Context

Call this function to get the person's PSID, thread ID, and thread type. For a complete list of method parameters, see the getContext() Reference.

MessengerExtensions.getContext('YOUR_APP_ID', 
  function success(thread_context){
    // success
  },
  function error(err){
    // error
  }
);

Response Format

The response passed to the success callback will be a JavaScript object in the following format:

{
  "thread_type": "GROUP",
  "tid": "1411911565550430",
  "psid": "1293479104029354",
  "signed_request": "5f8i9XXH2hEaykXHKFvu-E5Nr6QRqN002JO7yl-w_9o.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsImlzc3VlZF9hdCI6MTUwNDA0NjM4MCwicGFnZV9pZCI6NjgyNDk4MTcxOTQzMTY1LCJwc2lkIjoiMTI1NDQ1OTE1NDY4MjkxOSIsInRocmVhZF90eXBlIjoiVVNFUl9UT19QQUdFIiwidGlkIjoiMTI1NDQ1OTE1NDY4MjkxOSJ9"
}

Validating the `signed_request`

There are situations where you may wish to transmit the information obtained from getContext() to your backend and validate it before performing some action like a login or purchase. This allows you to ensure that the information really did come from Messenger and was not spoofed.

The signed_request is base64url encoded and signed with an HMAC version of your App Secret, based on the OAuth 2.0 spec.

You can validate it with the following 4 steps:

Split the signed request into two parts delimited by a '.' character (e.g. 238fsdfsd.oijdoifjsidf899)
Decode the first part — the encoded signature — from base64url encoding.
Decode the second part — the payload — from base64url encoding. This can be used on the server side if needed.
Hash the original payload using HMAC SHA-256 and your app secret and confirm that it is equal to the encoded signature originally passed.
You may also wish to validate the issued_at timestamp in the payload to ensure the recency of the request.

This can be done in any modern programming language. Below is an example in PHP:

function parse_signed_request($signed_request) {
  list($encoded_sig, $payload) = explode('.', $signed_request, 2); 

  $secret = "appsecret"; // Use your app secret here

  // Decode the data
  $sig = base64_url_decode($encoded_sig);
  $data = json_decode(base64_url_decode($payload), true);

  // Confirm the signature
  $expected_sig = hash_hmac('sha256', $payload, $secret, $raw = true);
  if ($sig !== $expected_sig) {
    error_log('Bad Signed JSON signature!');
    return null;
  }

  return $data;
}

function base64_url_decode($input) {
  return base64_decode(strtr($input, '-_', '+/'));
}

Decoding the payload will yield an object with the same information as originally returned by getContext(), but with the addition of algorithm, issued_at, and page_id fields:

{
  "psid": "1293479104029354", 
  "algorithm": "HMAC-SHA256", 
  "thread_type": "GROUP", 
  "tid": "1411911565550430", 
  "issued_at": 1491351619, 
  "page_id": 167938560376726
}

Remember, to avoid accidentally divulging your app secret, this validation should happen on your server and never in client-side code.

Using Thread IDs with Global Pages

Some businesses use a global page structure with multiple pages associated with one app ID or bot. In this situation, the thread IDs returned by getContext() in the chat extension will be different for people in different countries.

Use the following API to resolve the country page-specific thread ID to a global thread ID, and use that global thread ID to maintain state among users accessing the chat extension from their respective regional pages.

Retrieve global thread ID:

curl -X GET "https://graph.facebook.com/v2.6/{thread-id}?access_token=<PAGE_ACCESS_TOKEN>"

Example response:

    {"tid":1577059318985661,"global_tid":1577059318985661}