getConversations: eBay Message API | eBay Developers Program

GET/conversation

This method can be used to retrieve one or more conversations associated with a user.

The conversation_type query parameter is required when using this method to specify if the retrieved conversations are from eBay or from members.

The result set can also optionally be filtered by conversation status, reference, username, and/or time range. The limit and offset path parameters can be used to paginate the result set and control how many conversations are returned in the response.

Input

Resource URI

GET https://api.ebay.com/commerce/message/v1/conversation?

limit=integer&

offset=integer&

conversation_status=string&

conversation_type=string&

reference_id=string&

reference_type=string&

start_time=string&

end_time=string&

other_party_username=string

This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com

URI parameters

Parameter	Type	Description
limit	integer	The maximum number of entries that can be returned on each page of the paginated response. Use this parameter in conjunction with the offset parameter to control the pagination of the output. For example, if offset is set to `10` and limit is set to `10`, the call retrieves entries 11 through 20 from the result set. Note: This feature employs a zero-based list, where the first item in the list has an offset of `0`. If this parameter is omitted, the default value is used. Default: 25 Maximum: 50 Occurrence: Optional
offset	integer	The number of reports to skip in the result set before returning the first entry in the paginated response. Use this parameter in conjunction with the limit parameter to control the pagination of the output. For example, if offset is set to `0` and limit is set to `10`, the first page of the response will contain the first 10 entries from the complete list retrieved by the call. Note: This feature employs a zero-based list, where the first item in the list has an offset of `0`. If this parameter is omitted, the default value is used. Default: 0 Occurrence: Optional
conversation_status	string	This query parameter specifies the status of the conversations being retrieved. Only conversations in the specified status will be returned. Valid values: `ACTIVE` `ARCHIVE` `DELETE` `READ` `UNREAD` Occurrence: Optional
conversation_type	string	This query parameter specifies the type of the conversations being retrieved. Only conversations of the specified type will be returned. This parameter is always required when using this method. Valid values: `FROM_EBAY` `FROM_MEMBERS` Occurrence: Required
reference_id	string	This query parameter specifies the unique identifier of the reference (specified by the corresponding reference_type value) associated with the conversation. Only conversations associated with the specified reference ID will be returned. For example, in the case of a `LISTING` reference, this value will be the item ID value of the listing. Note: If this query parameter is used, the reference_type parameter must also be used to specify the type of reference this ID is associated with. Occurrence: Optional
reference_type	string	This query parameter specifies the type of reference associated with a conversation. The reference type is used to specify what the conversation is in reference to. For example, a value of `LISTING` specifies that the conversation is associated with a specific listing. The item ID associated with this listing can then be specified through the reference_id query parameter. Currently, only the `LISTING` reference type is supported. Occurrence:
start_time	string	This query parameter specifies the start time (in ISO 8601 format) for which to start retrieving conversations. For example, if set to `2024-11-06T10:00:00.000Z`, only messages sent after this time will be retrieved. Format: yyyy-MM-ddThh:mm.ss.sssZ Note: Currently, this parameter is only available if the conversation_type of the conversation is `FROM_MEMBERS`. Occurrence: Optional
end_time	string	This query parameter specifies the end time (in ISO 8601 format) for which to stop retrieving conversations. For example, if set to `2024-11-06T10:00:00.000Z`, only messages sent before this time will be retrieved. Format: yyyy-MM-ddThh:mm.ss.sssZ Note: Currently, this parameter is only available if the conversation_type of the conversation is `FROM_MEMBERS`. Occurrence: Optional
other_party_username	string	This query parameter specifies the user name (login name) of an eBay user for which to retrieve conversations. If this filter is used, only conversation(s) from the other eBay user specified through this parameter will be returned. Occurrence: Optional

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

All other standard RESTful request headers are optional. For more information on standard RESTful request headers, see the HTTP request headers- opens rest request components page table.

OAuth scope

This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/commerce.message

See OAuth access tokens for more information.

Request payload

This call has no payload.

Request fields

This call has no field definitions.

Output

HTTP response headers

This call has no response headers.

Response payload

Copy complete valid JSON to clipboard

