# List messages This operation lists all messages sent or received via particular [Processing Modes](https://developers.sinch.com/docs/conversation/processing-modes/). Setting the `messages_source` parameter to `CONVERSATION_SOURCE` allows for querying messages in `CONVERSATION` mode, and setting it to `DISPATCH_SOURCE` will allow for queries of messages in `DISPATCH` mode. Note that `conversation_id` and `contact_id` are only supported as query parameters if `messages_source` is set to `CONVERSATION_SOURCE`. Combining multiple parameters is supported for more detailed filtering of messages, but some of them are not supported depending on the value specified for `messages_source`. The description for each field will inform if that field may not be supported. The messages are ordered by their `accept_time` property in descending order, where `accept_time` is a timestamp of when the message was enqueued by the Conversation API. This means messages received most recently will be listed first. Endpoint: GET /v1/projects/{project_id}/messages Version: 1.0 Security: Basic, oAuth2 ## Security: - `Basic` (unknown) http basic - `oAuth2` (unknown) oauth2 ## Path parameters: - `project_id` (string, required) The unique ID of the project. You can find this on the [Sinch Dashboard](https://dashboard.sinch.com/convapi/apps). ## Query parameters: - `conversation_id` (string) Resource name (ID) of the conversation. - `contact_id` (string) Resource name (ID) of the contact. - `app_id` (string) Id of the app. - `channel_identity` (string) Channel identity of the contact. - `start_time` (string) Filter messages with `accept_time` after this timestamp. Must be before `end_time` if that is specified. - `end_time` (string) Filter messages with `accept_time` before this timestamp. - `page_size` (integer) Maximum number of messages to fetch. Defaults to 10 and the maximum is 1000. - `page_token` (string) Next page token previously returned if any. When specifying this token, make sure to use the same values for the other parameters from the request that originated the token, otherwise the paged results may be inconsistent. - `view` (string) - `messages_source` (string) Specifies the message source for which the request will be processed. Used for operations on messages in Dispatch Mode. For more information, see [Processing Modes](https://developers.sinch.com/docs/conversation/processing-modes/). - `only_recipient_originated` (boolean) If true, fetch only recipient originated messages. - `channel` (string) Only fetch messages from the `channel`. - `direction` (string) Optional. Only fetch messages with the specified `direction`. If direction is not specified, it will list both TO_APP and TO_CONTACT messages. ## Response 200: - `200` (unknown) A successful response. ## Response 200 fields (application/json): - `messages` (array) List of messages associated to the referenced conversation. - `messages.accept_time` (string) The time Conversation API processed the message. - `messages.channel_identity` (object) A unique identity of message recipient on a particular channel. For example, the channel identity on SMS, WHATSAPP or VIBERBM is a MSISDN phone number. - `messages.channel_identity.app_id` (string) Required if using a channel that uses app-scoped channel identities. Currently, FB Messenger, Instagram, LINE, and WeChat use app-scoped channel identities, which means contacts will have different channel identities on different Conversation API apps. These can be thought of as virtual identities that are app-specific and, therefore, the app_id must be included in the API call. - `messages.channel_identity.channel` (string, required) The identifier of the channel you want to include. Must be one of the enum values. Enum: "SMS", "RCS", "WHATSAPP", "MMS", "KAKAOTALK", "KAKAOTALKCHAT", "VIBERBM", "LINE", "INSTAGRAM", "MESSENGER", "WECHAT", "TELEGRAM", "APPLEBC" - `messages.channel_identity.identity` (string, required) The channel identity. This will differ from channel to channel. For example, a phone number for SMS, WhatsApp, and Viber Business. - `messages.contact_id` (string) The ID of the contact. - `messages.conversation_id` (string) The ID of the conversation. - `messages.direction` (string) The direction of the message flow, indicating whether the message was sent to or from the Conversation API app. Enum: "TO_APP", "TO_CONTACT" - `messages.id` (string) The ID of the message. - `messages.metadata` (string) Optional. Metadata associated with the contact. Up to 1024 characters long. - `messages.injected` (boolean) Flag for whether this message was injected. - `messages.sender_id` (string) For Contact Messages (MO messages), the sender ID represents the recipient to which the message was sent. This may be a phone number (in the case of SMS and MMS) or a unique ID (in the case of WhatsApp). This is field is not supported on all channels, nor is it supported for MT messages. - `messages.processing_mode` (string) Whether or not Conversation API should store contacts and conversations for the app. For more information, see [Processing Modes](https://developers.sinch.com/docs/conversation/processing-modes/). Enum: "CONVERSATION", "DISPATCH" - `messages.app_message` (object) A message originating from a Conversation API app - `messages.app_message.explicit_channel_message` (object) Allows you to specify a channel and define a corresponding channel specific message payload that will override the standard Conversation API message types. The key in the map must point to a valid conversation channel as defined in the enum `ConversationChannel`. The message content must be provided in a string format. You may use the [transcoding endpoint](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/Transcoding/) to help create your message. For more information about how to construct an explicit channel message for a particular channel, see that [channel's corresponding documentation](https://developers.sinch.com/docs/conversation/channel-support/) (for example, using explicit channel messages with [the WhatsApp channel](https://developers.sinch.com/docs/conversation/channel-support/whatsapp/message-support/#explicit-channel-messages)). - `messages.app_message.explicit_channel_omni_message` (object) Override the message's content for specified channels. The key in the map must point to a valid conversation channel as defined in the enum `ConversationChannel`. The content defined under the specified channel will be sent on that channel. - `messages.app_message.channel_specific_message` (object) Channel specific messages, overriding any transcoding. The structure of this property is more well-defined than the open structure of the `explicit_channel_message` property, and may be easier to use. The key in the map must point to a valid conversation channel as defined in the enum `ConversationChannel`. - `messages.app_message.agent` (object) Represents an agent that is involved in a conversation. - `messages.app_message.agent.display_name` (string) Agent's display name - `messages.app_message.agent.type` (string) Agent's classification. It can be UNKNOWN_AGENT_TYPE, HUMAN or BOT. Enum: "UNKNOWN_AGENT_TYPE", "HUMAN", "BOT" - `messages.app_message.agent.picture_url` (string) The Agent's picture url. - `messages.app_message.card_message` (object) Message containing text, media and choices. - `messages.app_message.card_message.choices` (array) You may include choices in your Card Message. The number of choices is limited to 10. - `messages.app_message.card_message.choices.postback_data` (any) An optional field. This data will be returned in the ChoiceResponseMessage. The default is message_id_{text, title}. - `messages.app_message.card_message.choices.display_mode` (string) Controls the display behavior of a choice. Only supported for Choice Message on the RCS channel. Has no effect on other channels or message types, except for a carousel's outer choices, where it is rejected outright. Enum: "DISPLAY_MODE_UNSPECIFIED", "PERSISTENT" - `messages.app_message.card_message.choices.call_message` (object) - `messages.app_message.card_message.choices.call_message.phone_number` (string, required) Phone number in E.164 with leading +. Example: +15551231234 - `messages.app_message.card_message.choices.call_message.title` (string, required) Title shown close to the phone number. The title is clickable in some cases. Example: Message text - `messages.app_message.card_message.choices.location_message` (object) - `messages.app_message.card_message.choices.location_message.coordinates` (object, required) - `messages.app_message.card_message.choices.location_message.label` (string) Label or name for the position. - `messages.app_message.card_message.choices.location_message.title` (string, required) The title is shown close to the button or link that leads to a map showing the location. The title can be clickable in some cases. - `messages.app_message.card_message.choices.text_message` (object) - `messages.app_message.card_message.choices.text_message.text` (string, required) The text to be sent. - `messages.app_message.card_message.choices.url_message` (object) - `messages.app_message.card_message.choices.url_message.title` (string, required) The title shown close to the URL. The title can be clickable in some cases. - `messages.app_message.card_message.choices.url_message.url` (string, required) The url to show. - `messages.app_message.card_message.choices.calendar_message` (object) - `messages.app_message.card_message.choices.calendar_message.title` (string, required) The title is shown close to the button that leads to open a user calendar. - `messages.app_message.card_message.choices.calendar_message.event_start` (string, required) The timestamp defines start of a calendar event. Example: 2025-11-30T10:00:00Z - `messages.app_message.card_message.choices.calendar_message.event_end` (string, required) The timestamp defines end of a calendar event. Example: 2025-11-30T11:00:00Z - `messages.app_message.card_message.choices.calendar_message.event_title` (string, required) Title of a calendar event. - `messages.app_message.card_message.choices.calendar_message.event_description` (string) Description of a calendar event. - `messages.app_message.card_message.choices.calendar_message.fallback_url` (string, required) The URL that is opened when the user cannot open a calendar event directly or channel does not have support for this type. - `messages.app_message.card_message.choices.share_location_message` (object) - `messages.app_message.card_message.choices.share_location_message.title` (string, required) The title is shown close to the button that leads to open a map to share a location. - `messages.app_message.card_message.choices.share_location_message.fallback_url` (string, required) The URL that is opened when channel does not have support for this type. - `messages.app_message.card_message.description` (string) This is an optional description field that is displayed below the title on the card. - `messages.app_message.card_message.height` (string) You can set the desired size of the card in the message. Enum: "UNSPECIFIED_HEIGHT", "SHORT", "MEDIUM", "TALL" - `messages.app_message.card_message.title` (string) The title of the card message. - `messages.app_message.card_message.media_message` (object) A message containing a media component. - `messages.app_message.card_message.media_message.thumbnail_url` (string) An optional parameter. Will be used where it is natively supported. - `messages.app_message.card_message.media_message.url` (string, required) Url to the media file. - `messages.app_message.card_message.media_message.filename_override` (string) Overrides the media file name. - `messages.app_message.card_message.message_properties` (object) Optional additional properties. - `messages.app_message.card_message.message_properties.whatsapp_header` (string) Optional. Sets the header for the footer of a WhatsApp reply button message, if there is no media in the message. Ignored for other channels. Ignored if not transcoded to a native WhatsApp message with reply buttons. - `messages.app_message.carousel_message` (object) - `messages.app_message.carousel_message.cards` (array, required) A list of up to 10 cards. - `messages.app_message.carousel_message.choices` (array) Optional. Outer choices on the carousel level. The number of outer choices is limited to 3. - `messages.app_message.choice_message` (object) Additional properties for the message. - `messages.app_message.choice_message.choices` (array) The number of choices is limited to 10. - `messages.app_message.choice_message.text_message` (object) - `messages.app_message.choice_message.text_message.text` (string, required) The text to be sent. - `messages.app_message.choice_message.message_properties` (object) - `messages.app_message.choice_message.message_properties.whatsapp_footer` (string) Optional. Sets the text for the footer of a WhatsApp reply button or URL button message. Ignored for other channels. - `messages.app_message.template_message` (object) - `messages.app_message.template_message.channel_template` (object) Optional. Channel specific template reference with parameters per channel. The channel template if exists overrides the omnichannel template. At least one of `channel_template` or `omni_template` needs to be present. The key in the map must point to a valid conversation channel as defined by the enum ConversationChannel. - `messages.app_message.template_message.omni_template` (object) The referenced template can be an omnichannel template stored in Conversation API Template Store as an AppMessage. You may also reference external channel-specific templates, such as a WhatsApp Business Template. Note that channel-specific template references are not supported when populating the `explicit_channel_omni_message` field. - `messages.app_message.template_message.omni_template.version` (string, required) Used to specify what version of a template to use. Required when using `omni_channel_override` and `omni_template` fields. This will be used in conjunction with `language_code`. Note that, when referencing omni-channel templates using the [Sinch Customer Dashboard](https://dashboard.sinch.com/), the latest version of a given omni-template can be identified by populating this field with `latest`. - `messages.app_message.template_message.omni_template.language_code` (string) The BCP-47 language code, such as `en_US` or `sr_Latn`. For more information, see http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. English is the default `language_code`. Note that, while many API calls involving templates accept either the dashed format (`en-US`) or the underscored format (`en_US`), some channel specific templates (for example, WhatsApp channel-specific templates) only accept the underscored format. Note that this field is required for WhatsApp channel-specific templates. - `messages.app_message.template_message.omni_template.parameters` (object) Required if the template has parameters. Concrete values must be present for all defined parameters in the template. Parameters can be different for different versions and/or languages of the template. - `messages.app_message.template_message.omni_template.template_id` (string, required) The ID of the template. Note that, in the case of WhatsApp channel-specific templates, this field must be populated by the name of the template. - `messages.app_message.list_message` (object) - `messages.app_message.list_message.title` (string, required) A title for the message that is displayed near the products or choices. - `messages.app_message.list_message.description` (string) This is an optional field, containing a description for the message. - `messages.app_message.list_message.sections` (array, required) List of ListSection objects containing choices to be presented in the list message. - `messages.app_message.list_message.sections.title` (string) Optional parameter. Title for list section. - `messages.app_message.list_message.sections.items` (array, required) - `messages.app_message.list_message.message_properties` (object) Additional properties for the message. Required if sending a product list message. - `messages.app_message.list_message.message_properties.catalog_id` (string) Required if sending a product list message. The ID of the catalog to which the products belong. - `messages.app_message.list_message.message_properties.menu` (string) Optional. Sets the text for the menu of a choice list message. - `messages.app_message.list_message.message_properties.whatsapp_header` (string) Optional. Sets the text for the header of a WhatsApp choice list message. Ignored for other channels. - `messages.app_message.contact_info_message` (object) - `messages.app_message.contact_info_message.name` (object, required) Name information of the contact. - `messages.app_message.contact_info_message.name.full_name` (string, required) Full name of the contact - `messages.app_message.contact_info_message.name.first_name` (string) First name. - `messages.app_message.contact_info_message.name.last_name` (string) Last name. - `messages.app_message.contact_info_message.name.middle_name` (string) Middle name. - `messages.app_message.contact_info_message.name.prefix` (string) Prefix before the name. e.g. Mr, Mrs, Dr etc. - `messages.app_message.contact_info_message.name.suffix` (string) Suffix after the name. - `messages.app_message.contact_info_message.phone_numbers` (array, required) Phone numbers of the contact - `messages.app_message.contact_info_message.phone_numbers.phone_number` (string, required) Phone number with country code included. - `messages.app_message.contact_info_message.phone_numbers.type` (string) Phone number type, e.g. WORK or HOME. - `messages.app_message.contact_info_message.addresses` (array) Physical addresses of the contact - `messages.app_message.contact_info_message.addresses.city` (string) City Name - `messages.app_message.contact_info_message.addresses.country` (string) Country Name - `messages.app_message.contact_info_message.addresses.state` (string) Name of a state or region of a country. - `messages.app_message.contact_info_message.addresses.zip` (string) Zip/postal code - `messages.app_message.contact_info_message.addresses.type` (string) Address type, e.g. WORK or HOME - `messages.app_message.contact_info_message.addresses.country_code` (string) Two letter country code. - `messages.app_message.contact_info_message.email_addresses` (array) Email addresses of the contact - `messages.app_message.contact_info_message.email_addresses.email_address` (string, required) Email address. - `messages.app_message.contact_info_message.email_addresses.type` (string) Email address type. e.g. WORK or HOME. - `messages.app_message.contact_info_message.organization` (object) Organization information of the contact. - `messages.app_message.contact_info_message.organization.company` (string) Company name - `messages.app_message.contact_info_message.organization.department` (string) Department at the company - `messages.app_message.contact_info_message.organization.title` (string) Corporate title, e.g. Software engineer - `messages.app_message.contact_info_message.urls` (array) URLs/websites associated with the contact - `messages.app_message.contact_info_message.urls.url` (string, required) The URL to be referenced - `messages.app_message.contact_info_message.urls.type` (string) Optional. URL type, e.g. Org or Social - `messages.app_message.contact_info_message.birthday` (string) Date of birth in YYYY-MM-DD format. - `messages.contact_message` (object) A message originating from a contact. - `messages.contact_message.channel_specific_message` (object) Example: {"nfm_reply":{"summary":"WhatsApp NFM Reply Channel Specific Contact Message Example","value":{"channel_specific_message":{"message_type":"nfm_reply","message":{"type":"nfm_reply","nfm_reply":{"name":… - `messages.contact_message.channel_specific_message.message_type` (string) The message type. Enum: "nfm_reply" - `messages.contact_message.channel_specific_message.message` (any) The message content. - `messages.contact_message.channel_specific_message.message.type` (string, required) The interactive message type. Enum: "nfm_reply" - `messages.contact_message.channel_specific_message.message.nfm_reply` (object, required) The interactive nfm reply message. - `messages.contact_message.channel_specific_message.message.nfm_reply.name` (string, required) The nfm reply message type. Enum: "flow", "address_message" - `messages.contact_message.channel_specific_message.message.nfm_reply.response_json` (string, required) The JSON specific data. - `messages.contact_message.channel_specific_message.message.nfm_reply.body` (string, required) The message body. - `messages.contact_message.choice_response_message` (object) - `messages.contact_message.choice_response_message.message_id` (string, required) The message id containing the choice. - `messages.contact_message.choice_response_message.postback_data` (string, required) The postback_data defined in the selected choice. - `messages.contact_message.fallback_message` (object) - `messages.contact_message.fallback_message.raw_message` (string) Optional. The raw fallback message if provided by the channel. - `messages.contact_message.fallback_message.reason` (object) - `messages.contact_message.fallback_message.reason.code` (string) Enum: "UNKNOWN", "INTERNAL_ERROR", "RATE_LIMITED", "RECIPIENT_INVALID_CHANNEL_IDENTITY", "RECIPIENT_NOT_REACHABLE", "RECIPIENT_NOT_OPTED_IN", "OUTSIDE_ALLOWED_SENDING_WINDOW", "CHANNEL_FAILURE", "CHANNEL_BAD_CONFIGURATION", "CHANNEL_CONFIGURATION_MISSING", "MEDIA_TYPE_UNSUPPORTED", "MEDIA_TOO_LARGE", "MEDIA_NOT_REACHABLE", "NO_CHANNELS_LEFT", "TEMPLATE_NOT_FOUND", "TEMPLATE_INSUFFICIENT_PARAMETERS", "TEMPLATE_NON_EXISTING_LANGUAGE_OR_VERSION", "DELIVERY_TIMED_OUT", "DELIVERY_REJECTED_DUE_TO_POLICY", "CONTACT_NOT_FOUND", "BAD_REQUEST", "UNKNOWN_APP", "NO_CHANNEL_IDENTITY_FOR_CONTACT", "CHANNEL_REJECT", "NO_PERMISSION", "NO_PROFILE_AVAILABLE", "UNSUPPORTED_OPERATION" - `messages.contact_message.fallback_message.reason.description` (string) A textual description of the reason. - `messages.contact_message.fallback_message.reason.sub_code` (string) Enum: "UNSPECIFIED_SUB_CODE", "ATTACHMENT_REJECTED", "MEDIA_TYPE_UNDETERMINED", "INACTIVE_SENDER" - `messages.contact_message.fallback_message.reason.channel_code` (string) Error code forwarded directly from the channel. Useful in case of unmapped or channel specific errors. Currently only supported on the WhatsApp channel. - `messages.contact_message.media_card_message` (object) - `messages.contact_message.media_card_message.caption` (string) Caption for the media on supported channels. - `messages.contact_message.media_card_message.url` (string, required) Url to the media file. - `messages.contact_message.product_response_message` (object) - `messages.contact_message.product_response_message.products` (array) The selected products. - `messages.contact_message.product_response_message.products.id` (string, required) Required parameter. The ID for the product. - `messages.contact_message.product_response_message.products.marketplace` (string, required) Required parameter. The marketplace to which the product belongs. Example: FACEBOOK - `messages.contact_message.product_response_message.products.quantity` (integer) Output only. The quantity of the chosen product. - `messages.contact_message.product_response_message.products.item_price` (number) Output only. The price for one unit of the chosen product. - `messages.contact_message.product_response_message.products.currency` (string) Output only. The currency of the item_price. - `messages.contact_message.product_response_message.title` (string) Optional parameter. Text that may be sent with selected products. - `messages.contact_message.product_response_message.catalog_id` (string) Optional parameter. The catalog id that the selected products belong to. - `next_page_token` (string) Token that should be included in the next request to fetch the next page. ## Response 400: - `400` (unknown) Malformed request. See [common error responses](https://developers.sinch.com/docs/conversation/api-reference/#common-error-responses) for more information. ## Response 400 fields (application/json): - `error` (object) - `error.code` (integer) - `error.details` (array) - `error.details.type_url` (string) - `error.details.value` (string) - `error.message` (string) - `error.status` (string) ## Response 401: - `401` (unknown) Incorrect credentials. See [common error responses](https://developers.sinch.com/docs/conversation/api-reference/#common-error-responses) for more information. ## Response 403: - `403` (unknown) Correct credentials but you don't have access to the requested resource. See [common error responses](https://developers.sinch.com/docs/conversation/api-reference/#common-error-responses) for more information. ## Response 403 fields (application/json): - `error` (object) - `error.code` (integer) - `error.details` (array) - `error.details.type_url` (string) - `error.details.value` (string) - `error.message` (string) - `error.status` (string) ## Response 500: - `500` (unknown) Correct credentials but you don't have access to the requested resource. See [common error responses](https://developers.sinch.com/docs/conversation/api-reference/#common-error-responses) for more information. ## Response 500 fields (application/json): - `error` (object) - `error.code` (integer) - `error.details` (array) - `error.details.type_url` (string) - `error.details.value` (string) - `error.message` (string) - `error.status` (string) ## Response 501: - `501` (unknown) Something went wrong on our end, try again with exponential back-off. See [common error responses](https://developers.sinch.com/docs/conversation/api-reference/#common-error-responses) for more information. ## Response 501 fields (application/json): - `error` (object) - `error.code` (integer) - `error.details` (array) - `error.details.type_url` (string) - `error.details.value` (string) - `error.message` (string) - `error.status` (string)