API Reference

Link to swagger documentation

This page covers general information about the Message Center API, including error handling, standards and business logic.

Error Handling
Standards
Appendix

Error Handling

The API uses standard HTTP status codes to indicate whether a request was successful or failed.

401 Unauthorized: Your HMAC signature is invalid or missing. Please check the authentication headers.
404 Not Found: The requested resource (e.g., a Chat or Order) could not be found.
422 Unprocessable Entity: The request Body is invalid. The response will contain details about the validation errors.

Example 422 Validation Error:

{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "message": [
      "The message field is required."
    ]
  }
}

Standards

Request and response format: All API requests and responses are expected to use the JSON format, except in cases where multipart/form-data is explicitly required (e.g., for file uploads).
URL encoding: All URLs must be properly encoded to ensure safe and accurate transmission of parameters.
Date and time format: All date and time values follow the RFC 3339 standard, e.g., 2019-10-12T07:20:50.52+00:00.

Appendix

Automatic ‘Mark as Seen’ Behavior

When a Seller interacts with Chat’s Messages, any unread messages from the BUYER within that Chat are automatically marked as read/seen.
This behavior includes the following actions:

In both cases, the seenAt field for all messages where senderUserType is BUYER and seenAt is null will be updated to the current timestamp.
Additionally, the Chat’s isSeen field will be set to true.

Chat Business Rules

A Chat is unique for each organization.id, order.id, and category.id combination.
Sellers and Buyers are notified by email when new unread messages are available.
Sellers are also notified by email when a Chat reaches OVER_SLA status.

CLOSED Status Flow

A Chat can transition to CLOSED in two ways:
1. The BUYER manually sets the Chat as resolved (CLOSED).
2. The system automatically sets the Chat to CLOSED after 72 hours of inactivity.
When a reply is sent to a CLOSED Chat, the Chat reopens and its status changes to WAITING_FOR_BUYER or WAITING_FOR_SELLER, depending on the senderUserType. If no further reply is sent, the system automatically sets the Chat to CLOSED again after another 72 hours of inactivity.