Breaking Changes

Breaking changes are any changes to existing functionality that will take effect immediately and impact all API versions. These changes can be introduced at any time and will not be tied to a specific release.

We avoid releasing Breaking Changes whenever possible and will make every effort to bundle changes into Platform Version releases so you have ample time to adjust your code.

Conversation ID

The user/conversations and page/conversations edges along with their associated Webhoooks will change the identifiers they use on July 4th. The IDs will still be prefixed with 't_' but what follows the prefix will change.

Graph API Conversation

The 'id' for the GraphAPI Conversation type will change. Messenger is migrating to a new database with enormous benefits to the Messenger product. The current GraphAPI 'id' is an identifier that won't be migrated to the new database. This will apply to all APIs that expose conversations, including Webhooks. Both old and new 'id' are currently accepted as valid IDs on all our GraphAPIs for Conversations.

To ease the transition, we're adding a new field to all the Webhooks that exposes the new identifier alongside the current identifier. This allows developers to map the current identifier to the new identifier and vice versa. We're also adding two new fields to the Conversation GraphAPI object to allow developers to map the current identifier to the new identifier. Lastly, the boolean parameter 'use_thread_key' on /page/conversations and /conversation allows developers to see the effect of this migration before it takes place.

Thread IDs are not globally unique. Just like thread_id, thread_key is unique per page, not across multiple pages.

Webhooks

The Webhooks expose the current identifier in the

'thread_id'

field. There will be a new

'thread_key'

field that will contain the new

Conversation

identifier, allowing developers to map the new identifier to the current identifier in updates from Webhooks. For the

{page_id}/conversations

Webhook, developers will now get updates in the following payload:

{
  field: 'conversations',
  values: {
    thread_id: 't_id.290234844429376',
    thread_key: 't_554591851336367',
    page_id: '554591851336367'
  }
}
'thread_key'

field contains the value that will populate the

'thread_id'

after the change has happened. To be clear, developers can expect the following Webhook payload after the change:

{
  "field": "conversations",
  "values": {
    "thread_id": "t_554591851336367",
    "thread_key": "t_554591851336367",
    "page_id": "6367185133"
  }
}

There will be a new

'thread_key'

field on all Webhooks that currently expose the

Conversation

identifier as

'thread_id'

.

Graph API

On the

Conversation

GraphAPI type, there will be two new fields. The

'thread_key'

field will contain the new identifier. The new field

'thread_id'

field will contain the current identifier. Before this change the

'id'

for Conversation will be the same as the

'thread_id'

field, but after the change the

'id'

will be the same as the

'thread_key'

field. Developers can see the new response by setting the

'use_thread_key'

parameter to true.

Before Change:
https://graph.facebook.com/{page_id}/conversations?limit=10&fields=thread_id,thread_key&access_token={access_token}
{
  "data": [
    {
      "thread_id": "t_id.450736921798255",
      "thread_key": "t_450736921798255",
      "id": "t_id.450736921798255"
    }
  ],
  "paging": {
  }
}
https://graph.facebook.com/{page_id}/conversations?limit=10&use_thread_key=true&fields=thread_id,thread_key&access_token={access_token}
{
  "data": [
    {
      "thread_id": "t_id.450736921798255",
      "thread_key": "t_450736921798255",
      "id": "t_450736921798255"
    }
  ],
  "paging": {
  }
}
After Change:
https://graph.facebook.com/{page_id}/conversations?limit=10&fields=thread_id,thread_key&access_token={access_token}
{
  "data": [
  {
    "thread_id": "t_450736921798255",
    "thread_key": "t_450736921798255",
    "id": "t_450736921798255"
  }
  ],
  "paging": {
  }
}