Non-Versioned Breaking Changes

This log covers breaking changes made between

Platform Versions.

The most

recent version

of the API is Version 2.9, which was introduced on April 18th, 2017 as part of F8 2017.

To learn more about versions, please see our overview of

how versions work.

For more info on upgrading, including code samples, please see our

upgrade guide.

Breaking Changes

Platform Change Implemented Date Introduced Upgrade By

Graph API

Conversation ID Update

July 4,2017

Messenger API

Graph API Conversation

June 27th, 2017

September 25th, 2017

Conversation ID Update

The {user_id}/conversations and {page_id}/conversations APIs along with the associated WebHooks 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 the 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_id}/conversations

and

/{conversation_id}

allows developers to see the effect of this migration before it takes place.

Webhook Changes

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 Changes

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": {
  }
}