Migrating to multipart messages
This document explains the difference between the new multipart messaging format (introduced in API v3), and the legacy format, and outlines the steps required to take in order to migrate your code-base and users.
In order not to make a breaking change in the SDK APIs, we have added new methods which accept and return the new multi-part messages structures. Upgrade your SDK, and then change your usage as follows:
onMultipartMessagein Swift and Android
With the new methods the message structure changes from:
- One required
textpart and one optional
The new message format is much more powerful than the legacy format, and can take many more forms of messages. Because of that, it’s not fully compatible with the legacy format. To make your upgrade process smoother, we have included compatibility between two formats, and this should allow you to seamlessly migrate your apps and user base. There are some limitations however, as multipart messages can take forms that are impossible to represent in the legacy format.
When sending a multipart message to clients who expect the legacy message format, you must match the same restrictions as the old format:
- It MUST contain exactly one
- It MAY contain 0 or 1 attachment part.
When a legacy user receives a multipart message which does not meet these requirements, they will instead receive a substitute message.
The substitute message will contain a single text part with the contents:
You have received a message that can't be represented in this version of the app. You will need to upgrade to read it.
In order to migrate your user base smoothly, we recommend you take the following steps:
- Release a version of your app which uses the multipart methods and message structure, but sticks to the stated restrictions on message format. This should not be a problem, because all legacy messages will be representable as multipart.
- Wait until the critical mass of your user base has upgraded
- Make use of the full flexibility of multi-part messaging!
Chatkit Push notifications currently only support sending text messages. The notification body contain the first message part of type
If a multi-part message contains no parts of type
text/plain, the string
New media-only message received️ will be delivered.