Messenger Platform

Guest Mode for Messenger

Guest mode allows a person to chat with a business via the Chat Plugin without logging into their Facebook account. This allows businesses to seamlessly connect with more customers, regardless of their browser, device, or Facebook login status. These “guest users” are temporary accounts that can receive messages when the user is on your website. “Guest chats” will end when the user decides to end the chat from the More menu, or 24 hours from the start of the conversation, whichever comes first. The guest name will appear as “Guest” followed by a short numeric string.

If the business tries to send a message to this guest user when the guest accounts have been terminated, they will see an error message, “This Person Cannot Receive Messages: This person isn't receiving messages from you right now.” The transcript of these “guest chats” will remain on the guest user's browser for up to 24 hours. Businesses, however, will retain a copy of the conversation in their inbox even after the chat expires until they delete it.

The following changes in Plugin implementation will take effect as a result of this update:

  • Messaging Referrals webhook: messaging_referrals webhook will include an is_guest_user=true flag to indicate a guest user. We recommend that developers read this webhook and give businesses the option to treat guest users different from logged in users in designing their conversation flow.
  • Termination webhook: when a guest user chooses to end the conversation, we will send a webhook notification to let the business know that the guest is no longer available. Future messages to that GuestID will fail and the error message #100 No matching user found will be sent. We recommend that developers read this webhook, notify the live agent and stop the conversation flow when a guest conversation is terminated.

Messaging Referrals Webhook

messaging_referrals webhook from guest users now include the is_guest_user=true flag, indicating this is a webhook from a guest user. Developer can refer to Handle the messaging_referrals event for existing conversations section for instructions on how to setup referral webhooks.

{
  "sender":{
    "id":"<GUEST_ID>"
  },
  "recipient":{
    "id":"<PAGE_ID>>"
  },
  "timestamp":1458692752478,
  "referral": {
     "ref": "<REF_DATA_PASSED_IN_CODE>",
     "source": "CUSTOMER_CHAT_PLUGIN",
     "type": "OPEN_THREAD",
     "referer_uri": "<WEBSITE_URL>",
     "is_guest_user": "true"
  }
}

Termination Webhook

When a guest user ends the conversation on the Chat Plugin, we will send a webhook to let developers know that the GUEST_ID is no longer valid and will no longer be receiving messages. Developers should make sure their environment prevents future messages to this conversation.

{
  "sender":{
    "id":"<GUEST_ID>"
  },
  "recipient":{
    "id":"<PAGE_ID>"
  },
  "timestamp":1458692752478,
  "referral": {
     "ref": "<REF_DATA_PASSED_IN_CODE>",
     "source": "CUSTOMER_CHAT_PLUGIN",
     "type": "END_CHAT",
     "referer_uri": "<WEBSITE_URL>"
     "is_guest_user": "true" #only for guest users
  }
}

User Profile API

Locale, gender and timezone information aren't available for guest users.

curl -X GET "https://graph.facebook.com/v7.0/<GUEST_ID>?fields=first_name,last_name,profile_pic,is_guest_user"
  
{
    "first_name": "Guest",
    "last_name": "1234",
    "profile_pic": "https://example.com/profile.jpg",
    "is_guest_user": "true"
}

Conversation API

Conversation API user_id parameter will also accept GUEST_ID to allow developers to get the thread history of a guest user.

curl -i -X GET \
 "https://graph.facebook.com/v7.0/me/conversations?user_id=<PSID/GUEST_ID>"

Send API

Send API id parameter will also accept GUEST_ID to allow developers to send messages to guest user.

curl -X POST -H "Content-Type: application/json" -d '{
  "messaging_type": "<MESSAGING_TYPE>",
  "recipient": {
    "id": "<GUEST_ID>"
  },
  "message": {
    "text": "hello, world!"
  }
}' "https://graph.facebook.com/v19.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

Issues With Guest Users

Businesses experiencing issues with guest users have the following control:

  • Turn guest mode on/off from Page Settings → Messaging → Add Messenger to your website → Get Started → Toggle Guest Mode off
  • Block a guest-user on Facebook’s Page Inbox
  • Report a repeat guest-user offender by submitting this form

Guest Mode Upgrade

Guest users will have the option to log in to Messenger to continue their chat with businesses. We call this the "upgrade" moment for the guest user.

A guest user can be prompted to log in to Facebook under these circumstances:

  • When the business sets their status as “Away” in Page Inbox: this allows the user to get a response from the business in their Messenger when the business is back
  • When the user tries to send the business an attachment: sending attachments isn’t allowed for guest users at the moment, users will have to log in to send the attachment.
  • When the user clicks on the "Continue in Messenger" button under the drop down menu.

Pages that are not linked to any developer app will have guest upgrade feature available by default. Pages that are linked to a developer app will have the option to turn on guest upgrade via app dashboard under Messenger -> Settings -> Chat Plugin -> Guest Upgrade toggle. There are a couple of changes in the webhooks and API in order to support the "upgrade" moment.

Guest Upgrade Webhook

When a guest user upgrades, a new webhook with GUEST_UPGRADE type will be sent to allow developers to know that the guest user has upgraded and the associated PSID of the logged in user. Subsequent message webhooks after the guest user has upgraded will only contain PSID.

{
  "sender":{
    "id": "<GUEST_ID>"
  },
  "recipient":{
    "id": "<PAGE_ID>"
  },
  "timestamp": 1458692752478,
  "referral": {
     "ref": "<LOGGED_IN_USER_PSID>",
     "source": "CUSTOMER_CHAT_PLUGIN",
     "type": "GUEST_UPGRADE",
     "referer_uri": "<WEBSITE_URL>"
  }
}

User Profile API

When a guest user upgrades, querying User Profile API with GUEST_ID will return an additional psid field to allow developers to associate/link GUEST_ID with PSID. The psid field will return a PSID_EDGE with the name and PSID of the user by default.

curl -X GET "https://graph.facebook.com/v7.0/<GUEST_ID>?fields=first_name,last_name,profile_pic,psid"
  
{
    "first_name": "Guest",
    "last_name": "1234",
    "profile_pic": "https://example.com/profile.jpg",
    "psid": <PSID_EDGE>
}

<PSID_EDGE>
{
    "name": "John Doe",
    "id": "<PSID>"
}

Conversation API

With Conversation API now accepting GUEST_ID there will be 3 different scenarios depending on the state of the guest user.

Scenario 1 - Guest user has upgraded and Conversation API is called using PSID.

"data": [
    {
      "id": "<logged_in_user_thread_id>", 
      "link": "<link>",
      "updated_time": "<updated_time>"   
    }
 ]

Scenario 2 - Guest user has not upgraded and Conversation API is called using GUEST_ID

"data": [
    {
      "id": "<guest_user_thread_id>", 
      "link": "<link>",
      "updated_time": "<updated_time>"   
    }
 ]

Scenario 3 - Guest user has upgraded and Conversation API is called using GUEST_ID

"data": [
    {
      "id": "<guest_user_thread_id>", 
      "link": "<link>",
      "updated_time": "<updated_time>"   
    },
    {
      "id": "<logged_in_user_thread_id>", 
      "link": "<link>",
      "updated_time": "<updated_time>"   
    }
 ]