Managing Messages in a Mercado Libre Claim

The management of messages within a Mercado Libre claim is crucial for efficiently handling communications between users and customer service regarding transaction issues. The primary goal is to provide quick and effective responses to users' concerns, offering solutions that address and resolve specific problems. This practice not only helps maintain customer satisfaction but also strengthens the quality of service on the platform, ensuring an optimal user experience and fostering trust in Mercado Libre.

Retrieve all messages of a claim

Messages in a claim constitute the main channel through which the involved parties express their requests and argue their positions. This form of communication is essential for a clear and effective exchange of information, facilitating an informed and fair resolution of disputes.

Call:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/marketplace/v2/claims/$CLAIM_ID/messages

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/v2/claims/5294629673/messages

Response:

 [
   {
       "sender_role": "complainant",
       "receiver_role": "respondent",
       "message": "No estoy de acuerdo\n",
       "translated_message": "I don't agree",
       "date_created": "2024-08-22T18:36:48.000-04:00",
       "last_updated": "2024-08-22T18:36:48.000-04:00",
       "message_date": "2024-08-22T18:36:48.000-04:00",
       "date_read": "2024-11-04T19:01:48Z",
       "attachments": [],
       "status": "available",
       "stage": "claim",
       "message_moderation": {
           "status": "clean",
           "reason": "",
           "source": "online",
           "date_moderated": "2024-08-22T22:36:47Z"
       },
       "repeated": false
   },
   {
       "sender_role": "respondent",
       "receiver_role": "complainant",
       "message": "Este es un mensaje de test del respondent al complainant",
       "translated_message": null,
       "date_created": "2024-08-22T18:21:20.000-04:00",
       "last_updated": "2024-08-22T18:21:20.000-04:00",
       "message_date": "2024-08-22T18:21:20.000-04:00",
       "date_read": "2024-08-22T22:21:21Z",
       "attachments": [
           {
               "filename": "1317418851_9efe5db7-1910-4184-932b-bb6279c15e37.jpg",
               "original_filename": "queja.jpg",
               "size": 16704,
               "date_created": "2024-08-22T18:21:19.000-04:00",
               "type": "image/jpeg"
           }
       ],
       "status": "available",
       "stage": "claim",
       "message_moderation": {
           "status": "clean",
           "reason": "",
           "source": "online",
           "date_moderated": "2024-08-22T22:21:19Z"
       },
       "repeated": false
   },
   {
       "sender_role": "complainant",
       "receiver_role": "respondent",
       "message": "imagen",
       "translated_message": "picture",
       "date_created": "2024-08-22T18:13:09.000-04:00",
       "last_updated": "2024-08-22T18:13:09.000-04:00",
       "message_date": "2024-08-22T18:13:09.000-04:00",
       "date_read": "2024-08-22T22:13:15Z",
       "attachments": [
           {
               "filename": "1517482146_31489bf8-95e3-4a2d-bcff-3c57771fb7c4.png",
               "original_filename": "Captura de pantalla 2024-08-22 a la(s) 4.12.28?p...m..png",
               "size": 166960,
               "date_created": "2024-08-22T18:13:09.000-04:00",
               "type": "image/png"
           }
       ],
       "status": "available",
       "stage": "claim",
       "message_moderation": {
           "status": "clean",
           "reason": "",
           "source": "online",
           "date_moderated": "2024-08-22T22:13:09Z"
       },
       "repeated": false
   },
   {
       "sender_role": "complainant",
       "receiver_role": "respondent",
       "message": "hola requiero una devolución test",
       "translated_message": "Hello I require a test return",
       "date_created": "2024-08-22T17:46:54.000-04:00",
       "last_updated": "2024-08-22T17:46:54.000-04:00",
       "message_date": "2024-08-22T17:46:54.000-04:00",
       "date_read": "2024-08-22T22:12:39Z",
       "attachments": [],
       "status": "available",
       "stage": "claim",
       "message_moderation": {
           "status": "clean",
           "reason": "",
           "source": "online",
           "date_moderated": "2024-08-22T21:46:54Z"
       },
       "repeated": false
   },
   {
       "sender_role": "complainant",
       "receiver_role": "respondent",
       "message": "Prueba test",
       "translated_message": "Prueba test",
       "date_created": "2024-08-22T17:31:37.000-04:00",
       "last_updated": "2024-08-22T17:31:37.000-04:00",
       "message_date": "2024-08-22T17:31:37.000-04:00",
       "date_read": "2024-08-22T21:32:21Z",
       "attachments": [],
       "status": "available",
       "stage": "claim",
       "message_moderation": {
           "status": "clean",
           "reason": "",
           "source": "online",
           "date_moderated": "2024-08-22T21:31:36Z"
       },
       "repeated": false
   }
]

Response Fields

A GET response to the /claims/$CLAIMS_ID/messages resource will provide the following parameters:

• sender_role: The player who sent the message:
  • complainant
  • respondent
• receiver_role: The player to whom the message is addressed:
  • complainant
  • respondent
