Messaging after sale

The messing API resource will enable you to get messages from a specific order, create new messages in the system, and send or receive attachments.
Let’s see how you can use it!

Contents:

Parameters description

message_id Message id
date_created Date of creation
date Date a message is saved
date_received Date a message is received
date_availableDate a message went through moderation
date_notified Date a message was notified to counterparty
date_read Date a message was read by counterparty

from A message sender
user_id Id of user who sent message
email Email of user who sent message (order secure email)
name Name of user who sent message

to A message recipient
user_id Id of user who received message
email Email of user who received message (order secure email)

subject Email subject
text Message text
plain Message plain text

attachments Attached files
attachments_validations Attachment validation
invalid_size If attachment size is invalid
invalid_extension Invalid attachment extension
internal_error Internal error

site_id Mercado Libre (MLA, MLB, etc.) site
resource Corresponding to order it pertains to (orders)
resource_id Order ID
status Message status
moderation_status Message moderation status

Get messages

To get messages from a specific order, you should associate the order_id with this resource via GET.

Call:

GET ".../messages/orders/$order_id"

Example:

 curl -X GET “https://api.mercadolibre.com/messages/orders/{resource_id}?access_token=$ACCESS_TOKEN”

Possible extra parameters:

These parameters can be used to determine the number of messages recovered by GET.

&limit={límite} >> positive integer

Example:

curl -X GET “https://api.mercadolibre.com/messages/orders/{order_id}?access_token=$ACCESS_TOKEN&limit=10”

&offset={compensación} >> positive integer

Example:

curl -X GET “https://api.mercadolibre.com/messages/orders/{order_id}?access_token=$ACCESS_TOKEN&limit=10&offset=1”

Response:

{
    "paging": {
        "limit": 2,
        "offset": 1,
        "total": 270
    },
    "results": [
        {
            "_id": "43b450d6bd3f47fb94394041b26c519f",
            "message_id": "43b450d6bd3f47fb94394041b26c519f",
            "date_received": "2016-11-07T15:03:14.978Z",
            "date": "2016-11-07T15:03:14.978Z",
            "date_available": "2016-11-07T15:03:14.978Z",
            "date_notified": "2016-11-07T15:05:50.179Z",
            "date_read": "2016-11-08T22:43:17.767Z",
            "from": {
                "user_id": "76601286",
                "email": "mailfrom.3fd70y+2-ogeytenjqgi3tombx@mail.mercadolibre.com",
                "name": null
            },
            "to": [
                {
                    "user_id": "106459677",
                    "email": "mailto.lj36rj8+2-ogeytenjqgi3tomjw@test.mercadolibre.com"
                }
            ],
            "subject": null,
            "text": {
                "plain": "Mensaje de pruebas desde api publica con attachment. Multiples 'to' "
            },
            "attachments": [
                {
                    "size": "103584",
                    "type": "image/png",
                    "date": "Tue, 25 Oct 2016 22:56:47 GMT",
                    "filename": "76601286_51a2e39b-7ff6-48ef-85f8-3025676db43e.png",
                    "original_filename": "Captura de pantalla 2016-10-20 a las 2.26.09 p.m..png"
                }
            ],
            "attachments_validations": null,
            "headers": null,
            "site_id": "MLA",
            "resource": "orders",
            "resource_id": "1125027671",
            "status": "available",
            "moderation_status": "non_moderated",
            "moderation": {
                "status": "non_moderated"
            },
            "client_id": 1000
        },
        {
            "_id": "37befd545a2d436f89e672b33990ef8b",
            "message_id": "37befd545a2d436f89e672b33990ef8b",
            "date_received": "2016-11-07T14:56:02.500Z",
            "date": "2016-11-07T14:56:02.500Z",
            "date_available": "2016-11-07T14:56:02.500Z",
            "date_notified": "2016-11-07T14:57:46.659Z",
            "date_read": "2016-11-07T15:19:08.967Z",
            "from": {
                "user_id": "76601286",
                "email": "mailfrom.3fd70y+2-ogeytenjqgi3tombx@mail.mercadolibre.com",
                "name": null
            },
            "to": [
                {
                    "user_id": "106459677",
                    "email": "mailto.lj36rj8+2-ogeytenjqgi3tomjw@test.mercadolibre.com"
                }
            ],
            "subject": null,
            "text": {
                "plain": "Mensaje de pruebas desde api publica con attachment. Multiples 'to' "
            },
            "attachments": [
                {
                    "size": "103584",
                    "type": "image/png",
                    "date": "Tue, 25 Oct 2016 22:56:47 GMT",
                    "filename": "76601286_51a2e39b-7ff6-48ef-85f8-3025676db43e.png",
                    "original_filename": "Captura de pantalla 2016-10-20 a las 2.26.09 p.m..png"
                }
            ],
            "attachments_validations": null,
            "headers": null,
            "site_id": "MLA",
            "resource": "orders",
            "resource_id": "1125027671",
            "status": "available",
            "moderation_status": "non_moderated",
            "moderation": {
                "status": "non_moderated"
            },
            "client_id": 1000
        }
    ]
}

