Customer Care Integration Guide
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.
Term | Definition |
---|---|
Conversation | The container of a set of Customer Care messages, including the Consumer Message(s) and Response Message(s). |
Consumer Message | A specific inquiry or complaint from an end consumer, received by a retailer that a supplier must respond to. |
Response Message | A supplier-provided response that the Dsco platform will send to the retailer so the retailer may share the response with the end consumer. |
Retailer | The demand side of the relationship that owns the end consumer relationship and receives feedback from the consumer. |
Seller | When in a marketplace relationship, this is the supply side of the relationship that sells on the retailer's marketplace. Note that the term supplier is often used in place of seller in this guide for clarity with API attribute names. |
Supplier | The supply side of the relationship that is meant to respond to end consumer feedback. |
Conversation Status | Suppliers are expected to close conversations to indicate they have responded to the consumer and consider the matter closed. |
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 itsConsumer Message
to the retailer. - Retailer -> Dsco
The retailer forwards thisConsumer Message
to Dsco. - Dsco -> Supplier
Dsco shares thisConsumer Message
with the supplier. - Supplier -> Dsco
The supplier provides theResponse Message
to the end consumer to Dsco. - Dsco -> Retailer
Dsco makes the supplier'sResponse 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 itsConsumer Message
to the retailer. - Retailer -> Dsco
The retailer creates a new Conversation and adds aConsumer Message
in Dsco. The conversation's status isin_progress
. - Dsco -> Supplier
Dsco gets the Conversation and itsConsumer Message
and notifies the supplier of the new message. - Supplier -> Dsco
The supplier adds aResponse Message
to the conversation in question and later changes the conversation's status toClosed
when done. - Dsco -> Retailer
The retailer calls in to get any new Customer Care conversation messages and the supplier'sResponse 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.
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.
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..."
}