Processing Modes

Breaking change:

As of April 16th, 2025, a breaking change was introduced to the Conversation API. The default processing mode changed from CONVERSATION to DISPATCH.

This change impacts all new Conversation API apps created after this date. Apps created prior to this date are unaffected by this change.

Please review your configurations and update any dependencies accordingly.

By default, Conversation API uses the DISPATCH processing mode, which handles messages without maintaining contacts and conversations. You may also use the CONVERSATION processing mode. Each mode is described below.

Processing Mode	Behavior
`DISPATCH`	Messages are not associated with Contacts and Conversations Message retention TTL is `[0 - 7]` days. In the case of a `0` day TTL, messages aren't stored at all Message retention policy can only be `MESSAGE_EXPIRE_POLICY` as there are no conversations or contacts
`CONVERSATION`	Messages are associated with Contacts and Conversations Message retention TTL is `[1 - 3650]` days Message retention policy can be `MESSAGE_EXPIRE_POLICY`, `CONVERSATION_EXPIRE_POLICY`, and `PERSIST_RETENTION_POLICY`

Setting the Processing Mode

You can set the processing mode in two ways:

On the App : the selected processing mode will be applied to every new MT and MO.
On individual MTs : only the MT will be sent in the selected processing mode. The processing mode won't carry over to the MO. For example, if the user responds a dispatch MT but the App is in CONVERSATION mode, a new Contact and Conversation may be created if they don't already exist. You should carefully evaluate this option as it's meant to be used by campaign dispatching services that initiate conversations.

Notes on Dispatch Mode

Below are guidelines for making Conversation API calls while using DISPATCH mode.

Sending messages and events

Contacts are note created in DISPATCH mode. Therefore, when using a Conversation API app set to DISPATCH mode, the following API calls should be made by including and populating the identified_by sub-object of the recipient object:

Listing messages

Since contacts and conversations are not created in DISPATCH mode, these operations will return status 400 if a contact_id or conversation_id are provided when using a Conversation API app set to DISPATCH mode: