# Types of Conversation API metadata This page explains the metadata fields used in Sinch's Conversation API and how they propagate from [mobile terminated (MT) messages](https://community.sinch.com/t5/Glossary/MT-Mobile-Terminated/ta-p/7634) and [mobile originated (MO) messages](https://community.sinch.com/t5/Glossary/MO-Mobile-Originated/ta-p/7618) to MO callbacks and [delivery report (DR)](https://community.sinch.com/t5/Glossary/Delivery-Receipt-DLRs-or-DRs/ta-p/7523) callbacks. Conversation API metadata can be organized into two different categories: - [MT metadata](#mt-metadata), which is metadata you set when make a [send message API call](/docs/conversation/api-reference/conversation/messages/messages_sendmessage). - [Channel metadata](#channel-metadata), which is metadata propagated to MO and DR callbacks from the underlying [Conversation API channels](/docs/conversation/channel-support) themselves. The sub-sections on this page describe each category of metadata in more detail. Additionally, the table below has been included as a quick-reference resource for identifying the metadata sources and how the metadata propagates to DR and MO callbacks: | Metadata source | DR callback propagation? | MO callback propagation? | | --- | --- | --- | | MT field `conversation_metadata` | No | Yes, as `message_metadata` | | MT field `message_metadata` | Yes, as `metadata` (contained within the `message_delivery_report` object) | No, with the exception of `reply_to` and `choice_message_response` MO message types. | | MT field `correlation_id` | Yes, as `correlation_id` | Yes, as `correlation_id` | | Channel metadata (provided by underlying Conversation API channel) | Yes, as `message_metadata` or `channel_metadata` | Yes, as `metadata` (contained within the `message` object) or `channel_metadata` | ## MT Metadata MT metadata is metadata set when making a [send message API call](/docs/conversation/api-reference/conversation/messages/messages_sendmessage). The fields in which you can include such metadata are described in the following sub-sections below. Additionally, the table below has been included as a quick-reference resource for identifying the metadata fields and how they propagate from MTs to DR and MO callbacks: | Metadata source | DR callback propagation? | MO callback propagation? | | --- | --- | --- | | MT field `conversation_metadata` | No | Yes, as `message_metadata` | | MT field `message_metadata` | Yes, as `metadata` (contained within the `message_delivery_report` object) | No, with the exception of `reply_to` and `choice_message_response` MO message types. | | MT field `correlation_id` | Yes, as `correlation_id` | Yes, as `correlation_id` | ### The `conversation_metadata` field This is metadata that will be associated with the conversation in `CONVERSATION` mode and with the specified recipient identities in `DISPATCH` mode. This metadata will be propagated on MO callbacks associated with the respective conversation or user identity. `conversation_metadata` is **NOT** returned in DR Callback but is returned in MO callback under the `message_metadata` field: Original MT message The conversation metadata is defined in the `conversation_metadata` object. ```json { "app_id": "YOUR_app_ID", "recipient": { "identified_by": { "channel_identities": [ { "channel": "{{CHANNEL_FOR_MESSAGE_SEND}}", "identity": "{{WHATSAPP}}" } ] } }, "message": { "text_message": { "text": "Text message from Sinch Conversation API" }, "conversation_metadata": { "title": "conversation metadata title", "desc": "conversation metadata description" } } ``` DR callback The original value(s) for `conversation_metadata` is not returned in any field in the DR callbacks: ```json { "app_id": "YOUR_app_ID", "accepted_time": "2025-11-14T10:15:53.708Z", "event_time": "2025-11-14T10:15:54.922522628Z", "project_id": "YOUR_project_ID", "message_delivery_report": { ... "status": "READ", ... "metadata": "", }, "message_metadata": "", "correlation_id": "", "channel_metadata": {} } ``` MO callback The values provided in the `conversation_metadata` field of the original MT message are reflected in the `message_metadata` field: ```json { "app_id": "YOUR_app_ID", "accepted_time": "2025-11-14T10:19:40.810Z", "event_time": "2022-01-11T17:03:00Z", "project_id": "YOUR_project_ID", "message": { ... "contact_message": { "text_message": { "text": "Mo from whatsapp" } }, ... "metadata": "", }, "message_metadata": "{\"desc\":\"conversation metadata description\",\"title\":\"conversation metadata title\"}", "correlation_id": "", "channel_metadata": {} } ``` ### The `message_metadata` field The `message_metadata` field can be populated with an arbitrary string or JSON. This value will be reflected in the `metadata` field of the callback under `message_delivery_report`. The content is usually not propagated to MO callbacks with the exception of `reply_to` and `choice_message_response` MO message types. Original MT message The message metadata is defined in the `message_metadata` field: ```json { "app_id": "YOUR_app_ID", "recipient": { "identified_by": { "channel_identities": [ { "channel": "{{CHANNEL_FOR_MESSAGE_SEND}}", "identity": "{{WHATSAPP}}" } ] } }, "message": { "text_message": { "text": "Text message from Sinch Conversation API" } }, "message_metadata": "Hello I am message_metadata set in MT message request" } ``` DR callback The MT's `message_metadata` is propagated to the `metadata` field of the `message_delivery_report` object: ```json { "app_id": "YOUR_app_ID", "accepted_time": "2025-11-14T10:15:53.708Z", "event_time": "2025-11-14T10:15:54.922522628Z", "project_id": "YOUR_project_ID", "message_delivery_report": { ... "status": "READ", ... "metadata": "Hello I am message_metadata set in MT message request", }, "message_metadata": "", "correlation_id": "", "channel_metadata": {} } ``` MO callback The MT's `message_metadata` is not propagated in MO callbacks except for `reply_to` and `choice_message_response` MO message types: ```json { "app_id": "YOUR_app_ID", "accepted_time": "2025-11-14T10:29:08.795Z", "event_time": "2022-01-11T17:03:00Z", "project_id": "YOUR_project_ID", "message": { ... "contact_message": { "text_message": { "text": "Mo from whatsapp" } }, ... "metadata": "", }, "message_metadata": "", "correlation_id": "", "channel_metadata": {} } ``` ### The `correlation_id` field The `correlation_id` field is used with the [Batch functionality of Conversation API](/docs/conversation/api-reference/batch-api/batch/messages/batch_sendbatch#messages/batch_sendbatch/t=request&path=correlation_id). It's an arbitrary identifier that will be propagated to callbacks related to this message, including MO messages from the recipient. The MO callbacks will always use the last `correlation_id available` in the conversation. The `correlation_id` field is propagated as-is in both MT and MO callbacks: Original MT message ```json { "app_id": "YOUR_app_ID", "recipient": { "identified_by": { "channel_identities": [ { "channel": "{{CHANNEL_FOR_MESSAGE_SEND}}", "identity": "{{WHATSAPP}}" } ] } }, "message": { "text_message": { "text": "Text message from Sinch Conversation API" }, "correlation_id": "correlation_id text" } } ``` DR callback ```json { "app_id": "YOUR_app_ID", "accepted_time": "2025-11-14T10:15:53.708Z", "event_time": "2025-11-14T10:15:54.922522628Z", "project_id": "YOUR_project_ID", "message_delivery_report": { ... "status": "READ", ... "metadata": "", }, "message_metadata": "", "correlation_id": "correlation_id text", "channel_metadata": {} } ``` MO callback ```json { "app_id": "YOUR_app_ID", "accepted_time": "2025-11-14T10:29:08.795Z", "event_time": "2022-01-11T17:03:00Z", "project_id": "YOUR_project_ID", "message": { ... "contact_message": { "text_message": { "text": "Mo from whatsapp" } }, ... "metadata": "", }, "message_metadata": "", "correlation_id": "correlation_id text", "channel_metadata": {} } ``` ## Channel Metadata Channel metadata is metadata propagated to MO and DR callbacks from the underlying [Conversation API channels](/docs/conversation/channel-support) themselves. The table below has been included as a quick-reference resource for identifying the metadata fields in MO and DR callbacks: | Metadata source | DR callback propagation? | MO callback propagation? | | --- | --- | --- | | Channel metadata (provided by underlying Conversation API channel) | Yes, as `message_metadata` or `channel_metadata` | Yes, as `metadata` (contained within the `message` object) or `channel_metadata` | Examples of how the metadata is propagated to each of the callback types are below: DR callback In a DR callback, the metadata information can be passed by channel in the `message_metadata` string or in the `channel_metadata` object: Note We recommend using the information delivered in the `channel_metadata` field, which is the preferred field. It is an improved and more structured version of `message_metadata`. Support for the `message_metadata` may be deprecated in the future. ```json { "app_id": "YOUR_app_ID", "accepted_time": "2025-12-01T13:53:09.260Z", "event_time": "2025-12-01T13:53:10Z", "project_id": "YOUR_project_ID", "message_delivery_report": { // ... }, "message_metadata": "{\"pricing_category\":\"service\",\"whatsapp_conversation_id\":\"12345\",\"pricing_type\":\"free_customer_service\"}", "channel_metadata": { "whatsapp": { "conversation": { "type": "service" } } } } ``` MO callback In an MO callback, the metadata information can be passed by channel in the `metadata` string of the `message` object or in the `channel_metadata` object: Note We recommend using the information delivered in the `channel_metadata` field, which is the preferred field. It is an improved and more structured version of `message.metadata`. Support for the `message.metadata` may be deprecated in the future. ```json { "app_id": "YOUR_app_ID", "accepted_time": "2025-12-01T13:53:07.510Z", "event_time": "2025-12-01T13:53:06Z", "project_id": "YOUR_project_ID", "message": { // ... "metadata": "{\"referral\":{\"source_type\":\"\",\"source_id\":\"\",\"source_url\":\"\",\"ctwa_clid\":\"\",\"headline\":\"Our new product\",\"body\":\"This is a great product\"}}", }, "channel_metadata": { "whatsapp": { "message_type": "text", "profile_names": { "123456": "Name" } } } } ```