Customer Care Integration Guide

• Overview
• Terms
• The Flow
• Approach: The Conversation
• API Details
  • Retailer Creates a Customer Care Conversation
  • Supplier Gets Customer Care Messages
  • Supplier responds to Customer Care Messages

Overview

Rithum's Dsco platform supports a retailer sharing direct feedback from an end consumer with a supplier who is meant to respond to the feedback. This workflow is typically used in a marketplace-like relationship between a retailer and a "seller." Here, we will use the term supplier to mean the entity who is acting as a seller in the retailer's marketplace.

The Dsco platform does the heavy lifting to make it easier for retailers and suppliers to trade in both a traditional dropship relationship and also a marketplace relationship with as little change as possible on the platform and as such there is nothing that ties the Customer Care workflow described here to a marketplace relationship per se.

Terms

Below are terms used throughout this guide.

The Flow

A retailer receives a Consumer Message that is direct feedback from an end consumer, perhaps an order is late and the end consumer is frustrated or perhaps an end consumer received the ordered product and is dissatisfied somehow. The retailer needs to get that end consumer message to the supplier. The supplier needs to get that consumer message and respond to it with a message of its own. That message response needs to get back to the retailer so the retailer may share it with the end consumer. Here's the flow...

• End Consumer -> Retailer
  The end consumer sends its Consumer Message to the retailer.
• Retailer -> Dsco
  The retailer forwards this Consumer Message to Dsco.
• Dsco -> Supplier
  Dsco shares this Consumer Message with the supplier.
• Supplier -> Dsco
  The supplier provides the Response Message to the end consumer to Dsco.
• Dsco -> Retailer
  Dsco makes the supplier's Response Message available to the retailer who will then get it to the end consumer.

Approach: The Conversation

The messages that flow back and forth in the flow described above need a container. That container is called a conversation. A conversation has a Conversation Status that lets both the retailer and the supplier know whether the supplier has responded to the Consumer Message with a Response Message. Here's the flow now in the context of a Conversation container.

• End Consumer -> Retailer
  The end consumer sends its Consumer Message to the retailer.
• Retailer -> Dsco
  The retailer creates a new Conversation and adds a Consumer Message in Dsco. The conversation's status is in_progress.
• Dsco -> Supplier
  Dsco gets the Conversation and its Consumer Message and notifies the supplier of the new message.
• Supplier -> Dsco
  The supplier adds a Response Message to the conversation in question and later changes the conversation's status to Closed when done.
• Dsco -> Retailer
  The retailer calls in to get any new Customer Care conversation messages and the supplier's Response Message is found and the retailer forwards it along to the end consumer.

Why did the Dsco platform call the container for these Customer Care messages a Conversation? The answer is a container was needed for these messages and a back and forth set of messages is a conversation. Also, this allowed Dsco to create a general purpose messaging platform that allows retailers and suppliers to have back and forth messages around various contexts, not just around Customer Care.

API Details

Retailer Creates a Customer Care Conversation

A retailer creates a new Conversation and marks it as a Customer Care conversation, specifying the order the end consumer feedback relates to, and includes the Consumer Message originating from the end consumer.

Create Conversation API

Note that the context object is necessary to specify the order that the feedback is for. The supplier associated with the order will be the one who receives the feedback and is expected to handle it. The retailer may optionally designate which item on the order the feedback revolves around if desired by including lineItem in the context.

Also note that the retailer designates the messages in the conversation that came from the end consumer by marking them with originatesFromExternal.

Sample Create Conversation Request Body

{
  "otherPartyTradingPartnerId": "aaa-bbb-ccc",
  "title": "Late order complaint from end consumer on Order 123",
  "type": {
    "type": "customer_care",
    "consumerId": "12345"
  }
  "context": {
    "type": "order",
    "poNumber": "123-456-789",
  },
  "initialMessage": {
    "message": "Why is my order late?",
  },
}

The conversation will be created and then shared with the supplier designted by dscoSupplierTradingPartnerId who must be the same supplier associated with the order specified in the context.

Supplier Gets Customer Care Messages

Assuming the supplier uses APIs to respond to Customer Care messages and not another method, the supplier will periodically poll for new Customer Care messages.

Get Conversation Messages API

Let's say the supplier checks for new Customer Care messages every 30 minutes. Let's say that the current day/time is 2023:05:01T10:00:00.0000Z and that the supplier last checked for new messages at 2023:05:01T9:29:55.0000Z. The supplier will make the following call to get any outstanding messages since the last time they called in. (Remember, the API instructs not to leave 5 seconds between now and when you search up until just to be on the safe side with eventual consistency.)

Sample Get Conversation Messages Request Body

{
  "type": {"type": "customer_care"},
  "createdSince": "2023:05:01T9:29:55.0000Z",
  "until": "2023:05:01T09:59:55.0000Z"
}

Let's assume there are some thousands of these messages and that a scrollId was returned from the API. Here's the request to get the next page of results.

Sample Get Conversation Messages Request Body to Get Next Page

{
  "scrollId": "asdf09a8sfa0s98fas098df0s98f0s98fsfs8safsfs987fs98f7s98f7s908f7s"
}

Supplier responds to Customer Care Messages

Again, assuming the supplier uses APIs to respond to Customer Care messages and not another method, the supplier will call the Add Customer Message API to send the Response Message back to the retailer. The messages received in the Get Conversation Messages API call made above each include the dscoConversationId that is needed to add a message to the conversation. Optionally, if the caller has added a reference ID to the conversation, the message may be added using the reference ID to identify the conversation the message should be added to.

Add Message to Conversation API

Sample Add Message to Conversation Request Body

Note that response_to_consumer is requisite so that Dsco knows that this message is meant to be a response Dsco routes back through the retailer to the end consumer. Also note that dscoConversationId was provided in the message when the supplier retrieved it in the previous API call described above.

{
  "dscoConversationId": "sfs09fsf09s8fsfs9009",
  "message": "We're sorry that your order is late.  Your options are..."
}