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.

Using the new multipart messaging APIs

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:

  • sendMessagesendMultiPartMessage
  • subscribeToRoomsubscribeToRoomMultipart
  • hook: onMessage becomesonMultipartMessage in Swift and Android
  • fetchMessages fetchMultipartMessages

With the new methods the message structure changes from:

  • One required text part and one optionalattachment part,


  • Up to 10 parts, each of which may be text, attachment, or link. Their exact structure is documented in both the API docs, as well as the docs for individual SDKs - see example for the JavaScript SDK.

Ensuring backward compatibility during migration

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 text/plain part.
  • 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.

Steps to migrate your existing users

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!

Push notifications

Chatkit Push notifications currently only support sending text messages. The notification body contain the first message part of typetext/plain.
If a multi-part message contains no parts of type text/plain, the stringNew media-only message received️ will be delivered.