June 27, 2017

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.

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