Post-sale messages management

Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.

Last update 21/12/2022

Post-sale messages

The messaging API resource will enable you to get messages from a specific order, create new messages in the system, and send or receive attachments.

Parameters

from: message sender.
user_id: user id who sent message.
to: message recipient.
user_id: user id who received message.
text: message text.
attachments: attached files.
site_id: Mercado Libre México, Brazil, Colombia, Chile (MLM, MLB, MCO, MLC) site.

Get messages by pack

To get the messages of a particular pack you must make a request associating the pack_id and the user_id, corresponding to the seller of the package, with the resource /marketplace/messages. Remember messages moderated by the counterpart will not be visible and the messages themselves will be visible.

Request:

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

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/messages/packs/2315686468?limit=2&offset=1

Response:

{
  "paging": {
    "limit": 1,
    "offset": 0,
    "total": 1
  },
  "conversation_status": {
    "claim_ids": null,
    "shipping_id": null,
    "status": "active",
    "status_date": "2020-02-26T17:37:42Z",
    "status_update_allowed": false,
    "substatus": null
  },
  "messages": [{
    "id": "2d45a5ad186041659e9a608f0c109dff",
    "site_id": "MLM",
    "client_id": 1344270061107690,
    "from": {
      "user_id": 523132944,
      "name": "TESTNICOCBT TESTNICOCBT"
    },
    "to": {
      "user_id": 441782523,
      "name": "Test Test"
    },
    "status": "available",
    "subject": null,
    "text": "This a message to buyer",
    "message_date": {
      "received": "2020-03-13T15:14:10Z",
      "available": "2020-03-13T15:14:10Z",
      "notified": null,
      "created": "2020-03-13T15:14:10Z",
      "read": null
    },
    "message_moderation": {
      "status": "clean",
      "reason": null,
      "source": "online",
      "moderation_date": "2020-03-13T15:14:10Z"
    },
    "message_attachments": [{
        "filename": "471826944_ba20cdf4-26b4-4c21-a689-5eabe271ddb3.png",
        "original_filename": "FileName.png",
        "type": "image/png",
        "size": 536766,
        "potential_security_threat": false,
        "creation_date": "2020-03-13T15:14:10Z"
      },
      {
        "filename": "523130418_10f6b123-5ec2-44dc-b611-e347098331a2.png",
        "original_filename": "FileName.png",
        "type": "image/png",
        "size": 536766,
        "potential_security_threat": false,
        "creation_date": "2020-03-13T15:14:10Z"
      }
    ],
    "message_resources": [{
        "id": "2315686468",
        "name": "packs"
      },
      {
        "id": "523132944",
        "name": "sellers"
      }
    ],
    "conversation_first_message": false,
    "text_translated": "Este es un mensaje para el comprador"
  }]
}

Note:

Remember that the time zone for these dates is UTC.

Get message by ID

To know the messages associated with a pack, you must make a query to the resource /marketplace/messages.

Request:

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

{
    "paging": null,
    "conversation_status": null,
    "messages": [
        {
            "id": "testmessage1123456",
            "site_id": "MLM",
            "client_id": 818828848883,
            "from": {
                "user_id": "1234567",
                "name": ""
            },
            "to": {
                "user_id": "7654321",
                "name": ""
            },
            "status": "available",
            "subject": null,
            "text": "",
            "message_date": {
                "received": "2021-09-26T04:48:25Z",
                "available": "2021-09-26T04:48:25Z",
                "notified": "2021-09-26T04:48:25.000Z",
                "created": "2021-09-26T04:48:25Z",
                "read": null
            },
            "message_moderation": {
                "status": "clean",
                "reason": null,
                "source": "online",
                "moderation_date": "2021-09-26T04:48:25Z"
            },
            "message_attachments": null,
            "message_resources": [
                {
                    "id": "2000002725708674",
                    "name": "packs"
                },
                {
                    "id": "534272725",
                    "name": "sellers"
                }
            ],
            "conversation_first_message": false,
            "text_translated": "Este es un mensaje de prueba"
        }
    ]
}

