# List recent conversations This operation lists conversations and their most recent message, ordered by when the most recent message was sent for that conversation. Endpoint: GET /v1/projects/{project_id}/conversations:recent 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: - `app_id` (string, required) The application ID - `only_active` (boolean) True if only active conversations should be listed. Default is false. - `page_size` (integer) The maximum number of conversations to fetch. Defaults to 10 and the maximum value is 50. - `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. - `order` (string) Whether to sort conversations by newest message first or oldest. Default is DESC (newest first) ## Response 200: - `200` (unknown) A successful response. ## Response 200 fields (application/json): - `conversations` (array) List of recent conversations - `conversations.conversation` (object) A collection of messages exchanged between a contact and an app. Conversations are normally created on the fly by Conversation API once a message is sent and there is no active conversation already. There can be only one active conversation at any given time between a particular contact and an app. - `conversations.conversation.active` (boolean) Flag for whether this conversation is active. - `conversations.conversation.active_channel` (string) 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" - `conversations.conversation.app_id` (string) The ID of the participating app. - `conversations.conversation.contact_id` (string) The ID of the participating contact. - `conversations.conversation.metadata` (string) Arbitrary data set by the Conversation API clients. Up to 1024 characters long. NOTE: This field has been deprecated due to changes in the system architecture or functionality. It is no longer actively maintained and may be removed in future versions. Please avoid relying on this field in new code. - `conversations.conversation.metadata_json` (object) Arbitrary data set by the Conversation API clients and/or provided in the `conversation_metadata` field of a SendMessageRequest. A valid JSON object. - `conversations.conversation.correlation_id` (string) Arbitrary correlation ID related to the MT message set by the Conversation API user. - `conversations.conversation.id` (string) The ID of the conversation. - `conversations.conversation.last_received` (string) The timestamp of the latest message in the conversation. The timestamp will be Thursday January 01, 1970 00:00:00 UTC if the conversation contains no messages. - `conversations.last_message` (object) A message on a particular channel. - `conversations.last_message.accept_time` (string) The time Conversation API processed the message. - `conversations.last_message.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. - `conversations.last_message.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. - `conversations.last_message.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. - `conversations.last_message.contact_id` (string) The ID of the contact. - `conversations.last_message.conversation_id` (string) The ID of the conversation. - `conversations.last_message.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" - `conversations.last_message.id` (string) The ID of the message. - `conversations.last_message.metadata` (string) Optional. Metadata associated with the contact. Up to 1024 characters long. - `conversations.last_message.injected` (boolean) Flag for whether this message was injected. - `conversations.last_message.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. - `conversations.last_message.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" - `conversations.last_message.app_message` (object) A message originating from a Conversation API app - `conversations.last_message.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)). - `conversations.last_message.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. - `conversations.last_message.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`. - `conversations.last_message.app_message.agent` (object) Represents an agent that is involved in a conversation. - `conversations.last_message.app_message.agent.display_name` (string) Agent's display name - `conversations.last_message.app_message.agent.type` (string) Agent's classification. It can be UNKNOWN_AGENT_TYPE, HUMAN or BOT. Enum: "UNKNOWN_AGENT_TYPE", "HUMAN", "BOT" - `conversations.last_message.app_message.agent.picture_url` (string) The Agent's picture url. - `conversations.last_message.app_message.reply_to` (object) Sends this message as a contextual reply to an inbound contact message, so the contact sees their original message quoted. Only supported on the WhatsApp channel. Conversation API keeps the mapping needed for the quote for 96 hours. If the referenced message is unknown or older than 96 hours, or the message is sent on a channel that does not support contextual replies, the message is still sent without the quote. For more information, see [Sending contextual replies](https://developers.sinch.com/docs/conversation/channel-support/whatsapp/message-support/#sending-contextual-replies). - `conversations.last_message.app_message.reply_to.message_id` (string, required) Required when using `reply_to`. The Conversation API ID of the inbound contact message this message replies to. Do not use a channel message ID (e.g., a WhatsApp message ID) from Meta. - `conversations.last_message.app_message.card_message` (object) Message containing text, media and choices. - `conversations.last_message.app_message.card_message.choices` (array) You may include choices in your Card Message. The number of choices is limited to 10. - `conversations.last_message.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}. - `conversations.last_message.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" - `conversations.last_message.app_message.card_message.choices.call_message` (object) - `conversations.last_message.app_message.card_message.choices.location_message` (object) - `conversations.last_message.app_message.card_message.choices.text_message` (object) - `conversations.last_message.app_message.card_message.choices.url_message` (object) - `conversations.last_message.app_message.card_message.choices.calendar_message` (object) - `conversations.last_message.app_message.card_message.choices.share_location_message` (object) - `conversations.last_message.app_message.card_message.description` (string) This is an optional description field that is displayed below the title on the card. - `conversations.last_message.app_message.card_message.height` (string) You can set the desired size of the card in the message. Enum: "UNSPECIFIED_HEIGHT", "SHORT", "MEDIUM", "TALL" - `conversations.last_message.app_message.card_message.title` (string) The title of the card message. - `conversations.last_message.app_message.card_message.media_message` (object) A message containing a media component. - `conversations.last_message.app_message.card_message.media_message.thumbnail_url` (string) An optional parameter. Will be used where it is natively supported. - `conversations.last_message.app_message.card_message.media_message.url` (string, required) Url to the media file. - `conversations.last_message.app_message.card_message.media_message.filename_override` (string) Overrides the media file name. - `conversations.last_message.app_message.card_message.message_properties` (object) Optional additional properties. - `conversations.last_message.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. - `conversations.last_message.app_message.carousel_message` (object) - `conversations.last_message.app_message.carousel_message.cards` (array, required) A list of up to 10 cards. - `conversations.last_message.app_message.carousel_message.choices` (array) Optional. Outer choices on the carousel level. The number of outer choices is limited to 3. - `conversations.last_message.app_message.choice_message` (object) Additional properties for the message. - `conversations.last_message.app_message.choice_message.choices` (array) The number of choices is limited to 10. - `conversations.last_message.app_message.choice_message.text_message` (object) - `conversations.last_message.app_message.choice_message.text_message.text` (string, required) The text to be sent. - `conversations.last_message.app_message.choice_message.message_properties` (object) - `conversations.last_message.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. - `conversations.last_message.app_message.template_message` (object) - `conversations.last_message.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. - `conversations.last_message.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. - `conversations.last_message.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`. - `conversations.last_message.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. - `conversations.last_message.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. - `conversations.last_message.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. - `conversations.last_message.app_message.list_message` (object) - `conversations.last_message.app_message.list_message.title` (string, required) A title for the message that is displayed near the products or choices. - `conversations.last_message.app_message.list_message.description` (string) This is an optional field, containing a description for the message. - `conversations.last_message.app_message.list_message.sections` (array, required) List of ListSection objects containing choices to be presented in the list message. - `conversations.last_message.app_message.list_message.sections.title` (string) Optional parameter. Title for list section. - `conversations.last_message.app_message.list_message.sections.items` (array, required) - `conversations.last_message.app_message.list_message.message_properties` (object) Additional properties for the message. Required if sending a product list message. - `conversations.last_message.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. - `conversations.last_message.app_message.list_message.message_properties.menu` (string) Optional. Sets the text for the menu of a choice list message. - `conversations.last_message.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. - `conversations.last_message.app_message.contact_info_message` (object) - `conversations.last_message.app_message.contact_info_message.name` (object, required) Name information of the contact. - `conversations.last_message.app_message.contact_info_message.name.full_name` (string, required) Full name of the contact - `conversations.last_message.app_message.contact_info_message.name.first_name` (string) First name. - `conversations.last_message.app_message.contact_info_message.name.last_name` (string) Last name. - `conversations.last_message.app_message.contact_info_message.name.middle_name` (string) Middle name. - `conversations.last_message.app_message.contact_info_message.name.prefix` (string) Prefix before the name. e.g. Mr, Mrs, Dr etc. - `conversations.last_message.app_message.contact_info_message.name.suffix` (string) Suffix after the name. - `conversations.last_message.app_message.contact_info_message.phone_numbers` (array, required) Phone numbers of the contact - `conversations.last_message.app_message.contact_info_message.phone_numbers.phone_number` (string, required) Phone number with country code included. - `conversations.last_message.app_message.contact_info_message.phone_numbers.type` (string) Phone number type, e.g. WORK or HOME. - `conversations.last_message.app_message.contact_info_message.addresses` (array) Physical addresses of the contact - `conversations.last_message.app_message.contact_info_message.addresses.city` (string) City Name - `conversations.last_message.app_message.contact_info_message.addresses.country` (string) Country Name - `conversations.last_message.app_message.contact_info_message.addresses.state` (string) Name of a state or region of a country. - `conversations.last_message.app_message.contact_info_message.addresses.zip` (string) Zip/postal code - `conversations.last_message.app_message.contact_info_message.addresses.type` (string) Address type, e.g. WORK or HOME - `conversations.last_message.app_message.contact_info_message.addresses.country_code` (string) Two letter country code. - `conversations.last_message.app_message.contact_info_message.email_addresses` (array) Email addresses of the contact - `conversations.last_message.app_message.contact_info_message.email_addresses.email_address` (string, required) Email address. - `conversations.last_message.app_message.contact_info_message.email_addresses.type` (string) Email address type. e.g. WORK or HOME. - `conversations.last_message.app_message.contact_info_message.organization` (object) Organization information of the contact. - `conversations.last_message.app_message.contact_info_message.organization.company` (string) Company name - `conversations.last_message.app_message.contact_info_message.organization.department` (string) Department at the company - `conversations.last_message.app_message.contact_info_message.organization.title` (string) Corporate title, e.g. Software engineer - `conversations.last_message.app_message.contact_info_message.urls` (array) URLs/websites associated with the contact - `conversations.last_message.app_message.contact_info_message.urls.url` (string, required) The URL to be referenced - `conversations.last_message.app_message.contact_info_message.urls.type` (string) Optional. URL type, e.g. Org or Social - `conversations.last_message.app_message.contact_info_message.birthday` (string) Date of birth in YYYY-MM-DD format. - `conversations.last_message.contact_message` (object) A message originating from a contact. - `conversations.last_message.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":… - `conversations.last_message.contact_message.channel_specific_message.message_type` (string) The message type. Enum: "nfm_reply" - `conversations.last_message.contact_message.channel_specific_message.message` (any) The message content. - `conversations.last_message.contact_message.channel_specific_message.message.type` (string, required) The interactive message type. Enum: "nfm_reply" - `conversations.last_message.contact_message.channel_specific_message.message.nfm_reply` (object, required) The interactive nfm reply message. - `conversations.last_message.contact_message.channel_specific_message.message.nfm_reply.name` (string, required) The nfm reply message type. Enum: "flow", "address_message" - `conversations.last_message.contact_message.channel_specific_message.message.nfm_reply.response_json` (string, required) The JSON specific data. - `conversations.last_message.contact_message.channel_specific_message.message.nfm_reply.body` (string, required) The message body. - `conversations.last_message.contact_message.choice_response_message` (object) - `conversations.last_message.contact_message.choice_response_message.message_id` (string, required) The message id containing the choice. - `conversations.last_message.contact_message.choice_response_message.postback_data` (string, required) The postback_data defined in the selected choice. - `conversations.last_message.contact_message.fallback_message` (object) - `conversations.last_message.contact_message.fallback_message.raw_message` (string) Optional. The raw fallback message if provided by the channel. - `conversations.last_message.contact_message.fallback_message.reason` (object) - `conversations.last_message.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" - `conversations.last_message.contact_message.fallback_message.reason.description` (string) A textual description of the reason. - `conversations.last_message.contact_message.fallback_message.reason.sub_code` (string) Enum: "UNSPECIFIED_SUB_CODE", "ATTACHMENT_REJECTED", "MEDIA_TYPE_UNDETERMINED", "INACTIVE_SENDER" - `conversations.last_message.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. - `conversations.last_message.contact_message.media_card_message` (object) - `conversations.last_message.contact_message.media_card_message.caption` (string) Caption for the media on supported channels. - `conversations.last_message.contact_message.media_card_message.url` (string, required) Url to the media file. - `conversations.last_message.contact_message.product_response_message` (object) - `conversations.last_message.contact_message.product_response_message.products` (array) The selected products. - `conversations.last_message.contact_message.product_response_message.products.id` (string, required) Required parameter. The ID for the product. - `conversations.last_message.contact_message.product_response_message.products.marketplace` (string, required) Required parameter. The marketplace to which the product belongs. Example: FACEBOOK - `conversations.last_message.contact_message.product_response_message.products.quantity` (integer) Output only. The quantity of the chosen product. - `conversations.last_message.contact_message.product_response_message.products.item_price` (number) Output only. The price for one unit of the chosen product. - `conversations.last_message.contact_message.product_response_message.products.currency` (string) Output only. The currency of the item_price. - `conversations.last_message.contact_message.product_response_message.title` (string) Optional parameter. Text that may be sent with selected products. - `conversations.last_message.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. - `total_size` (integer) ## 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)