Messaging API v1 Use Case Guide
Message buyers about their orders.
What is the Messaging API?
With the Selling Partner API for Messaging (Messaging API), you can build applications that let sellers send messages to buyers after they place an order. Sellers can send a variety of message types. These include asking order related questions, arranging a delivery, requesting the removal of negative feedback, and more. The Messaging API can send messages to a buyer even if the buyer has not contacted the seller first. You cannot use this API to respond to messages from buyers.
Refer to the Messaging API reference for a list of operations that correspond to the available message types.
Terminology
Amazon S3 presigned URL: A URL for an Amazon S3 bucket to which you can upload an object without AWS security credentials or permissions. You get an Amazon S3 presigned URL in Step 7. Create an upload destination.
Message availability
Not all message types are available in all circumstances. There are a number of factors that can affect message availability, including whether the order has been fulfilled, the type of seller, or the number of messages already sent for the order.
Workflow for sending a message
The following is for the user of the application. Sending a message is a multi-step process that includes calls to operations in both the Messaging API and the Uploads API. Here is the basic workflow for sending a message:
-
Your application displays the seller's recent orders, and the seller chooses an order for which they want to send a message to the buyer.
-
Your application displays the message types that are available for the order that the seller chooses. Get the available message types by calling the
getMessagingActionsForOrder
operation of the Messaging API. -
The seller chooses a message type for the order.
-
If custom messages are supported for the message type, the seller inputs a custom message.
-
If attachments are supported for the message type, the seller uploads an attachment to your application. The seller also inputs a file name for the attachment.
-
If the seller uploads an attachment to your application, your application uploads the attachment to an Amazon S3 bucket by doing the following:
-
Calculating a Content-MD5 hash for the attachment, which is needed for creating an upload destination.
-
Creating an upload destination by calling the
createUploadDestination
operation of the Uploads API. -
Uploading the attachment to the destination.
-
-
Your application requests that a message be sent from the seller to the buyer by calling the operation that corresponds to the message type that the seller chose in step #3. For example, your application calls the
createConfirmOrderDetails
operation if the seller chose the "Confirm order details" message type. -
Amazon emails a message from the seller to the buyer. Refer to Tutorial: Send a message for the detailed workflow.
Tutorial: Send a message
This tutorial teaches you how to make an application that lets a seller send a message to a buyer.
Prerequisites
To complete this tutorial, you need:
-
Authorization from the seller for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
-
Buyer Communication role approval in your developer profile.
-
The Buyer Communication role selected in the App registration page for your application.
Step 1. Get the order for which the seller wants to send a message
-
Display a list of the seller's recent orders that the seller can choose from.
-
The seller chooses an order for which they want to send a message to the buyer.
-
Associate an Amazon order identifier with the order that the seller chooses.
-
Save the Amazon order identifier for Step 2. Get a list of available message types.
Step 2. Get a list of available message types
Call the getMessagingActionsForOrder
operation of the Messaging API, specifying the Amazon order identifier from
Step 1. Get the order for which the seller wants to send a message to get a list of message types that are available for the order.
- Call the
getMessagingActionsForOrder
operation of the Messaging API, passing the following parameters:
Path Parameter:
Parameter | Description | Required |
---|---|---|
amazonOrderId
|
An Amazon order identifier. This specifies the order for which a message is to be sent. Get this value from Step 1. Get the order for which the seller wants to send a message.
Type: string |
Yes |
Query Parameter:
Parameter | Description | Required |
---|---|---|
marketplaceIds
|
A marketplace identifier. This specifies the marketplace in which the order was placed. You can specify only one marketplace.
Type: array[string] |
Yes |
Request example
GET https://sellingpartnerapi-na.amazon.com/messaging/v1/orders/902-6786204-8179805?marketplaceIds=ATVPDKIKX0DER
Response
The response schema for the getMessagingActionsForOrder
operation.
Name | Description | Schema |
---|---|---|
_links optional | An object whose property names are link relation types, and values are either a Link Object or an array of Link Objects. The subject resource of these links is the Resource Object, of which the containing "_links" object is a property. | _links |
_embedded optional | An object whose property names are link relation types and values are either a Resource Object or an array of Resource Objects. Embedded Resources can be a full, partial, or inconsistent version of the representation served from the target URI. | _embedded |
errors optional | A list of error responses returned when a request is unsuccessful. | ErrorList |
_links
Name | Description | Schema |
---|---|---|
self required | Corresponds with the IANA registered 'self' relation whose target is the resource's URI. | LinkObject |
actions required | Eligible actions for the specified amazonOrderId. | < LinkObject > array |
Name | Schema |
---|---|
actions required | < GetMessagingActionResponse > array |
Response example
{
"_links":
{
"actions": [
{
"href": "/messaging/v1/orders/902-6786204-
8179805/messages/confirmCustomizationDetails?marketplaceIds=ATVPDKIKX0
DER",
"name": "confirmCustomizationDetails"
},
{
"href": "/messaging/v1/orders/902-6786204-
8179805/messages/negativeFeedbackRemoval?marketplaceIds=ATVPDKIKX0DER"
,
"name": "negativeFeedbackRemoval"
},
{
"href": "/messaging/v1/orders/902-6786204-
8179805/messages/confirmOrderDetails?marketplaceIds=ATVPDKIKX0DER",
"name": "confirmOrderDetails"
},
],
"self":
{
"href": "/messaging/v1/orders/902-6786204-
8179805?marketplaceIds=ATVPDKIKX0DER"
}
},
"_embedded":
{
"actions": [
{
"_links":
{
"schema":
{
"href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmCustomizationDetails/schema",
"name": "confirmCustomizationDetails"
},
"self":
{
"href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmCustomizationDetails?marketplaceIds=ATVPDKIKX0DER",
"name": "confirmCustomizationDetails"
}
},
"_embedded":
{
"schema":
{
"_links":
{
"self":
{
"href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmCustomizationDetails/schema",
"name": "confirmCustomizationDetails"
}
},
"type": "object",
"name": "confirmCustomizationDetails",
"title": "Confirm customization details",
"description": "Ask your customer to provide details or verify the customization input provided (name spelling, imagery, initials).",
"properties":
{
"attachments":
{
"type": "array",
"items":
{
"type": "object",
"required": [],
"properties":
{
"fileName":
{
"type": "string"
},
"id":
{
"type": "string"
}
}
},
"title": "Add attachment",
"description": "You can upload text files, PDFs, Word documents, and these image file types: .jpg, .gif, and .png. The total size of attachments must be less than 10 MB.",
"x-ui-field-type": "attachments",
"maxItems": 5
},
"rawMessageBody":
{
"type": "string",
"title": "Explain why you are contacting and any action you need your customer to take. ",
"description": "800 character limit. Only links related to order completion are allowed, no HTML or email addresses.",
"x-ui-field-type": "text",
"minLength": 1,
"maxLength": 800
}
},
"required": [
"attachments",
"rawMessageBody"
],
"$schema": "http://json-schema.org/draft-04/schema#",
"x-ui-hidden": null
}
},
"name": "confirmCustomizationDetails",
"title": "Confirm customization details"
},
{
"_links":
{
"schema":
{
"href": "/messaging/v1/orders/902-6786204-8179805/messages/negativeFeedbackRemoval/schema",
"name": "negativeFeedbackRemoval"
},
"self":
{
"href": "/messaging/v1/orders/902-6786204-8179805/messages/negativeFeedbackRemoval?marketplaceIds=ATVPDKIKX0DER",
"name": "negativeFeedbackRemoval"
}
},
"_embedded":
{
"schema":
{
"_links":
{
"self":
{
"href": "/messaging/v1/orders/902-6786204-8179805/messages/negativeFeedbackRemoval/schema",
"name": "negativeFeedbackRemoval"
}
},
"type": "object",
"name": "negativeFeedbackRemoval",
"title": "Request to update negative feedback",
"description": "Ask your customer to consider updating their seller feedback rating. You may only send this once per order.",
"properties": {},
"required": [],
"$schema": "http://json-schema.org/draft-04/schema#",
"x-ui-hidden": true
}
},
"name": "negativeFeedbackRemoval",
"title": "Request to update negative feedback"
},
{
"_links":
{
"schema":
{
"href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmOrderDetails/schema",
"name": "confirmOrderDetails"
},
"self":
{
"href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmOrderDetails?marketplaceIds=ATVPDKIKX0DER",
"name": "confirmOrderDetails"
}
},
"_embedded":
{
"schema":
{
"_links":
{
"self":
{
"href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmOrderDetails/schema",
"name": "confirmOrderDetails"
}
},
"type": "object",
"name": "confirmOrderDetails",
"title": "Confirm order details",
"description": "Ask your customer a specific order-related question prior to shipping their order.",
"properties":
{
"rawMessageBody":
{
"type": "string",
"title": "Explain why you are contacting and any action you need your customer to take. ",
"description": "2000 character limit. Only links related to order completion are allowed, no HTML or email addresses.",
"x-ui-field-type": "text",
"minLength": 1,
"maxLength": 2000
}
},
"required": [
"rawMessageBody"
],
"$schema": "http://json-schema.org/draft-04/schema#",
"x-ui-hidden": null
}
},
"name": "confirmOrderDetails",
"title": "Confirm order details"
},
]
}
}
-
Save the list of schemas in the
_embedded.actions
array of the response. In the_embedded.schema
section of each array element you can find a schema for each available message type. Use thetitle
value in each schema to create a list of available message types for the seller to choose from in Step 3. Get the seller's choice of message type. Use the schemas to understand how to display and enforce the restrictions for custom messages and attachments that apply for each message type. For more information, refer to Step 4. Get custom message text from the seller (if supported) and Step 5. Get an attachment from the seller (if supported). -
Save the list of paths in the
_links.actions
array of the response. Thehref
value in each array element contains a path for each available message type. You can use one of these paths in a call for the appropriate operation in Step 9. Send a message to the buyer.
Step 3. Get the seller's choice of message type
-
Display a list of available message types for the seller to choose from. Get these from the
title
values that you saved in Step 2. Get a list of available message types. -
Let the seller choose the message type that they want send, and save it. This choice will affect several subsequent steps, including:
-
Step 4. Get custom message text from the seller (if supported). The choice of message type determines whether a custom message is supported.
-
Step 5. Get an attachment from the seller (if supported). The choice of message type determines whether attachments are supported.
-
Step 9. Send a message to the buyer. The choice of message type determines which operation you will call in Step 9. For example if the seller chooses the "Confirm customization details" message type, you will call the
confirmCustomizationDetails
operation in Step 9.
-
Step 4. Get custom message text from the seller (if supported)
Some message types permit the seller to include a custom message in the email to the buyer. To find out if a message type supports custom messages, review the Messaging API reference to find the operation that corresponds to the message type. For example, the createConfirmServiceDetails
operation corresponds to the "Contact Home Service customer" message type. If the operation includes a text body parameter, the message type supports custom messages.
-
Determine if the message type that the seller chose in Step 3. Get the seller's choice of message type supports custom messages. If custom messages are not supported, go directly to Step 5. Get an attachment from the seller (if supported). If custom messages are supported, continue with this procedure.
-
Let the seller input the raw text that they want for their custom message.
-
Display and enforce any restrictions on the message text that the seller inputs. You can find the text restrictions in the
_embedded.schema.properties.rawMessageBody
section of the_embedded.actions
array element that corresponds to the seller's message type. Find this in the response for thegetMessagingActionsForOrder
operation in Step 2. Get a list of available message types. -
Save the message text and use it as input for Step 9. Send a message to the buyer.
Step 5. Get an attachment from the seller (if supported)
Some message types permit the seller to include a link to an attachment in the email to the buyer. To find out if a message type supports attachments, review the Messaging API reference to find the operation that corresponds to the message type. For example, the createWarranty
operation corresponds to the "Send Warranty Information" message type. If the operation includes an attachments body parameter, the message type supports attachments.
-
Determine if the message type that the seller chose in Step 3. Get the seller's choice of message type supports attachments. If attachments are not supported, go directly to Step 9. Send a message to the buyer. If attachments are supported, continue with this procedure.
-
Let the seller upload an attachment to your application.
-
Display and enforce any restrictions on the attachment that the seller uploads. You can find the attachment restrictions in the
_embedded.schema.properties.attachments
section of the_embedded.actions
array element that corresponds to the seller's message type. Find this in the response for thegetMessagingActionsForOrder
operation in Step 2. Get a list of available message types. -
Convert the attachment into an input stream and save it for Step 8. Upload the attachment.
-
Let the seller input a file name for the attachment, including the file extension.
-
Save the file name and use it as input for Step 9. Send a message to the buyer.
Step 6. Calculate a Content-MD5 hash
Calculate a Content-MD5 hash for the attachment from Step 5. Get an attachment from the seller(if supported). You will need it to create an upload destination in Step 7. Create an upload destination.
The Java sample code in this step contains logic for calculating a Content-MD5 hash. This sample code uses the Apache HTTP client.
- Use the following as input for the sample code:
The attachment input stream from Step 5. Get an attachment from the seller (if supported), is the argument for the fis
parameter of the computeContentMD5Value
method of the CreateMD5
class.
- Save the
md5Content
value to pass in with theContent-MD5
parameter in Step 7. Create an upload destination.
Sample Java code
package io.swagger.client.util;
import java.io.FileInputStream;
import java.io.IOException;
import java.security.DigestInputStream;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
public class CreateMD5
{
public static String computeContentMD5Value(FileInputStream fis)
throws IOException,
NoSuchAlgorithmException
{
DigestInputStream dis = new DigestInputStream(fis,
MessageDigest.getInstance("MD5"));
byte[]buffer = new byte[8192];
while (dis.read(buffer) > 0);
String md5Content = new String(org.apache.commons.codec.binary.Base64
.encodeBase64(dis.getMessageDigest().digest()));
// Effectively resets the stream to be beginning of the file
// via a FileChannel.
fis.getChannel().position(0);
return md5Content;
}
}
Step 7. Create an upload destination
Call the createUploadDestination
operation of the Uploads API to create an upload destination for your attachment, in the form of an Amazon S3 presigned URL. For definitions, refer to Terminology.
- Call the
createUploadDestination
operation of the Uploads API, passing the following parameters:
Query parameters:
Type | Name | Description | Schema |
---|---|---|---|
Query | marketplaceIds required | A list of marketplace identifiers. This specifies the marketplaces where the upload will be available. Only one marketplace can be specified. Max count : 1 | < string > array |
Query | contentMD5 required | The Content-MD5 hash that you calculated in Step 6. Calculate a Content MD5 hash. | string |
Path | resource required | The resource for the upload destination that you are creating. For example, if you are creating an upload destination for the createLegalDisclosure operation of the Messaging API, the {resource} would be /messaging/v1/orders/{amazonOrderId}/messages/legalDisclosure , and the entire path would be /uploads/2020-11-01/uploadDestinations/messaging/v1/orders/{amazonOrderId}/messages/legalDisclosure . If you are creating an upload destination for an Aplus content document, the {resource} would be aplus/2020-11-01/contentDocuments and the path would be /uploads/v1/uploadDestinations/aplus/2020-11-01/contentDocuments . | string |
Query | contentType optional | The content type of the file to be uploaded. | string |
Request example
POST https://sellingpartnerapi-na.amazon.com/uploads/2020-11-01/uploadDestinations/messaging/v1/orders/7XX-5XXXXX-8XXXXXX/messages/invoice?marketplaceIds=A2Q3Y263D00KWC&contentMD5=qCcR3o%2BU0FUR1%2BgXhApNfQ%3D%3D
Response
The response schema for the createUploadDestination
operation.
Name | Description | Schema |
---|---|---|
payload optional | Information about an upload destination. | UploadDestination |
errors optional | A list of error responses returned when a request is unsuccessful. | ErrorList |
Response example
{
"payload":
{
"uploadDestinationId": "sc/7ae2d3b1-fdd3-42c4-98c4-9cc509fb95d8.png",
"url": "https://aplus-media.s3.amazonaws.com/?x-amz-date=20201116T184623Z&x-amz-signature=c5c8efd95d883b6787a2b1a93c7c066f01cb4e8d7be3ece4360aa800332e0cf9&x-amz-meta-owner=A2CZ04NGKYDXDV&acl=private&key=sc/7ae2d3b1-fdd3-42c4-98c4-9cc509fb95d8.png&x-amz-algorithm=AWS4-HMAC-SHA256&policy=eyJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJhcGx1cy1tZWRpYS1iZXRhIn0seyJrZXkiOiJzb3RhLzdhZTJkM2IxLWZkZDMtNDJjNC05OGM0LTljYzUwOWZiOTVkOC5wbmcifSx7ImFjbCI6InByaXZhdGUifSx7IngtYW16LW1ldGEtb3duZXIiOiJBMkNaMDROR0tZRFhEViJ9LHsieC1hbXotYWxnb3JpdGhtIjoiQVdTNC1ITUFDLVNIQTI1NiJ9LHsieC1hbXotY3JlZGVudGlhbCI6IkFLSUE2TDZSN1FFNTZGNkdNRzVFLzIwMjAxMTE2L3VzLWVhc3QtMS9zMy9hd3M0X3JlcXVlc3QifSx7IngtYW16LWRhdGUiOiIyMDIwMTExNlQxODQ2MjNaIn0sWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMSwzMTQ1NzI4XV0sImV4cGlyYXRpb24iOiIyMDIwLTExLTE2VDIxOjQ2OjIzLjg2OFoifQ==&x-amz-credential=AKIA6L6R7QE56F6GMG5E/20201116/us-east-1/s3/aws4_request",
"headers":
{
"Content-MD5": "1jnGuPv7xwPiat6NesKL/w=="
}
}
}
- Save the following values:
- url and headers. Use these values in Step 8. Upload the attachment.
uploadDestinationId
. Use this value in Step 9. Send a message to the buyer.
Step 8. Upload the attachment
Upload to an Amazon S3 bucket the attachment that the seller uploaded to your application in Step 5. Get an attachment from the seller (if supported).
The Java sample code in this step contains logic for uploading an attachment. This sample code uses the Apache HTTP client.
Use the following as input to the sample code:
-
Use the url value that you saved in Step 7. Create an upload destination as the argument for
URL(uploadDestinationPayload.getPayload().getUrl())
in theUploadFileToDestination
class. -
Use the headers value that you saved in Step 7. Create an upload destination as input for
(Map < String, String > )uploadDestinationPayload.getPayload().getHeaders()
in theUploadFileToDestination
class. -
Use the attachment input stream that you saved in Step 4. Get custom message text from the seller (if supported) and use it as input for the
out.write()
method of theUploadFileToDestination
class.
Sample Java code
package io.swagger.client.util;
import java.io.IOException;
import java.io.OutputStreamWriter;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Map;
import io.swagger.client.model.CreateUploadDestinationResponse;
public class UploadFileToDestination
{
private static String requestMethod = "PUT";
private static String contentType = "Content-Type";
private static String contentValue = "application/text";
private static URL url;
private static Map < String,
String > headers;
/* Upload file to destination using the response returned in
CreateUploadDestination. Reference https://docs.aws.amazon.com/AmazonS3/latest/dev/PresignedUrlUploadObjectJavaSDK.html)
*/
public static void uploadFileInDestination(
CreateUploadDestinationResponse uploadDestinationPayload)
throws IOException
{
url = new URL(uploadDestinationPayload.getPayload().getUrl());
headers = (Map < String, String > )uploadDestinationPayload.getPayload()
.getHeaders();
// Create the connection and use it to upload the new object using the
// pre-signed URL.
HttpURLConnection connection = (HttpURLConnection)url.openConnection();
connection.setDoOutput(true);
connection.setRequestMethod(requestMethod);
connection.setRequestProperty(contentType, contentValue);
// headers that are returned in createDestination call
for (Map.Entry < String, String > headersEntry: headers.entrySet())
{
connection.setRequestProperty(headersEntry.getKey(),
headersEntry.getValue());
}
OutputStreamWriter out = new OutputStreamWriter(
connection.getOutputStream());
out.write("Text of the file");
out.close();
// Check the HTTP response code. To complete the upload and make the
// object available,
// you must interact with the connection object in some way.
connection.getResponseCode();
System.out.println("HTTP response code: " + connection.getResponseCode()
+ connection.getResponseMessage());
connection.disconnect();
}
}
The attachment is uploaded to the Amazon S3 bucket.
Step 9. Send a message to the buyer
To send a message from the seller to the buyer you need to call the operation that corresponds to the message type that the seller chose in Step 2. Get a list of available message types. For example, if the seller chose the "Confirm customization details" message type, you would call the confirmCustomizationDetails
operation. Refer to the Messaging API reference for the list of operations that are available. In this example, we will call the confirmCustomizationDetails
operation.
- Call the
confirmCustomizationDetails
operation of the Messaging API, passing the following parameters:
Path parameter:
Parameter | Description | Required |
---|---|---|
amazonOrderId
|
An Amazon order identifier. This specifies the order for which a message is to be sent. Use the Amazon order identifier that you saved in Step 1. Get the order for which the seller wants to send a message.
Type: string |
Yes |
Query Parameter:
Parameter | Description | Required |
---|---|---|
marketplaceIds
|
A marketplace identifier. This specifies the marketplace in which the order was placed. You can specify only one marketplace.
Type: array[string] |
Yes |
Body Parameter:
Parameter | Description | Required |
---|---|---|
text
|
The custom message to be included in the email to the buyer. Use the message text from Step 4. Get custom message text from the seller (if supported).
Type: string |
Yes |
attachments
|
Attachments to include in the message to the buyer
|
Yes |
Request example
GET https://sellingpartnerapi-na.amazon.com/messaging/v1/orders/902-6786204-8179805/messages/confirmCustomizationDetails?marketplaceIds=ATVPDKIKX0DER
{
"text": "This is the message from the seller to the buyer that will appear in the email to the buyer.",
"attachments": [
{
"uploadDestinationId": "4370d51b-2954-445c-9f30-EXAMPLE6b9de",
"fileName": "example.txt"
}
]
}
Response
There is no response. Instead, Amazon emails the seller's message to the buyer.
Updated about 1 month ago