Save message and attach file

Important:

As of August 12, it will be mandatory to send the site_id parameter to indicate the account´s site to add attachment.

To attach a file in the message, you need to save it first. Then, when the attachment is sent, the file id is returned as response. The site_id parameter must be added to indicate in which account you want to add the attachment.
Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/messages/attachments?site_id=$SITE_ID

Notes:

- The POST needs to be made form.data with key: value > file = reference to file (that is, the file itself).
- The file needs to have a maximum 25 MB size.
- You can exchange pictures, instruction manuals, invoices, and any other attachments of up to 25 MB in JPG, PNG, PDF and TXT format.
- The allowed Mime Types of files are:
text/plain
image/png
image/jpeg
image/heif
image/heic
application/pdf
application/msword
application/vnd.ms-excel
text/xml,application/xml
application/octet-stream
If you want to upload any that are not listed, the API will return an HTTP Status Code 400.

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/messages/attachments?site_id=MLM
  -H 'content-type: multipart/form-data;' \
  -F 'file=@/home/user/.../Adjunto.jpg'

In this case, the server will respond with a JSON containing file id in case of a successful request.

Note:

The response obtained should be attached to the intended message.

Response:

{
  "id": "210438685_59f0f034-db1b-4ea6-8c5e-1d34e2092482.jpg"
}

Create messages for a buyer

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/marketplace/messages/packs/$ORDER_ID

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST http://api.mercadolibre.com/marketplace/messages/packs/2315686468
  -H 'content-type: application/json' \
  -d '{
    "text": "More test message",
    "text_translated": "",
    "attachments": [
        "471826944_ba20cdf4-26b4-4c21-a689-5eabe271ddb3.png",
        "523130418_10f6b123-5ec2-44dc-b611-e347098331a2.png"
    ]
}

Notes:

- The attachments attribute is obtained from the attachment POST response. Learn more how upload and save attachment.
- If you don't need to attach a file, you can remove the "attachments" section in the JSON.
- If you want to create a message with the buyer language, use the “text_translated” field.
- If you need to insert a link that can be clicked, you can do so using the href function. For example: "<a href="your_url"> Your tracking link </a>".

Get attachment

To get an attached message, you need to make a GET.
Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/messages/attachments/$ATTCHMENT_ID?tag=post_sale&site_id=SITE_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/messages/attachments/76601286_5946e4c4-168a-45fd-945e-b8f0c306c58d.png?tag=post_sale&site_id=MLA

Response:
If the request is successful, the call will return the requested file. In case the file cannot be accessed, the server response will be the following:

{
    "message": "File can not be accessed, try it later",
    "error": null,
    "status": 500,
    "cause": []
}

In case the access token is not sent, the message will be:

{
    "message": "Access token is required",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Errors

Error code	Message	Solution
400	Attachment empty or null	Please, attach file valid
	File name cannot include characters such as: /, \	Remove characters like: / ,
	File size exceeds 25 Mb	Reduce the file attachment over 25 Mb
	Message exceeds allowed number of attachments: 25	Reduce number of attachments over 25
	You are not allowed to execute the option OTHER again	Quantity (cap) not available
	Messages id empty or invalid	Send a message id valid
	The specified message id: a does not exists	Send a effective message id
	Not allowed messages from multiple orders	Send message IDs that correspond to order
	The limit param must be greater than 0.	Request “limit” param must be greater than 0
	Invalid offset or limit param	Use a offset or limit param valid
403	User access token invalid for resource {resource_id}	Use an access token valid
404	The message with id: a could not be retrieved from storage	Message not found in the server, try again in a few seconds
500	Requested file could not be obtained	File can not be accessed, try it later
	File can not be saved, try it later.	Problems when saving file

Next: Working with claims.