sendMessage: eBay Message API | eBay Developers Program

POST/send_message

This method can be used to start a conversation with another user or send a message in an existing conversation with another user based on the information provided in the request.

To send a message, one of the conversationId or otherPartyUsername request fields are required. The conversationId must be used when sending a message in an existing conversation and specifies the conversation for which to send the message. For a new conversation, the otherPartyUsername field must be used to send the message to a specific user. In addition, the messageText field is required as it contains the body text of the message.

Optionally, media (such as images or documents) can be attached to the message using the messageMedia container. The reference container can also be used to associate a message with a listing.

Input

Resource URI

POST https://api.ebay.com/commerce/message/v1/send_message

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

This method has no URI parameters.

HTTP request headers

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

The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.

Header	Type	Description
Content-Type	string	This header indicates the format of the request body provided by the client. Its value should be set to application/json. For more information, refer to HTTP request headers. Occurrence: Required

Header

Type

Description

Content-Type

string

This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.

Occurrence: Required

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

Copy complete valid JSON to clipboard

{ /* SendMessageRequest */

"conversationId" : "string",

"emailCopyToSender" : "boolean",

"messageMedia" : [

{ /* MessageMedia */

"mediaName" : "string",

"mediaType" : "string",

"mediaUrl" : "string"

}

"messageText" : "string",

"otherPartyUsername" : "string",

"reference" :

{ /* Reference */

"referenceId" : "string",

"referenceType" : "string"

}

Request fields

Input container/field	Type	Description
conversationId	string	This field specifies the unique identifier of the conversation in which to send the message. Use the getConversations method to retrieve conversation ID values. This field is required if sending a message in an existing conversation. Occurrence: Conditional
emailCopyToSender	boolean	This boolean indicates whether a copy of the message should be emailed to the sender. If this boolean is input as `true`, a copy of the message will be emailed to the sender. Occurrence: Optional
messageMedia	array of MessageMedia	This array lists the individual forms of media, if any, to be attached to the message. Up to five individual forms of media may be be sent per message. If more than five are specified in this array, an error will occur and the call will fail. Occurrence: Optional
messageMedia.mediaName	string	The name of the media attached to the message. Occurrence: Conditional
messageMedia.mediaType	string	The type of media attached to the message. Valid values: `IMAGE` `PDF` `DOC` `TXT` Occurrence: Conditional
messageMedia.mediaUrl	string	The URL of the self-hosted media attached to the message. URLs must use the "HTTPS" protocol. Occurrence: Conditional
messageText	string	The text of the message. Max length: 2000 characters Occurrence: Required
otherPartyUsername	string	This field specifies the eBay username of the entity for which to send the message. This field is required if starting a new conversation with another eBay user. Occurrence: Conditional
reference	Reference	This container should be used if the new or existing conversation is related to a specific eBay listing. For example, a referenceType of `LISTING` and an associated referenceId will specify the item ID value of the listing associated with the message. Occurrence: Optional
reference.referenceId	string	This value indicates the reference ID associated with the corresponding referenceType value. For example, in the case of a `LISTING` reference type, this value will be the item ID value of the listing. Occurrence: Conditional
reference.referenceType	string	This value indicates the reference type to associate 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` is supported. Occurrence: Conditional

Output

HTTP response headers

This call has no response headers.

Response payload

Copy complete valid JSON to clipboard

{ /* SendMessageResponse */

"createdDate" : "string",

"messageBody" : "string",

"messageId" : "string",

"messageMedia" : [

{ /* MessageMedia */

"mediaName" : "string",

"mediaType" : "string",

"mediaUrl" : "string"

}

"readStatus" : "boolean",

"recipientUserName" : "string",

"senderUserName" : "string",

"subject" : "string"

}

Response fields

Output container/field	Type	Description
createdDate	string	The date, in ISO 8601 format, the message was sent. Occurrence: Always
messageBody	string	The message text. Occurrence: Always
messageId	string	The unique identifier of the message. Occurrence: Always
messageMedia	array of MessageMedia	This array will be returned if the user attached one or more images or documents to the message. Occurrence: Conditional
messageMedia.mediaName	string	The name of the media attached to the message. Occurrence: Conditional
messageMedia.mediaType	string	The type of media attached to the message. Valid values: `IMAGE` `PDF` `DOC` `TXT` Occurrence: Conditional
messageMedia.mediaUrl	string	The URL of the self-hosted media attached to the message. URLs must use the "HTTPS" protocol. Occurrence: Conditional
readStatus	boolean	The read status of the message. If returned as `true`, the message has been read by the recipient. Occurrence: Always
recipientUserName	string	The eBay username of the recipient. Occurrence: Always
senderUserName	string	The eBay username of the sender. Occurrence: Always
subject	string	The subject line of the message. Occurrence: Conditional

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
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
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.
355003	API_MESSAGE	REQUEST	Invalid referenceType value. Please see documentation for valid values.
355006	API_MESSAGE	REQUEST	Invalid or unrecognized otherPartyUsername value.
355007	API_MESSAGE	REQUEST	Invalid or unrecognized conversation_id value.
355010	API_MESSAGE	REQUEST	The maximum amount of media that may be sent is {maximumMediaAllowedCount}. Please reduce the number of media in the messageMedia array to {maximumMediaAllowedCount} and try again.
355011	API_MESSAGE	REQUEST	Invalid mediaType value. Please see documentation for valid values.
355012	API_MESSAGE	REQUEST	All fields under messageMedia are required. Please add missing field(s).
355013	API_MESSAGE	REQUEST	The messageText string exceeds the maximum character threshold of {maximumMessageTextAllowedLength}. Please modify the message text to meet this requirement.
355014	API_MESSAGE	REQUEST	Invalid mediaUrl. Please see documentation.
355015	API_MESSAGE	REQUEST	Please pass message text or upload one of more media attachments.
355016	API_MESSAGE	REQUEST	Invalid referenceId. The referenceId value must be a positive integer value.
355018	API_MESSAGE	REQUEST	conversationId and otherPartyUsername cannot both be empty.
355020	API_MESSAGE	REQUEST	The referenceId is invalid, no listing can be found by this referenceId.
355021	API_MESSAGE	REQUEST	All fields under reference are required. Please add missing field(s).

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: Send a message in an existing conversation

Sample 2: Send a message and start a new conversation

Sample 1: Send a message in an existing conversation

This method can be used to send a message to a user (or in an existing conversation).

Input

To send a message, either a conversationId or otherPartyUsername request field is required, as well as the messageText of the message.

In this sample, the message is being sent in an existing conversation, so the conversationId field is used. An image is also being attached to the message, as shown in the messageMedias container. Finally, the message is referencing a listing (as shown by the included references container), with the item ID of the referenced listing being specified in the referenceID field.

POSThttps://api.ebay.com/commerce/message/v1/conversation/send_message

Output

If the call is successful, a response body will be returned showing details of the message, such as the messageId value.

Sample 2: Send a message and start a new conversation

This method can be used to send a message to a user (or in an existing conversation).

Input

To send a message, either a conversationId or otherPartyUsername request field is required, as well as the messageText of the message.

In this sample, the message is being sent in a new conversation, so the otherPartyUsername field is used. An image is also being attached to the message, as shown in the messageMedias container. Finally, the message is referencing a listing (as shown by the included references container), with the item ID of the referenced listing being specified in the referenceID field.

POSThttps://api.ebay.com/commerce/message/v1/conversation/send_message

Output

If the call is successful, a response body will be returned showing details of the message, such as the messageId value.