• API Docs
  • Post-sale messages
  • Pending messages
Last update 07/06/2022

Pending messages

Notifications flow

To work and consume the new (unread) messages from the integration, use /messages notifications to get the sales with new messages and do the GET directly on each one to bring the details of the received messages.


Messages pending reading

This option will allow you to obtain the pending messages to read in Mercado Libre of all the existing orders or only those specified. In addition, you can also define the role of the user for each case, either buyer or seller. To obtain the aforementioned information, you must perform the GET shown below. This resource is indicated for a redundancy use, only for validation if there were no losses in the integration from notifications.
Remember that when you check /messages/packs/pack_id/sellers/$seller_id the messages will be marked as read. In case you don't want to mark them as read, perform the GET with the mark_as_read = false parameter and the query will be: /messages/packs/pack_id/sellers/seller_id?mark_as_read=false.

Note:
This resource returns up to 1000 (thousand) conversations per request. In case you want to get more, you must mark some as read and make the same request again.

Request:

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

Response:

{
    "results": [
        {
            "resource": "/packs/123123123",
            "count": 1
        },
        {
            "resource": "/packs/1231234123",
            "count": 1
        }
    ],
    "userId": 29293123}

Optional parameter

- "role": "buyer"/"seller".


Response fields

user_id: ID of user who made request.
count: messages pending reading.
order_id: each available order.



Pending messages filtered by resource

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/messages/unread/$RESOURCE

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/messages/unread/packs/1234/sellers/2345

Response:

{
   "user_id":2345,
   "results":[
      {
         "resource":"/packs/1234/sellers/2345",
         "count":1
      }
   ]
}

Use modes

If you want to get all the orders with messages pending reading as seller, you will need to make this request:

curl -x GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/messages/unread?role=$ROLE&tag=post_sale

The possible values for ROLE are "buyer" or "seller".

Note:
For a better performance, it's recommended to declare the "role", but in case you do not specify a role or for a invalid role (different from "buyer" or "seller"), the resource will return as role=seller by default.

Response:

{
   "results": [
       {
           "resource": "/packs/12312312",
           "count": 1
       }
   ],
   "userId": 123123
}

Finally, if there are no messages pending reading for all the user's orders or specific user's orders, or if the user specifies within the “orders_id” parameter those orders that are not part of it, the response will be like this:

{
    "user_id": "1234512314",
    "results": []
}

Mark messages as read

With the following GET you can mark the messages as read.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/messages/packs/$PACK_ID/sellers/$SELLER_ID

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/messages/packs/2000000089077943/sellers/415458330

Response:

{
    "paging": {
        "limit": 2,
        "offset": 1,
        "total": 31
    },
    "conversation_status": {
        "path": "/packs/2000000089077943/seller/415458330",
        "status": "active",
        "substatus": null,
        "status_date": "2019-04-08T16:36:30.000Z",
        "status_update_allowed": false,
        "claim_id": null,
        "shipping_id": null
    },
    "messages": [
        {
            "id": "2c92808469fea23a0169febf14580001",
            "site_id": "MLM",
            "client_id": 123,
            "from": {
                "user_id": "415458330",
                "email": "test_user_83388960@testuser.com",
                "name": "Juan Pablo Robledo"
            },
            "status": "IN_MODERATION",
            "text": "Test message ToUserId",
            "message_date": {
                "received": "2019-04-08T20:58:49.000Z",
                "available": null,
                "notified": null,
                "created": "2019-04-08T20:58:49.000Z",
                "read": "2019-04-08T20:58:52.000Z"
            },
            "message_moderation": {
                "status": "NON_MODERATED",
                "reason": "none",
                "by": "none",
                "moderation_date": null
            },
            "message_attachments": [
                {
                    "filename": "415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d.pdf",
                    "original_filename": "Ayuda-Memoria-Arduino-ELINSI.pdf",
                    "type": "application/octet-stream",
                    "size": 225677,
                    "potential_security_threat": false,
                    "creation_date": "2019-04-08T20:58:49.000Z"
                }
            ],
            "message_resources": [
                {
                    "id": "2000000089077943",
                    "name": "packs"
                },
                {
                    "id": "415458330",
                    "name": "seller"
                }
            ]
        },
        {
            "id": "2c92808469fea23a0169febdb0570000",
            "site_id": "MLM",
            "client_id": 123,
            "from": {
                "user_id": "415458330",
                "email": "test_user_83388960@testuser.com",
                "name": "Juan Pablo Robledo"
            },
            "status": "IN_MODERATION",
            "text": "Test message ToUserId",
            "message_date": {
                "received": "2019-04-08T20:57:18.000Z",
                "available": null,
                "notified": null,
                "created": "2019-04-08T20:57:18.000Z",
                "read": "2019-04-08T20:57:22.000Z"
            },
            "message_moderation": {
                "status": "NON_MODERATED",
                "reason": "none",
                "by": "none",
                "moderation_date": null
            },
            "message_attachments": [
                {
                    "filename": "415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d.pdf",
                    "original_filename": "Ayuda-Memoria-Arduino-ELINSI.pdf",
                    "type": "application/octet-stream",
                    "size": 225677,
                    "potential_security_threat": false,
                    "creation_date": "2019-04-08T20:57:19.000Z"
                }
            ],
            "message_resources": [
                {
                    "id": "2000000089077943",
                    "name": "packs"
                },
                {
                    "id": "415458330",
                    "name": "seller"
                }
            ]
        }
    ]
}

Errors

Status Error Message
400 Messages id empty or invalid Messages id empty or invalid
400 The specified message id: a does not exists The specified message id: a does not exists
400 Not allowed messages from multiple orders Not allowed messages from multiple orders
404 The message with id: a could not be retrieved from storage The message with id: a could not be retrieved from storage

Next: Blocked messages.