Notes:

  • Per each sale from a buyer you will get a different masked email. That is, if the same buyer purchases you two different products at different times, each sale will generate an email.
  • The buyer’s contact mails will be viewed masked so the number of characters (between 55 and 60) will increase.

Get messages by ID

Request:

GET “https://api.mercadolibre.com/messages/{message_id}?access_token=$ACCESS_TOKEN”

Response Example:

{
  "message_id": "0033b582a1474fa98c02d229abcec43c",
  "date_received": "2016-09-01T05:15:25.821Z",
  "date": "2016-09-01T05:15:25.821Z",
  "date_available": "2016-09-01T05:15:25.821Z",
  "date_notified": "2016-09-01T05:17:42.945Z",
  "date_read": "2016-09-01T21:31:19.606Z",
  "from": {
    "user_id": "123456789",
    "email": "userfrom.n4tx9d+2-ogeytenjqgi3tomjw@mail.mercadolibre.com",
    "name": "User from"
  },
  "to": [
    {
      "user_id": "123456780",
      "email": "userto.3fd70y+2-ogeytenjqgi3tombx@mail.mercadolibre.com"
    }
  ],
  "subject": "Test Item subject",
  "text": {
    "plain": "Ejemplo de texto"
  },
  "attachments": [
    {}
  ],
  "attachments_validations": {
    "invalid_size": [
    ],
    "invalid_extension": [
    ],
    "forbidden": [
    ],
    "internal_error": [
    ]
  },
  "site_id": "MLA",
  "resource": "orders",
  "resource_id": "1234567871",
  "status": "available",
  "moderation": {
    "status": "non_moderated"
  }
}

Create messages

In case of from seller, order seller.id will go in from.user_id.

Call:

POST “https://api.mercadolibre.com/messages?access_token=$ACCESS_TOKEN&application_id=$APPLICATION_ID” 

Note: The “application_id” is only required when the Access Token does not have the APP ID embedded.

Example:

curl -i -X POST -H "Content-Type: application/json" -H “X-Client-Id: {application id}” -d
'{
    "from": {
        "user_id": 123435,
    },
    "to": [
        {
            "user_id": 9191923,
            "resource": "orders",
            "resource_id": 2223213,
            "site_id": "MLA"
        }
    ],
    "text": {
        "plain": "Plain text message here"
    }
}’ https://api.mercadolibre.com/messages?access_token=$ACCESS_TOKEN&application_id=$APPLICATION_ID

Note: The attachments attribute is obtained from the attachment POST response. (See attachments section).

Send 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.

Call:

POST “https://api.mercadolibre.com/messages/attachments?access_token=$ACCESS_TOKEN”

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.

Example:

curl-i-XPOST-H"Content-Type: multipart/form-data"-F"file=@/home/user/file""https://api.mercadolibre.com/messages/attachments?access_token=$ACCESS_TOKEN"

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"
}

