> ## Documentation Index > Fetch the complete documentation index at: https://developers.partoo.co/llms.txt > Use this file to discover all available pages before exploring further. # List conversations > This endpoint lets you list all the Conversations you have access to. You can filter the conversations based on the Organization or the Business that they are related to. If you want to keep an up-to-date list of ongoing conversations for your businesses, we recommend using the [Message Received](/api-reference/webhooks-events/message-created) and [Message Deleted](#operation/message_deleted) Webhooks instead of periodically calling this endpoint. ⚠️ This endpoint is paginated using cursor pagination. This means that in order to get the next page of results, you need to provide the cursor returned in the previous call. ## OpenAPI ````yaml /assets/openapi/openapi-bundled.yaml get /conversations openapi: 3.1.0 info: title: Partoo Rest API version: v2 license: name: © Copyright Partoo url: https://www.partoo.co/en/gtu-api/ x-logo: url: >- https://partoo-client-images.s3.amazonaws.com/logo-partoo-restapi-white.png description: > ## Introduction The Partoo Rest API allows you to automate all the actions that are possible to do in the Partoo Web Application. The Partoo Rest API can be used for many different purposes: - Create/update/delete your businesses & users if you are a client. - Create/subscribe/manage organizations, businesses & users if you are a reseller. - Retrieve data on businesses you have access to if you are a publisher. - ... servers: - url: https://api.partoo.co/v2 description: Production server - url: https://api.sandbox.partoo.co/v2 description: Sandbox server (dev environment for clients & partners) security: - ApiKeyAuth: [] paths: /conversations: get: tags: - Messages summary: List conversations description: > This endpoint lets you list all the Conversations you have access to. You can filter the conversations based on the Organization or the Business that they are related to. If you want to keep an up-to-date list of ongoing conversations for your businesses, we recommend using the [Message Received](/api-reference/webhooks-events/message-created) and [Message Deleted](#operation/message_deleted) Webhooks instead of periodically calling this endpoint. ⚠️ This endpoint is paginated using cursor pagination. This means that in order to get the next page of results, you need to provide the cursor returned in the previous call. operationId: listConversations parameters: - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/query_business__in' responses: '200': description: OK content: application/json: schema: description: Response object type: object properties: conversations: type: array description: The list of conversations, paginated. items: $ref: '#/components/schemas/Conversation' count: $ref: '#/components/schemas/Count' next_cursor: $ref: '#/components/schemas/NextCursor' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' components: parameters: PerPage: in: query name: per_page schema: type: integer default: 30 minimum: 1 maximum: 100 description: Number of items to return per page. Cursor: in: query name: cursor schema: type: string description: > The cursor identifiying the page of data to fetch. If no cursor is provided, the query will return the first page of data. A cursor for the next page of data is provided in the response of this request. query_business__in: in: query name: business__in description: >- Filter by business ids. Use a comma-separated list to provide multiple ids. schema: type: array example: >- a1c9f37b4deca92f83b61d02,9f4e2a8c0d73b154e621bc97,c73b15e9fa42d60b3a8c21ef items: $ref: '#/components/schemas/BusinessId' description: '' schemas: Conversation: type: object title: Conversation properties: id: type: integer consumer_img: type: - string - 'null' format: url description: The url of the consumer's profile picture example: https://www.example.com/profile-picture.jpg consumer_name: type: - string - 'null' description: > The name of the consumer, can be empty. The format may differ depending on the platform of contact (ex: "John Doe", "John Doe (@johndoe)", "@johndoe", "", ...). example: John Doe consumer_phone_number: type: - string - 'null' description: | The phone number of the consumer, formatted in E.164 international format (ex: "+33612345678"). example: '+33612345678' consumer_email: type: - string - 'null' description: | The email of the consumer. example: john.doe@example.com last_message: oneOf: - type: 'null' - $ref: '#/components/schemas/Message' description: The last message exchanged in the conversation. is_read: type: boolean description: > If the last message received was read. This property is scoped to the user who performs the request. Multiple partoo users can have a different is_read value for the same conversation. is_read is always false in webhook payloads. status: allOf: - description: > If Open, it is possible to send a message in the conversation, else not. A conversation can be Closed if it is expired. - $ref: '#/components/schemas/ConversationStatus' created_at: type: string description: | The date of creation of the conversation, in the ISO 8601 format (ex: "2023-01-31 16:22:17.327878+00:00"). example: '2023-01-31 16:22:17.327878+00:00' has_one_user_message: type: boolean description: | If the conversation has at least one message sent by a Partoo user. business: allOf: - description: > Some basic information about the business that the conversation is associated with. - $ref: '#/components/schemas/ConversationBusiness' messaging_partner: $ref: '#/components/schemas/MessagingPartner' issues: type: array items: $ref: '#/components/schemas/ConversationIssue' description: > The list of issues that affect the conversation. The issues represent setup problem that the business may have with a messaging channel. It is not possible to send messages on a conversation that has issues. ⚠️ New values may be added to this enum without prior notice and without following the classic depreciation cycle. It is up to you to gracefully handle the case where new values are added. example: - facebook_no_page_linked first_message_date: type: string description: > The date at which the first message of the conversation was received, in the ISO 8601 format (ex: "2023-01-31 16:22:17.327878+00:00"). is_expired: type: boolean description: > If the conversation has expired. A conversation expires if the consumer has not contacted the business for a certain amount of time. You cannot send messages to an expired conversation. example: false is_solved: type: boolean description: > If the conversation has been solved. Conversations can be solved from our app or by updating conversation status to "closed". example: false is_automated: type: boolean description: | If a Partoo chatbot is assigned to the conversation. example: false assigned_user_id: type: - string - 'null' description: | The "user_id" of the user assigned to the conversation. example: 62d80fae74e8b11d700302b8 custom_channel: oneOf: - type: 'null' - $ref: '#/components/schemas/CustomChannel' description: >- Data about the custom channel, this object is filled only if the messaging partner is `Custom`. Count: description: > Total number of results available for the filters and dimensions requested. type: integer example: 1 NextCursor: type: - string - 'null' description: | The cursor to use in order to retrieve the next page of data. When all data have been fetched, the value is null. BusinessId: description: Business id type: string example: 5409c35a97bbc544d8e26737 Message: type: object title: Message properties: id: type: integer description: The id of the message. conversation_id: type: integer description: The id of the parent conversation. date: type: string description: | The date at which the message was sent or received, in the ISO 8601 format (ex: "2023-01-31 16:22:17.327878+00:00"). example: '2023-01-31 16:22:17.327878+00:00' content_type: $ref: '#/components/schemas/MessageContentType' sender_type: $ref: '#/components/schemas/SenderType' sender_label: type: - string - 'null' description: Name of the person sending the message example: Jane Doe status: $ref: '#/components/schemas/MessageStatus' is_deleted: type: boolean description: | If the message has been deleted by the consumer on the messaging channel (for now, only "Instagram" messages can be deleted). example: false is_automated: type: boolean description: | If the message was sent by a Partoo automation (chatbot, ...). example: false content: oneOf: - $ref: '#/components/schemas/TextMessageContent' - $ref: '#/components/schemas/ImageMessageContent' - $ref: '#/components/schemas/VideoMessageContent' - $ref: '#/components/schemas/AudioMessageContent' - $ref: '#/components/schemas/DocumentMessageContent' - $ref: '#/components/schemas/IgStoryReplyMessageContent' - $ref: '#/components/schemas/IgStoryMentionMessageContent' - $ref: '#/components/schemas/UnsupportedMessageContent' - $ref: '#/components/schemas/SolvingMessageContent' - $ref: '#/components/schemas/ReopeningMessageContent' user_id: type: - string - 'null' description: | For "User" messages sent via the Partoo application, the id of the user that sent the message. custom_channel: oneOf: - type: 'null' - $ref: '#/components/schemas/CustomChannelMessage' description: >- Data about the custom channel, this object is filled only if the messaging partner is `Custom`. ConversationStatus: type: string enum: - Open - Closed ConversationBusiness: type: object title: BusinessInfo properties: id: type: string name: type: - string - 'null' city: type: - string - 'null' zipcode: type: - string - 'null' country: type: - string - 'null' formatted_address: type: - string - 'null' MessagingPartner: description: > The channel that the message is being sent to/from. ⚠️ New values may be added to this enum without prior notice and without following the classic depreciation cycle. It is up to you to gracefully handle the case where new values are added. type: string enum: - Google - Facebook - Instagram - SMS - Whatsapp - Custom - Livechat example: Facebook ConversationIssue: type: string enum: - facebook_no_page_linked - facebook_partner_co_undone - facebook_invalid_status - facebook_missing_webhook_subs - instagram_no_account_linked - sms_no_phone_number CustomChannel: type: object title: Message properties: id: type: string description: The id of the custom channel. name: type: string description: The name of the custom channel. icon: type: string description: Url of the channel's icon. is_readonly: type: boolean description: >- Set to `true` if the channel to be read-only (i.e., no replies via Partoo) external_conversation_id: type: string description: The unique id of the conversation in your system. MessageContentType: type: string enum: - Text - Image - Video - Audio - Document - IgStoryReply - IgStoryMention - Unsupported description: > The type of the message: - "Text" describes a simple text message. - "Image" describes a message that only contains an image. - "IgStoryReply" (for "Instagram" conversations) describes a notification of reply to an Instagram story. - "IgStoryMention" (for "Instagram" conversations) describes a notification of a mention in an Instagram story. - "Unsupported" describes a message whose content is not supported. ⚠️ New values may be added to this enum without prior notice and without following the classic depreciation cycle. It is up to you to gracefully handle the case where new values are added. We recommend showing a "Unhandled content" placeholder to the user in place of the message ⚠️ SenderType: type: string enum: - User - Consumer - Metadata description: > Describes the person that sent the Message: - "User" indicates that the message was sent as the Business. Such messages can be sent by a Partoo user, via API, or directly on the messaging platform. - "Consumer" indicates that the message was sent by a consumer, a client that wants to get in touch with the business. - "Metadata" is reserved for special messages that appear in the Partoo inbox. They only give contextual information about the conversation, and are not shown to the consumer. ⚠️ New values may be added to this enum without prior notice and without following the classic depreciation cycle. It is up to you to gracefully handle the case where new values are added. We recommend ignoring messages with unhandled sender_type ⚠️ MessageStatus: type: string enum: - Sending - Success - Failed description: > The delivery status of the message. Messages send via Partoo are created with the status "Sending", and propagated to the messaging channel. If the message is sent successfully, the status is changed to "Success". If the messaging channel fails to send the message, the status changed to "Failed". A failed message can be retried using the [/retry endpoint](/api-reference/messages/retry-send-message). TextMessageContent: title: Text type: string description: The text of the message. ImageMessageContent: title: Image type: string format: url description: The url of the image. VideoMessageContent: type: object title: Video properties: url: type: string format: url description: The url of the video. file_name: type: - string - 'null' description: Name of the video file. AudioMessageContent: type: object title: Audio properties: url: type: string format: url description: The url of the audio. file_name: type: - string - 'null' description: Name of the audio file. DocumentMessageContent: type: object title: Document properties: url: type: string format: url description: The url of the document. file_name: type: - string - 'null' description: Name of the document file. IgStoryReplyMessageContent: type: object title: IgStoryReply properties: url: type: string format: url description: The url of the story that received the reply. content: type: string description: Text of the reply, or url of the image. content_type: type: string enum: - Image - Text description: The type of content of ther reply. id: type: string description: The Instagram ID of the story. IgStoryMentionMessageContent: type: string title: IgStoryMention format: url description: The url of the story mentionned. UnsupportedMessageContent: type: object title: Unsupported properties: type: type: string enum: - video - audio - unknown SolvingMessageContent: type: string enum: - Solving title: Solving (Metadata) ReopeningMessageContent: type: string enum: - Reopening title: Reopening (Metadata) CustomChannelMessage: type: object title: Message properties: external_message_id: type: string description: The unique id of the message in your system. responses: '401': description: You are not authenticated content: application/json: schema: description: Error that occurs when you are not authenticated type: object properties: errors: type: object description: The detail of the error encountered properties: authentication: type: string default: User not authenticated '403': description: | You are not allowed to perform this action content: application/json: schema: description: > Error that occurs when you are authenticated but you are trying to perform an action you are not allowed to perform type: object properties: errors: type: object description: The detail of the error encountered properties: authorization: type: string default: Operation not allowed securitySchemes: ApiKeyAuth: description: > The authentication system on Partoo API is using API Key that should be put in the header of the request (the name of the header is `x-APIKey`). An api_key is linked to a user. This user's role will give you different access level to the API features. type: apiKey in: header name: x-APIKey ````