• message: Message text
• translated_message: Message translation (only if the message requires translation: label CBT)
• date_created: Date when the message was created
• last_updated: Date of the last update
• message_date: Date when the message was sent
• date_read: Indicates the date when the message was read
• attachments: List of message attachments:
  • filename
  • original_filename
  • size
  • date_created
  • type
• status: Status of the message:
  • available
  • moderated
  • rejected
  • pending_translation
• stage: The stage in which the message was sent
• message_moderation: The result of the moderation process.
  • status: Possible values:
    • clean: The message is clean.
    • rejected: The message was moderated.
    • pending: Moderation is in progress.
    • non_moderated: Moderation was not applied, e.g., in older cases.
  • reason: Reason for moderating the message:
    • OUT_OF_PLACE_LANGUAGE: Inappropriate language.
  • source: Moderation modality. Possible values:
    • online: Moderation occurs during message creation. Currently, the only modality.
  • date_moderated: Date when moderation was performed.
• repeated

Replying to Messages and Attaching Files

Responding effectively and attaching relevant documentation allows for more efficient problem-solving, enhancing customer satisfaction and ensuring service quality. During a claim, all participants, except the warehouse_dispatcher player, have the opportunity to send at least one message.

Messages may include attachments. If a participant wishes to include an attachment in their message, they must first upload the file following the steps detailed in the "Uploading Attachments" section. Once uploaded, the user can use the filename generated by the Attachments API to incorporate it into their message, as illustrated in the provided examples.

This communication structure not only facilitates a smoother and more documented exchange of information but also optimizes the claim management process, allowing for quicker and more transparent resolution of disputes.

The POST should be performed asform.data with file = file location..

Users can exchange a variety of useful documents, such as photos, instruction manuals, and invoices, in JPG, PNG, and PDF formats, as long as they do not exceed 5 MB in size.

Additionally, the filename should be concise, not exceeding 125 characters, and should be composed of letters, numbers, periods, hyphens, and underscores (a-zA-Z0-9._-). These regulations ensure that file exchanges are carried out efficiently and organized, facilitating management and access to relevant information during the claim process.

Uploading Attachments

Files can be attached to messages by sending a POST request to the 'attachments' endpoint. This functionality enables the inclusion of relevant documentation directly into the conversation, allowing for more complete and effective communication during the claim resolution process.

Call:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 

{
 "file"=$FILE_PATH
}

https://api.mercadolibre/marketplace/v2/claims/$CLAIM/attachments

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 

{
 "file"=@/Users/user/Desktop/file.jpg
}

https://api.mercadolibre.com/marketplace/v2/claims/5294629673/attachments

Response:

{
   "user_id": 1317418851,
   "file_name": "9984c9c8-97da-4e85-860e-d016fbbe61fe.jpeg"
}

Create a Message with the Uploaded File

A player is enabled to send a message only if they have the 'send_message' action assigned to their profile. To verify if this action is available, the player must check the 'available_actions' in the Claim details. This structure ensures that only authorized participants can interact in the claim process, maintaining organization and communication efficiency.

The actions that allow sending messages to other claim participants vary depending on the claim's stage and current status. These actions are essential for facilitating effective and strategic communication between the involved parties, dynamically adapting to the specific needs and circumstances of each claim.

Actions:

Parameters:

Call:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 
{
 "receiver_role": "complainant| mediator| respondent",
 "message": "CLAIM MESSAGE",
 "attachments":  ["1317418851_9efe5db7-1910-4184-932b-bb6279c15e37.jpg" ]
}
https://api.mercadolibre.com/marketplace/v2/claims/$CLAIM_ID/actions/send-message

Attachment example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 
{
 "receiver_role": "complainant",
 "message": "This is a test message",
 "attachments":  ["1317418851_9efe5db7-1910-4184-932b-bb6279c15e37.jpg" ]
}

https://api.mercadolibre.com/marketplace/v2/claims/5294629673/actions/send-message

Response:

"status 201 created"

Example with no attachment:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 
{ 
 "receiver_role": "complainant",
 "message": "Prueba sin archivo",
 "attachments":  []
}

https://api.mercadolibre.com/marketplace/v2/claims/5294629673/actions/send-message

Response:

"status 201 created"

Download the file

Call:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/marketplace/v2/claims/$CLAIM_ID/attachments/$ATTACHMENTS_ID/download

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/5294629673/attachments/1517482146_31489bf8-95e3-4a2d-bcff-3c57771fb7c4.png/download

Get file information

Call:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/attachments/$ATTACHMENTS_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/5294629673/attachments/example.png

Response:

{
   "filename": "1517482146_31489bf8-95e3-4a2d-bcff-3c57771fb7c4.png",
   "original_filename": "Captura de pantalla 2024-08-22 a la(s) 4.12.28?p...m..png",
   "size": 166960,
   "date_created": "2024-08-22T18:13:09.000-04:00",
   "type": "image/png"
}

Next: Manage claim solutions