Chat with Sellers

What you’ll learn

In this how to guide you’ll learn:

• What is the in-app chat feature
• Chat relationships & workflow
• The queries and mutations you can use to work with in-app chat

What is in-app chat?

In-app chat is a text-based communication tool on the Marketplacer platform, facilitating near real-time, company-to-company conversations between Operators and Sellers. This streamlined communication enhances issue resolution for partners within the Marketplacer ecosystem.

If you’re a Seller looking leverage the Seller API to chat with Operators, check out this article.

In-app chat is available in both the Operator or Seller portals, but can also be accessed via the Operator and Seller APIs. This guide focuses on how you can use the Operator API to chat with your sellers.

Chat Relationships & Workflow

Chat Relationships

A simplified view of the relationships between an Operator and Sellers using In-app Chat on a Marketplacer instance is shown below:

The takeaways from this are:

• An Operator can have multiple chat’s with different Sellers
• A Seller only has 1 chat with the Operator
• Sellers cannot chat with each other
• Chat messages are a single continuous thread between the Operator and Seller
• Irrespective of whether separate Operator API keys are used to generate chat messages on the same Marketplacer instance - those chat messages all appear in the same thread
• Irrespective of whether separate Seller API keys are used to generate chat messages under the same Seller Account - those chat messages all appear in the same thread
• Seller API keys use to generate chat messages under separate Seller Accounts will result in a separate chat thread for each

Chat Workflows

There are 3 basic workflows when using In-app chat:

1. Send new message workflow
2. Reply to a message workflow
3. Read message workflow

Send New Message Workflow

• sellersForChats fetch Sellers sorted by their latest chat message created date, (this included Sellers that do not have any chat messages).
• chatMessageCreate sends a message to the specified seller (using the Seller Id)

Reply to Message Workflow

• chatMessages fetch chat messages for a specific Seller
• chatMessageRead sets the readAt field on chat messages sent by a specific seller
• chatMessageCreate sends a reply message to the specified seller (using the Seller Id)

Read Message Workflow

• chatMessages fetch chat messages for a specific Seller
• chatMessageRead sets the readAt field on chat messages sent by a specific seller

Examples of these queries and mutations can be found below, as well as in our API Collections.

Query & Mutation Examples

sellersForChats

Fetch sellers sorted by their latest chat messages’ created timestamp

query FetchSellersForChat {
  sellersForChats(first: 10, after: null, q: "Cell Phone") {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    nodes {
      id
      businessName
    }
  }
}

In this example we fetch:

• The first 10 Sellers (we are not passing an after cursor), that have Cell Phones somewhere in their business name
• We also use pagination to determine if:
  • There is another page of data (hasNextPage)
  • If so, obtain the cursor we need to supply to our subsequent call (endCursor)

chatMessageSend

Create a chat message between operator and seller.

mutation SendMessgaeToSeller {
  chatMessageCreate(
    input: {
      message: "Can you check to see when order 12345 will be dispatched?"
      sellerId: "U2VsbGVyLTY2MDExOQ=="
    }
  ) {
    chatMessage {
      id
    }
    errors {
      field
      messages
    }
  }
}

In this mutation we:

• Provide a message we want to send to the Seller
• Identify the Seller we want to target by their ID
• Request the ID of the resulting Chat Message
• Request any errors associated with the mutation call

chatMessages

Fetches chat messages between Operator and a Seller

query GetChatMessages {
  chatMessages(first: 10, after: null, sellerId: "U2VsbGVyLTY2MDExOQ==") {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    nodes {
      id
      createdAt
      message
      readAt
      seller {
        businessName
      }
      sentByType
    }
  }
}

In this example we fetch:

• The first 10 Chat Messages (we are not passing an after cursor) for a Seller based on their ID
• We also use pagination to determine if:
  • There is another page of data (hasNextPage)
  • If so, obtain the cursor we need to supply to our subsequent call (endCursor)

chatMessageRead

Mark a chat message as read

mutation ConfirmReadOfChatMessage {
  chatMessageRead(input: { seller: "U2VsbGVyLTY2MDExOQ==", sentBy: "User" }) {
    errors {
      messages
      field
    }
  }
}

In this mutation we:

• Identify the Seller who’s chats we want to mark as being read
• Supply the user class (sentBy)
• Request any errors associated with the mutation call