Using Personas (Beta)

The Personas API allows a business to introduce a virtual “persona” into the thread. The persona may be backed by a human agent or a bot. This is useful for a variety of use cases, such as customer care, where the bot needs a way to represent passing the customer to a customer care representative.

When a persona is introduced into the thread, a new icon will be shown and all messages sent by the persona will be accompanied by an annotation above the message that states the persona name and the name of the Page the persona belongs to.

The Personas API allows you to create a persona, send messages and sender actions using a persona, and delete a persona if it's no longer in use.

Contents

Creating a Persona

To create a persona, send a POST request to the /personas endpoint. The property should include name and profile_picture_url for the persona.

Request

curl -X POST -H "Content-Type: application/json" -d '{
	"name": "John Mathew",
	"profile_picture_url": "https://facebook.com/john_image.jpg",
}'
"https://graph.facebook.com/me/personas?access_token=<PAGE_ACCESS_TOKEN>"
				

Response

The response will contain a Persona ID that can be used to send future messages. Please note that this ID is private and it is unique to a Page.

{
    "id": "<PERSONA_ID>"
}

Guidelines for Personas

  • The name of a persona is freeform, but we recommend a first name and last initial, such as "John Z.".
  • The page name of the bot will still be included at the top of the thread, even when a persona is invoked. It is not necessary to include the company name in the name field.
  • The persona should not be overly generic.
  • The persona should be clearly distinguished from the page/bot itself.
  • The persona should not attempt to deceive the user.
  • A persona can be created on the fly. It is not necessary to sync one's entire database of agents to Messenger Platform in advance.
  • The total size of the image in profile_picture_url may not exceed 8MB.

Sending Messages as a Personas

Once you have defined the persona, you can invoke it at anytime. Once invoked, the persona's icon will be displayed, and all messages sent by the persona will be accompanied by an annotation above the message that states the persona name and the name of the Page the persona belongs to.

To send a message as a Persona in the conversation, send a POST request to the /messages endpoint with the persona_id property in the body of the request:

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

Note: persona_id is a optional property. If persona_id is not included, the message will be sent normally.

Using Sender Actions

The sender actions message property allows you to control indicators for typing in the conversation via the Send API. When you begin processing a message, you might set the typing indicator with persona_id to show them that a response is in-progress from a Persona.

To send a sender action as a Persona in the conversation, send a POST request to the Messenger Platform endpoint /messages with the persona_id property.

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{
    "id":"<USER_PSID>"
   },
  "sender_action":"<typing_on/typing_off>",
  "persona_id": "<PERSONA_ID>"
 }' "https://graph.facebook.com/me/messages?access_token=PAGE_ACCESS_TOKEN"

Note: persona_id with sender actions is supported only for typing_on and typing_off actions.

Using Sender Actions →

Retrieving a Persona

To retrieve the name and profile picture of a persona, send a GET request to the /<persona_id> endpoint:

Request

  curl -X GET "https://graph.facebook.com/<PERSONA_ID>?access_token=<PAGE_ACCESS_TOKEN>"

Response

The Messenger Platform will respond with a persona name and profile_picture_url.

{
     "name": "John Mathew",
     "profile_picture_url": "https://facebook.com/john_image.jpg",
     "id": "<PERSONA_ID>"
}

Retrieving All Available Personas

To retrieve all the personas associated with a Page, send a GET request to the /personas endpoint:

Request

  curl -X GET "https://graph.facebook.com/me/personas?access_token=<PAGE_ACCESS_TOKEN>"

Response

The Messenger Platform will respond with a list of personas:

{
  "data": [
    {
      "name": "John Mathew",
      "profile_picture_url": "https://facebook.com/john_image.jpg",
      "id": "<PERSONA_ID>"
    },
    {
      "name": "David Mark",
      "profile_picture_url": "https://facebook.com/david_image.jpg",
      "id": "<PERSONA_ID>"
    },
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUlMtR2ZATQlRtVUZALUlloV1",
      "after": "QVFIUkpnMGx0aTNvUjJNVmJUT0Yw"
    }
  }
}

Deleting a Persona

To delete a persona, send a DELETE request to the /<persona_id> endpoint. Messages previously sent by this persona will continue to appear in the chat history of the thread. Once a person is deleted, it will no longer be able to send new messages.

Request

curl -X DELETE "https://graph.facebook.com/<PERSONA_ID>?access_token=PAGE_ACCESS_TOKEN"
    

Response

The response will be true if successful.

{
    "success": true
}