{ /* GetAllMyConversationsResponse */

"conversations" : [

{ /* ConversationDetail */

"conversationId" : "string",

"conversationStatus" : "string",

"conversationTitle" : "string",

"conversationType" : "string",

"createdDate" : "string",

"latestMessage" :

{ /* MessageDetail */

"createdDate" : "string",

"messageBody" : "string",

"messageId" : "string",

"messageMedia" : [

{ /* MessageMedia */

"mediaName" : "string",

"mediaType" : "string",

"mediaUrl" : "string"

}

"readStatus" : "boolean",

"recipientUsername" : "string",

"senderUsername" : "string",

"subject" : "string"

"referenceId" : "string",

"referenceType" : "string",

"unreadCount" : "integer"

}

"href" : "string",

"limit" : "integer",

"next" : "string",

"offset" : "integer",

"prev" : "string",

"total" : "integer"

}

Response fields

Output container/field	Type	Description
conversations	array of ConversationDetail	This array returns the conversations that match the filter criteria. Each conversation is returned with information such as its ID, status, title, type, and creation date, as well as the latest message in the conversation. Occurrence: Always
conversations.conversationId	string	The unique identifier of the conversation. Occurrence: Always
conversations.conversationStatus	string	This value indicates the current status of the conversation, such as `ACTIVE` or `ARCHIVE`. Occurrence: Always
conversations.conversationTitle	string	The title of the conversation. Occurrence: Always
conversations.conversationType	string	This value indicates the type of the conversation, such as `FROM_EBAY` or `FROM_MEMBERS`. Occurrence: Always
conversations.createdDate	string	This value indicates the date, in ISO 8601 format, the conversation was created. Occurrence: Always
conversations.latestMessage	MessageDetail	This container returns the latest message in the conversation and its details. Occurrence: Always
conversations.latestMessage.createdDate	string	The date, in ISO 8601 format, the message was received. Occurrence: Always
conversations.latestMessage.messageBody	string	The message text. Occurrence: Always
conversations.latestMessage.messageId	string	The unique identifier of the message. Occurrence: Always
conversations.latestMessage.messageMedia	array of MessageMedia	This array returns a list, if applicable, of media attached to the message. Occurrence: Conditional
conversations.latestMessage.messageMedia.mediaName	string	The name of the media attached to the message. Occurrence: Conditional
conversations.latestMessage.messageMedia.mediaType	string	The type of media attached to the message. Valid values: `IMAGE` `PDF` `DOC` `TXT` Occurrence: Conditional
conversations.latestMessage.messageMedia.mediaUrl	string	The URL of the self-hosted media attached to the message. URLs must use the "HTTPS" protocol. Occurrence: Conditional
conversations.latestMessage.readStatus	boolean	This boolean indicates if the message has been viewed by the recipient. If this boolean is returned as `true`, the message has been read. If this boolean is returned as `false`, the message has not been read. Occurrence: Always
conversations.latestMessage.recipientUsername	string	The eBay username of the message recipient. Occurrence: Always
conversations.latestMessage.senderUsername	string	The eBay username of the message sender. Occurrence: Always
conversations.latestMessage.subject	string	The subject line of the message. Occurrence: Conditional
conversations.referenceId	string	This value indicates the reference ID associated with the corresponding referenceType value. In the case of a `LISTING` referenceType, this value will be the item ID value of the associated listing. Occurrence: Conditional
conversations.referenceType	string	This value indicates the reference type, if applicable, associated with the conversation. The reference type is used to specify what the conversation is in reference to. For example, a value of `LISTING` specifies that the conversation is associated with a specific listing. The item ID associated with this listing will then be returned in the referenceId field. Currently, only `LISTING` will be returned. Occurrence: Conditional
conversations.unreadCount	integer	This value indicates the amount of unread messages in the conversation. Occurrence: Conditional
href	string	The URI to the current page of results. Occurrence: Always
limit	integer	The value of the limit parameter submitted in the request. Occurrence: Always
next	string	The URI for the next page of results. This value is returned if there is an additional page of results in the result set. Occurrence: Conditional
offset	integer	The value of the offset parameter submitted in the request. Occurrence: Always
prev	string	The URI for the previous page of results. This is retuned if there is a previous page of results in the result set. Occurrence: Conditional
total	integer	The total number of entries returned in the result set. Occurrence: Always

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

Status	Meaning
200	OK
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

Code	Domain	Category	Meaning
335000	API_MESSAGE	APPLICATION	Internal server error encountered. If this problem persists, contact the eBay Developers Program for support.
355001	API_MESSAGE	REQUEST	Invalid conversation_status value. Please see documentation for valid values.
355002	API_MESSAGE	REQUEST	Invalid conversation_type value. Please see documentation for valid values.
355003	API_MESSAGE	REQUEST	Invalid reference_type value. Please see documentation for valid values.
355004	API_MESSAGE	REQUEST	The start_time must be an earlier date than end_time.
355005	API_MESSAGE	REQUEST	Invalid date format used for one or both date filters. Please use ISO 8601 dates with UTC offset.
355006	API_MESSAGE	REQUEST	Invalid or unrecognized other_party_username value.
355008	API_MESSAGE	REQUEST	Invalid offset. The offset value must be a positive integer value and synchronized up with the limit value. If the limit value is 20, value offset values would be 0, 20, 40, etc.
355009	API_MESSAGE	REQUEST	Invalid limit. The limit value must be a positive integer value that does not exceed {maximumAllowedLimitNumber}
355016	API_MESSAGE	REQUEST	Invalid reference_id. The reference_id value must be a positive integer value.
355017	API_MESSAGE	REQUEST	The required conversation_type query parameter is either missing or has an invalid value. Please include this parameter and use a supported value.
355022	API_MESSAGE	REQUEST	The parameter reference_type is required whenever reference_id is provided.

Warnings

This call has no warnings.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Retrieve messages from all ACTIVE conversations

This method can be used to retrieve messages from all active conversations.

Input

The conversation_type of the conversations for which to retrieve messages is required as a path parameter for this method. In this sample, only conversations with the type FROM_MEMBERS will be returned. In addition, this sample only returns conversations that are active, as shown by the conversation_status query parameter.

GEThttps://api.ebay.com/commerce/message/v1/conversation?conversationType=FROM_MEMBERS&offset=0&limit=3&conversationStatus=ACTIVE

Output

If the call is successful, details about each active conversation from members, and the associated messages, are returned.

{
    "limit": 3,
    "offset": 0,
    "total": 3,
    "href": "http://localhost:9090/commerce/message/v1/conversation?conversationType=FROM_MEMBERS&offset=0&limit=3",
    "next": "http://localhost:9090/commerce/message/v1/conversation?conversationType=FROM_MEMBERS&offset=5&limit=3",
    "conversations": [
        {
            "conversationId": "5********2",
            "conversationStatus": "ACTIVE",
            "conversationType": "FROM_MEMBERS",
            "createdDate": "2025-10-07T21:15:04.000Z",
            "referenceId": "1********2",
            "referenceType": "LISTING",
            "unreadCount": 1,
            "latestMessage": {
                "messageId": "5********2",
                "messageBody": "Hi Seller, This is the start of the conversation!",
                "senderUsername": "p********2",
                "recipientUsername": "m********r",
                "readStatus": false,
                "createdDate": "2025-10-07T21:15:04.000Z"
            }
        },
        {
            "conversationId": "5********2",
            "conversationStatus": "ACTIVE",
            "conversationType": "FROM_MEMBERS",
            "createdDate": "2025-10-07T19:34:41.000Z",
            "referenceId": "1********9",
            "referenceType": "LISTING",
            "unreadCount": 0,
            "latestMessage": {
                "messageId": "5********2",
                "messageBody": "Hello, thank you for your message. Checking the new line fix. Things are looking good so far! Could you please give your car VIN number?",
                "senderUsername": "m********r",
                "recipientUsername": "p********2",
                "readStatus": true,
                "createdDate": "2025-10-07T19:34:41.000Z"
            }
        },
                 {
            "conversationId": "5********2",
            "conversationStatus": "ACTIVE",
            "conversationType": "FROM_MEMBERS",
            "createdDate": "2025-10-09T12:20:55.000Z",
            "referenceId": "1********2",
            "referenceType": "LISTING",
            "unreadCount": 0,
            "latestMessage": {
                "messageId": "5********2",
                "senderUsername": "m********r",
                "recipientUsername": "p********2",
                "readStatus": true,
                "createdDate": "2025-10-09T12:20:55.000Z",
                "messageMedia": [
                    {
                        "mediaName": "Screenshot 2025-03-25 at 5.37.58 PM.png",
                        "mediaUrl": "https://i.ebayimg.com/00/s/MTExMFgxNjAw/z/B2cAAeSwy7Fo56ii/$_1.PNG?set_id=880000500F",
                        "mediaType": "IMAGE"
                    }
                ]
            }
        }
    ]
}