Implement shopper-customer chat

Learn how to populate a chat window on a retailer-designed order status page. Use a polling strategy to retrieve messages from the shopper while shopping is in progress. You will also try sending a customer message to the shopper and marking messages as read.

You can try out this tutorial in your development environment.

1. Before you begin
2. Simulate shopping
3. Send a message from the shopper
4. Retrieve messages
5. Send a message to the shopper
6. Mark messages as read
7. Summary

Before you begin

We recommend that you complete the Implement order status tutorial to learn about how orders are managed before trying this tutorial.

For this tutorial, you need the following items:

• An order. For instructions on how to create a delivery order, see Implement delivery.
• The user access token that you generated for the customer's order status page. This is different than the client credentials access token you used to create the order.
• The base URL of your assigned Instacart development server.

Variables used in this tutorial

The following variables are used in requests in this tutorial. When you see a variable, substitute them with values that work in your development environment.

Variable	Description
<instacart_development_domain>	The domain of your assigned Instacart development server.
<token>	The user access token that was generated for this order using the encoded user ID.
<order_id>	The order ID from the order that you created before you started this tutorial.
<order_item_id>	The item ID that has a replacement item suggested.
<shopper_id>	The ID for a fictitious shopper that you create. This is generated during the tutorial.
<batch_id>	The ID for a batch that contains the order. This is generated during the tutorial.

The responses in this tutorial show sample values in place of the variables. The responses that are returned in your environment should have a similar format to the example responses. If you are interested in other possible responses including errors, see the API documentation.

Simulate shopping

In a production environment, a shopper uses the Instacart Shopper app while picking items. The chat is active while shopping is in progress. For this tutorial, we'll start by simulating a shopper shopping.

Use Sandbox API to complete the following tasks:

• Create a shopper
• Generate a batch assigned to the shopper
• Advance the batch to picking

Create a shopper

In the request, substitute your values for the variables <instacart_development_domain>, <token>, <shopper_email>, <shopper_phone>, and <shopper_password>.

curl --request POST \
  --url 'https://<instacart_development_domain>/v2/fulfillment_sandbox/shoppers' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'
  --data '{
    "email": "<shopper_email>",
    "phone": "<shopper_phone>",
    "password": "<shopper_password>"
  }'

The response contains the generated shopper ID.

{
  "id": 23728249
}

For details about this Sandbox API endpoint, see Create a shopper.

Generate a batch

An order must be batched before it can be shopped. Create a batch that contains the order and assign it to the shopper you just created.

note

The user ID is not required, but because of the way that orders are stored, the response is faster if you include the <external_user_id> in the request. Omit it if you don’t have it.

In the following request, substitute your values for the variables <instacart_development_domain> and <token>. In the request body, specify the generated <shopper_id>, the <order_id>, and optionally the <external_user_id>.

curl --request POST \
  --url 'https://<instacart_development_domain>/v2/fulfillment_sandbox/batches' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "batch_type": "delivery",
    "shopper_id": <shopper_id>,
    "orders": [
        {
            "id": "<order_id>",
            "user_id": "<external_user_id>"
        }
      ]
   }'

The response contains the batch ID.

{
  "id": 656178546
}

For details about this Sandbox API endpoint, see Generate a batch.

Advance the batch to picking

With the batch assigned to a shopper, you are now able to set the status of the batch. The batch starts in the status of acknowledged. We'll change the status from acknowledged to picking. The picking status means that the shopper has started shopping for the items in the order.

In the request, substitute your values for the variables <instacart_development_domain>, <batch_id>, and <token>. Set the workflow state to picking.

curl --request POST \
  --url 'https://<instacart_development_domain>/v2/fulfillment_sandbox/batches/<batch_id>/advance' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "workflow_state": "picking"
  }'

The response contains the batch ID and the status of the batch.

{
  "id": 656178546,
  "workflow_state": "picking"
}

For details about this Sandbox API endpoint, see Advance batch.

Send a message from the shopper

To send a shopper message from the simulated shopper, contact your Instacart representative. They can log in as your fictitious shopper and send a message within the context of the development environment.

Retrieve messages

Retrieve shopper and customer messages from the chat service. The entire conversation is retrieved each time you call this endpoint.

Start polling this endpoint when the shopper starts picking items. Send this request at whatever frequency you prefer. Stop polling the endpoint when the shopper is ready to checkout and the order workflow state transitions to checkout.

In the request, substitute your values for the variables <instacart_development_domain>, <order_id>, and <token>.

curl --request GET \
  --url 'https://<instacart_development_domain>/v2/post_checkout/chat/<order_id>/messages' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

The response contains an array of messages. In this example, there is only one message and the IDs are fictitious. When the read status is false, the customer has not yet read the chat message.

{
  "chat_messages": [
    {
      "id": 123,
      "order_id": 123456,
      "created_at": "2021-07-09T17:24:12Z",
      "recipient_id": "",
      "recipient_type": "",
      "sender_id": "",
      "sender_type": "",
      "read": false,
      "read_at": "2021-07-09T17:24:12Z",
      "body": "Hi, this is Zelma, your shopper. I'm just getting started on your shopping list.",
      "image": ""
    }
  ],
  "metadata": {
    "customer": {
      "id": 789012,
      "display_name": "Sierra"
    },
    "shoppers": [
      {
        "id": 23728249,
        "display_name": "Zelma",
        "avatar_url": "http://example.com"
      }
    ]
  }
}

Send a message to the shopper

After shopping starts, a customer can initiate chat or respond to a chat message from their shopper. Get the customer's message text and/or image from your UI component and send it to the shopper.

In the request, substitute your values for the variables <instacart_development_domain>, <order_id>, and <token>. Add content of the message in the request body. You can send text or an image or both in the request.

curl --request POST \
  --url 'https://<instacart_development_domain>/v2/post_checkout/chat/<order_id>/messages' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
      "body": "Hi, this is Sierra.",
      "image_url": ""
    }'

The response contains the ID that was generated for this message.

{
  "id": 123,
  "type": "CHAT",
  "created_at": "2021-01-01T05:00:00Z",
  "timezone": "Timezone"
}

Mark messages as read

If your chat window captures when the customer reads a shopper message, you can mark the message as read in the chat service.

Send the following request each time a message is read. Substitute your values for the variables <instacart_development_domain>, <order_id>, and <token>.

curl --request PUT \
  --url 'https://<instacart_development_domain>/v2/post_checkout/chat/<order_id>/messages' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json'

All unread shopper messages are marked as read.

{
  "messages_read_count": 1
}

Summary

In this tutorial, we started by simulating a shopper shopping for a customer's order. We retrieved a test message from the shopper, and then we covered how to send a customer message to that shopper. Finally, we marked all messages in the conversation as read.