Get attachment

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

Call:

GET “https://api.mercadolibre.com/messages/attachments/{attachment_id}?access_token=$ACCESS_TOKEN” 

Example:

https://api.mercadolibre.com/messages/attachments/76601286_5946e4c4-168a-45fd-945e-b8f0c306c58d.png?access_token=$ACCESS_TOKEN

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": []
}



To conclude, following all these steps, the POST will be like this…

Example:

{
    "from": {
      "user_id": 123455677
    },
    "to": [
        {
            "user_id": 72345286,
            "resource": "orders",
            "resource_id": 1234567671,
            "site_id": "MLA"
        }
    ],
    "text": {
      "plain" : "Mensaje de pruebas"
    },
  	"attachments" : ["76602286_52a2e39b-7ff6-48ef-85f8-3025676db43a.png" ]


}

Response:

[
    {
        "message_id": "d2345e6e7bb844469ae79623018223af",
        "date_received": "2016-11-14T20:46:49.678Z",
        "date": "2016-11-14T20:46:49.678Z",
        "date_available": "2016-11-14T20:46:49.678Z",
        "date_notified": null,
        "date_read": null,
        "from": {
            "user_id": "123455677",
            "email": "userseller.n4tx9d+2-ogeytenjqgi3tomjw@mail.mercadolibre.com",
            "name": null
        },
        "to": [
            {
                "user_id": "72345286",
                "email": "userbuyer.3fd70y+2-ogeytenjqgi3tombx@mail.mercadolibre.com"
            }
        ],
        "subject": null,
        "text": {
            "plain": "Mensaje de pruebas"
        },
        "attachments": [
            {
                "size": "103584",
                "type": "image/png",
                "date": "Tue, 25 Oct 2016 22:56:47 GMT",
                "filename": "76602286_52a2e39b-7ff6-48ef-85f8-3025676db43a.png",
                "original_filename": "Captura de pantalla 2016-10-20 a las 2.26.09 p.m..png"
            }
        ],
        "attachments_validations": null,
        "site_id": "MLA",
        "resource": "orders",
        "resource_id": "1125027671",
        "status": "available",
        "moderation": {
            "status": "non_moderated"
        }
    }
]

Messages pending reading

This option will let you get in Mercado Libre messages pending reading from all the existing orders or just specific orders.

You can also define the user role in each case, whether buyer or seller.

To obtain the above mentioned information, make a GET as shown below.

Call:

GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN

(Optional) Parameters:

To receive a list of specific orders, send comma separated IDs (…&orders_id=id1,id2,…,):
orders_id=$ORDERS_ID

In turn, to receive the user role in an order, Buyer example: …&role=buyer – Seller example: …&role=seller), you will need to do it with the following parameter: role=$ROLE

Use mode

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

No role:

CURL -X GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN

Clarification: If no role is specified or if it is invalid (other than “buyer” or “seller”), the resource will take the “seller” role by default.

With role:

CURL -X GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN&role=seller

To get all the orders with messages pending reading as buyer, you will need to make this call:

CURL -X GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN&role=buyer

If you want to get the number of messages pending reading for the orders, you will need to do this:

CURL -X GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN&orders_id=123,124,125

Response:
If the API response is satisfactory, you will get a JSON like this:

{
    "user_id": "1234512314",
    "results": [
        {
            "order_id": "19912312312”
            "count": 1
        }
    ]
}

In this response, you will see:

  • ID of user who made request (“user_id”).
  • Messages pending reading (“count”).
  • Each available order (“order_id”).

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": []
}

Note: This is a private resource, so if you make a call without access_token, you will get error 400.

Request without access token:

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

Mark messages as read

With this PUT call, you can mark messages as read in Mercado Libre providing the IDs you want to read in the URL.

Note: Messages should be separated by comma (,); otherwise, they will not be recognized as different messages.

Call:

PUT /messages/mark_as_read/:messages_id

