Messenger Platform

Personas API Reference (Beta)

Personas API allows a business to introduce a virtual “Persona” or voice into the thread backed by a human agent or a bot who carries a messaging conversation with end users in Messenger. It is still the same bot sending the message via the platform API, but we now have the option to send it under the voice of a Persona.

For more information on using the Personas API, see Using Personas.

Permissions

A Page access token with pages_messaging permission is required to interact with this endpoint.

Contents

Request URI

Create Persona / Retrieve All Personas

https://graph.facebook.com/me/personas?access_token=<PAGE_ACCESS_TOKEN>

Retrieve Persona / Delete Persona

https://graph.facebook.com/<PERSONA_ID>?access_token=<PAGE_ACCESS_TOKEN>

Example Request

Create Persona

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

Retrieve Persona

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

Retrieve All Personas

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

Delete Persona

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

Send Message with Persona

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>"

Properties

Create Persona

Property Type Description

name

String

The display name of the persona.

profile_picture_url

String

The URL of the user icon associated with the persona.

Response

Create Persona

{
    "id": "<PERSONA_ID>"
}
Property Type Description

id

String

The unique ID of the persona.

Retrieve All 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"
    }
  }
}
Property Type Description

data

Array

An array of personas

paging

Object

An object containing the before and after cursors used to paginate large result sets.

Retrieve Persona

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

name

String

The display name of the persona.

profile_picture_url

String

The URL of the user icon associated with the persona.

id

String

The unique ID of the persona.

Delete Persona

{
    "success": true
}
Property Type Description

success

bool

Outcome of the delete operation.