Skip to content
Conversation API/
/
Metadata guide
Last updated

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 and mobile originated (MO) messages to MO callbacks and delivery report (DR) callbacks.

Conversation API metadata can be organized into two different categories:

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 sourceDR callback propagation?MO callback propagation?
MT field conversation_metadataNoYes, as message_metadata
MT field message_metadataYes, 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_idYes, as correlation_idYes, as correlation_id
Channel metadata (provided by underlying Conversation API channel)Yes, as message_metadata or channel_metadataYes, as metadata (contained within the message object) or channel_metadata

MT Metadata

MT metadata is metadata set when making a send message API call. 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 sourceDR callback propagation?MO callback propagation?
MT field conversation_metadataNoYes, as message_metadata
MT field message_metadataYes, 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_idYes, as correlation_idYes, 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:

The conversation metadata is defined in the conversation_metadata object.

{
    "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"
    }
}

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.

The message metadata is defined in the message_metadata field:

{
  "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"
}

The correlation_id field

The correlation_id field is used with the Batch functionality of Conversation API. 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:

{
    "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"
    }
}

Channel Metadata

Channel metadata is metadata propagated to MO and DR callbacks from the underlying Conversation API channels themselves.

The table below has been included as a quick-reference resource for identifying the metadata fields in MO and DR callbacks:

Metadata sourceDR callback propagation?MO callback propagation?
Channel metadata (provided by underlying Conversation API channel)Yes, as message_metadata or channel_metadataYes, 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:

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.

{
  "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"
      }
    }
  }
}
Previous page
Next page