Example:

https://api.mercadolibre.com/messages/mark_as_read/id1,id2,id3?access_token=$ACCESS_TOKEN

Response:

{
    "message": "Messages marked as read successfully",
    "status": 200
}

Review blocked messages

In order to reduce spam and unnecessary messages, messages can be blocked within post sale messaging because:

  • The buyer has blocked message delivery.
  • After a period of time, message delivery is automatically blocked.

Via API you can find them under the “Blocked” status in a new section called “conversation”:

Call:

https://api.mercadolibre.com/messages/orders/{resource_id}?access_token=$ACCESS_TOKEN

Response:

{
  "paging": {...},
  "results": [{...},{...}],
  "conversation": {
"status": "blocked",
"substatus": "blocked_by_buyer",
      "status_date": "2017-05-26T13:17:23.511-04:00"
   }
}

status: This field allows two values:

  • active: conversation is open for sending/receiving messages
  • – substatus: null

  • blocked: conversation is closed to sending/receiving messages
  • – substatus: Blocked_by_time: Conversation has been blocked automatically after a period of time.
    – substatus: Blocked_by_buyer: Conversation has been blocked due to buyer request.

status_date: Represents the date when conversation status was recorded.

Possible errors

Common errors

Request without access token:

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

Errors to get message by id

User is denied access to a certain message:

{
  "message": "Access denied for user 30265782 to message with id 006b9b2df38f452b80402041ae86f6d4",
  "error": "forbidden",
  "status": 403,
  "cause": [ ]
}

Requested message does not exist:

{
    "message": "The specified message id does not exists",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Post errors

Message without receiver (“to” is missing):
400: The field ‘to.user_id’ is required

User id “to” invalid:
400: Invalid ‘to’ user id

User “from” and “to” are the same:
400: Sender and received must not be equals

User “from” is denied access to order:
403: Access denied for user {from.user_id} to order {to.resource_id}

If user_id is 0 and email is not a secure_email:
400: The field ‘to.email’ must be a secure email

Message receiver does not belong to order:
403: Receiver does not belong to order {to.resource_id}

“Resource” attribute is not found:
400: The field ‘to.resource’ is required

Resource attribute is invalid:
400: Invalid field ‘to.resource’

Request without site_id:
400:The field ‘to.site_id’ is required

site_id attribute is invalid:
400: The field ‘to.site_id’ has an invalid value

Post without Json body:
400: A JSON body is required

Message without ‘from’:
400: The field ‘from’ is required

Request without access token:
400: Access token is required

Access Token without application_id:
400: Application id is required

Messaging is blocked:
403: You can not send the message because the conversation is blocked by buyer.

403: You can not send the message because the conversation has been blocked by time.

GET messages by order Errors

User with no access to order:
403: User access token invalid for resource {resource_id}”

Request “limit” param must be greater than 0:
400: The limit param must be greater than 0

“Offset” param is invalid:
400: Invalid offset param

“Limit” param is invalid:
400: Invalid limit param

GET attachments Errors

Requested file could not be obtained:
500: File can not be accessed, try it later

Post attachments Errors

Problems when saving file:
500: File can not be saved, try it later

Attachment empty or null:
400: File attached is empty

File name cannot include characters such as: /, \
400: File name cannot include characters like /, \

File size exceeds 25 Mb. File size: x
400: File attachment is bigger than 25 Mb.

Message exceeds allowed number of attachments: 25
400: The message exceeds the allowed number of attachments: 25

PUT errors messages marked as unread

Invalid or empty message IDs

{
    "message": "Messages id empty or invalid.",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Ineffective message IDs

{
    "message": "The specified message id: a does not exists",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Message IDs that correspond to different orders

{
    "message": "Not allowed messages from multiple orders",
    "error": "bad_request",
    "status": 400,
    "cause": []
}



To get more information about how to use this service without logging out Mercado Libre, click here.


Next topic:
Subscribe to our feeds.

Please rate this