Send a message

Learn how to use the Messaging API to make an application that lets a seller send a message to a buyer.

Prerequisites

To complete this tutorial, you need:

• Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API applications.
• The Buyer Communication role role assigned to your developer profile.
• The Buyer Communication role role selected in the app registration page for your application.

Step 1. Get the order for which the seller wants to send a message

1. Display a list of the seller's recent orders that the seller can choose from.

2. The seller chooses an order for which they want to send a message to the buyer.

3. Associate an Amazon order identifier with the order that the seller chooses.

4. 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.

Path Parameter:

Query Parameter:

2. 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 the title 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).

3. Save the list of paths in the _links.actions array of the response. The href 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

1. 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.

2. 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.

1. 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.

2. Let the seller input the raw text that they want for their custom message.

3. 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 the getMessagingActionsForOrder operation in Step 2. Get a list of available message types.

4. 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.

1. 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.

2. Let the seller upload an attachment to your application.

3. 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 the getMessagingActionsForOrder operation in Step 2. Get a list of available message types.

4. Convert the attachment into an input stream and save it for Step 8. Upload the attachment.

5. Let the seller input a file name for the attachment, including the file extension.

6. 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.

1. 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.

2. Save the md5Content value to pass in with the Content-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 createUploadDestinationForResource operation of the Uploads API to create an upload destination for your attachment, in the form of an Amazon S3 presigned URL.

Query parameters:

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 the UploadFileToDestination 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 the UploadFileToDestination 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 the UploadFileToDestination 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.

Path parameter:

Query Parameter:

Body Parameter:

There is no response. Instead, Amazon emails the seller's message to the buyer.