[Channel API] Message import improvements

Starting May 31, 2021, important usability improvements will be introduced to the Channel API. For developers of existing Channel API integrations, the changes are purely additive and no technical changes should be necessary. Nevertheless, we highly recommend taking advantage of these improvements to conserve API calls and simplify code. The changes can be summarized as follows:

1. Webhook notifications when messages are successfully imported

Previously, after POSTing to the Sync inbound message or Sync outbound message endpoints, the developer would be responsible for using the message_uid in the response of that POST request to fetch the corresponding Front message and conversation id. To avoid requiring this extra API request, we are introducing a new message_imported webhook notification that will be delivered to the channel's webhook URL. This notification will have the following schema:

{
  "type": "message_imported",
  "payload": {
    [MESSAGE BODY]
  },
  "metadata": {
    // Will eventually be deprecated in favor of "external_conversation_ids"
    "external_conversation_id": string,
    // A single Front conversation may have multiple external conversation
    // ids because conversations in Front can be merged.
    "external_conversation_ids": [string]
  }
}

2. Message and Conversation routes by id accessible to Channel API tokens

It will also be possible to use the same JSON web token that you already use to make requests to the Sync inbound message or Sync outbound message endpoints to also make requests to any message or conversation routes by id. This will make it easier to fetch and update conversations and messages after they are initially created without having to use a separate Front API token.

This change applies to routes of the following format:

• /conversations/:conversation_id*
• /messages/:message_id*

Note that by using the channel's API token, the scope of the routes will be limited to conversations or messages that are related to the channel, not all conversations or messages from any channel in Front instance.

As part of this change, when using a channel's JSON web token to make /conversations or /messages API requests, conversation and message objects returned by the API will include a metadata property. For message objects the metadata will contain an external_id property, and for conversation objects the metadata will contain an external_conversation_ids array.

As always, if you have any questions please feel free to reach out on the Front Community.