Gestión de mensajes

→Parámetros
→Obtener mensajes por order
→Obtener mensajes por pack
→Obtener mensajes por ID
→Crear mensajes para un comprador
→Errores
→Cargar y guardar adjuntos
→Obtener adjunto


Parámetros

message_id: ID del mensaje.
date_created: fecha de creación.
date: fecha en que se guarda el mensaje.
date_received: fecha en que se recibió el mensaje.
date_available: fecha en el que el mensaje ha pasado por moderación.
date_notified: fecha en el que el mensaje ha sido notificado a la contraparte.
date_read: fecha en el que el mensaje fue leído por la contraparte.
from: quién envía el mensaje.
user_id: ID del usuario que envió el mensaje.
email: email del usuario que envió el mensaje (secure email de la orden).
name: nombre del usuario que envió el mensaje.
to: quién recibe el mensaje.
user_id: ID del usuario que recibió el mensaje.
email: email del usuario que recibió el mensaje (secure email de la orden).
subject: subject del email.
text: texto del mensaje.
plain: texto plano del mensaje.
attachments: archivos adjuntos.
attachments_validations: validaciones de adjuntos.
invalid_size: si el tamaño del adjunto es inválido.
invalid_extension: extensión del adjunto inválido.
internal_error: error interno.
site_id: sitio de Mercado Libre (MLA, MLB, etc.).
message_resources: contiene una lista con IDs relacionados al mensaje, describiendo a qué recurso pertenece cada uno.
status: estado del mensaje.
moderation.status: resultado del proceso de moderación.

  • clean
  • rejected
  • pending: para casos que la moderación está en proceso
  • non_moderated: para casos viejos que no aplicó la moderación

moderation.date_moderated: fecha en que se impactó la información de moderación.

moderation.source: modalidad de la moderación.

moderation.reason: razón por la cual se moderó el mensaje. Actualmente, esta moderación puede ser por lenguaje inapropiadoa (OUT_OF_PLACE_LANGUAGE), por link de redes sociales (SOCIAL_NETWORK_LINK), links acortados (LINK_SHORT_URL), por ser un mensaje automático de integrador (AUTOMATIC_MESSAGE), por información personal (PERSONAL_DATA) o links de Mercado Pago (LINK_MERCADOPAGO).


Obtener mensajes por order

Importante:
Para MLA y MLC utiliza la funcionalidad de consultar mensajería por pack.

Para obtener los mensajes de una order en particular deberás hacer una consulta asociando el order_id:

Llamada:

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

Ejemplo:

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

Respuesta:

{
    "paging": {
        "limit": 10,
        "offset": 0,
        "threshold": 1000,
        "total": 1
    },
    "results": [
        {
            "message_id": "d13a11809dac44d497d829e9bbbc78ae",
            "date_received": "2019-07-04T20:50:02.124Z",
            "date": "2019-07-04T20:50:02.124Z",
            "date_available": "2019-07-04T20:50:02.124Z",
            "date_notified": "2019-07-04T20:51:33.471Z",
            "date_read": null,
            "from": {
                "user_id": "419059118",
                "email": "ttest.hpz2z6q+2-ogiydkmzvg43tmobs@mail.mercadolivre.com",
                "name": "Test"
            },
            "to": [
                {
                    "user_id": "419067349",
                    "email": "ttest.6hqmq6+2-ogiydkmzvg43tmobx@mail.mercadolivre.com"
                }
            ],
            "subject": "Produto Teste - Não Ofertar",
            "text": {
                "plain": "Olá, tudo bem?"
            },
            "attachments": [],
            "attachments_validations": {
                "invalid_size": [],
                "invalid_extension": [],
                "forbidden": [],
                "internal_error": []
            },
            "site_id": "MLB",
            "resource": "orders",
            "resource_id": "2053577644",
            "status": "available",
            "moderation": {
                "status": "clean",
                "date_moderated": "2019-07-04T20:50:02.177Z",
                "source": "online"
            },
            "conversation_first_message": true
        }
    ],
    "conversation": {
        "status": "active",
        "status_date": null,
        "substatus": null,
        "is_blocking_allowed": false
    }
}

Obtener mensajes por pack

Para obtener los mensajes de un paquete en particular deberás hacer una consulta asociando el pack_id y el user_id, correspondiente al vendedor del paquete, con el recurso /messages.

Para conocer el pack_id, deberás obtener el campo “pack_id” en la respuesta de /orders/<order_id>

En caso que el pack id contenga un valor null, se deberá tomar por defecto el order id, manteniendo el recurso /packs en la llamada a la API.

Los mensajes moderados por la contraparte no serán visibles y sí podrán verse los mensajes propios.

Importante:
Cuando consultes a /messages/packs/pack_id/sellers/seller_id los mensajes se marcarán como leídos. En caso que no quieras marcarlos como leídos, realiza el GET con el parámetro mark_as_read = false y la consulta será: /messages/packs/pack_id/sellers/seller_id?mark_as_read=false.
Recuerda que el resto de recursos no marcarán los mensajes como leídos.

Llamada:

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

Ejemplo:

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

Respuesta:

{
   "paging":{
      "limit":10,
      "offset":0,
      "total":3
   },
   "conversation_status":{
        "path": "/packs/2000000089077943/seller/415458330",
        "status": "active",
        "substatus": null,
        "status_date": "2020-12-05T20:01:46.000Z",
        "status_update_allowed": false,
        "claim_id": null,
        "shipping_id": null
    },
   "messages":[
      {
         "id":"fd1d2e37ad004ede9e0bf25d1215002d",
         "site_id":"MLB",
         "client_id":123456789,
         "from":{
            "user_id":"123456789000",
            "email":"test@test.com.br",
            "name":"User Test"
         },
         "to":{
            "user_id":"2332423234",
            "email":"juliotest@test.com",
            "name":"Julio Test"
         },
         "status":"available",
         "subject":null,
         "text":"Mensaje de test",
         "message_date":{
            "received":"2020-12-05T20:01:46.000Z",
            "available":"2020-12-05T20:01:46.000Z",
            "notified":"2020-12-05T20:01:46.000Z",
            "created":"2020-12-05T20:01:46.000Z",
            "read":null
         },
         "message_moderation":{
            "status":"clean",
            "reason":null,
            "source":"online",
            "moderation_date":"2020-12-05T20:01:46.000Z"
         },
         "message_attachments":null,
         "message_resources":[
            {
               "id":"000011122344",
               "name":"packs"
            },
            {
               "id":"475684066",
               "name":"sellers"
            }
         ],
         "conversation_first_message":false
      }
   ],
   "seller_max_message_length":350,
   "buyer_max_message_length":3500
}
Nota:
Al final de la respuesta puede ver la cantidad máxima de caracteres que puede enviar el vendedor (seller_max_message_length).

Errores

Status Error Mensaje
403 User access token invalid for resource {resource_id} Usuario sin acceso a la orden
400 The limit param must be greater than 0 El param “limit” del request debe ser mayor a 0
400 Invalid offset param Param “offset” inválido
400 Invalid limit param Param “limit” inválido

Obtener mensajes por ID

Para conocer los mensajes asociados a un pack, deberás hacer una consulta al recurso /messages. 

Nota:
Incluye en la llamada el header “X-Pack-Format”: true para obtener la respuesta actualizada. Si no lo envías, seguirás recibiendo la respuesta antigua basada en la orden.

Llamada:

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

Ejemplo de respuesta sin header:

{
  "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": "clean",
      "date_moderated": "2019-03-13T09:34:26.450-04:00",
      "source": "online"

  
}

Ejemplo de respuesta con header:

{
    "paging": null,
    "conversation_status": null,
    "messages": [
        
            "id": "2c9380846a6fc814016a6fd38fe00007",
            "site_id": "MLA",
            "client_id": 1,
            "from": {
                "user_id": "391302538",
                "email": "fernanda.giustozzi+391302538@mercadolibre.com",
                "name": "Test Test"
            },
            "status": "available",
            "text": "newMessage",
            "message_date": {
                "received": "2019-04-30T19:58:17.000Z",
                "available": "2019-04-30T19:58:17.000Z",
                "notified": null,
                "created": "2019-04-30T19:58:17.000Z",
                "read": "2019-04-30T20:24:48.000Z"
            },
            "message_moderation": {
                "status": "clean",
                "reason": null,
                "source": "online",
                "moderation_date": "2019-04-30T19:58:17.000Z"
            },
            "message_attachments": [
                
                    "filename": "391302538_b6498e76-5af0-4206-aaeb-2aa6e754263e.jpg",
                    "original_filename": "319176.jpg",
                    "type": "image/jpeg",
                    "size": 661635,
                    "potential_security_threat": false,
                    "creation_date": "2019-04-30T19:58:17.000Z"
                
            ],
            "message_resources": [
                
                    "id": "2000000094354573",
                    "name": "packs"
                },
                
                    "id": "391302235",
                    "name": "sellers"
}

Errores

Status Error Mensaje
403 Access denied for user 30265782 to message with id 006b9b2df38f452b80402041ae86f6d4 Usuario sin acceso a un determinado mensaje
400 The specified message id does not exists No existe el mensaje pedido
404 The message with id: a could not be retrieved from storage Mensaje no encontrada en el servidor, intentar nuevamente en algunos segundos
404 The message with id: a could not be retrieved from storage Mensaje no encontrado en el servidor. Intente nuevamente en unos segundos


Crear mensajes para un comprador

Para enviar un mensaje a tu comprador, deberás agregar en el “from” del mensaje el user_id y el email del vendedor. Además, recuerda que tienes un límite de 350 caracteres.

Recuerda que permitimos aquellos caracteres incluidos en la norma ISO-8859-1 latin1 y los emoticones de esta lista.

Llamada:

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

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'postman-token: 167b4f47-cb87-2b27-2a3c-cfb012df9314' \
  -H 'x-client-id: 8794217632667367' \
  -d 
{
	"from": {
		"user_id": "415458330",
		"email": "test"
	},
	"to": {
		"user_id": "415460047"
	},
	"text": "Test message ToUserId 2",
	"attachments": ["415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d.pdf"]
}
https://api.mercadolibre.com/messages/packs/2000000089077943/sellers/415458330"&application_id=$APPLICATION_ID
Notas:
- El atributo attachments se obtiene de la respuesta del POST de attachments. Mira cómo cargar y guardar adjuntos.
- En caso de no necesitar adjuntar un archivo, debes eliminar la sección “attachments” del JSON. 
- Si necesitas insertar un enlace en el que se pueda hacer clic, puedes hacerlo utilizando la función href. Por ejemplo: "<a href="su_url"> Su link de seguimiento </a>".

Errores

Importante:
A partir del 13 de mayo de 2021, bloquearemos la mensajería en órdenes con estado cancelled de todas las categorías. En caso de tener una conversación abierta previo a la fecha mencionada, la mensajería estará disponible.
{
    "message": "blocked_conversation_send_message_forbidden",
    "error": "conversation_blocked",
    "status": 403,
    "cause": "blocked_by_cancelled_order"
}
Status Error Mensaje
400 The text has character/s that is/are not supported. Cuando envías un caracter no admitido, por ejemplo: UTF-8.
400 The message content is too long, max characters allowed are 350 Mensaje excede el límite de 350 caracteres
403 You can not send the message because a mediation is in process Error por mensaje bloqueado. Este error solo aplica para Brasil.
403 You can not send the message because the purchase is Mercado Envíos Full and has not been yet delivered Error por envío gestionado por Fulfillment (Mercado Libre)
403 Access denied for user {from.user_id} to order {to.resource_id} El user “from” no tiene acceso a la orden
403 Receiver does not belong to order {to.resource_id} El receptor del mensaje no pertenece a la orden
400 The field 'to.user_id' is required Mensaje sin receptor (falta agregar “to”)
400 Invalid ‘to’ user id User id “to” inválido
400 Sender and received must not be equals El user “from” y “to” son iguales
400 The field 'to.email' must be a secure email Si el user_id es 0 y el email no es un secure_email
400 The field 'to.resource' is required No se encuentra el atributo “resource”
400 Invalid field 'to.resource' Atributo resource inválido
400 The field 'to.site_id' is required Request sin site_id
400 The field 'to.site_id' has an invalid value Atributo site_id inválido
400 A JSON body is required Post sin Json body
400 The field 'from' is required Mensaje sin ‘from’
400 Access token is required Request sin access token
400 Application id is required Access token sin application_id

Cargar y guardar adjuntos

Para adjuntar un archivo dentro del mensaje primero deberá ser guardado. Luego, cuando se envía un adjunto, se devuelve el id del archivo como respuesta.


Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/attachments
Notas:
- El POST debe realizarse como form.data con key: value > file = referencia al file (es decir el archivo en sí).
- El archivo debe tener un tamaño máximo de 25 MB.
- Podrán intercambiarse fotos, manuales de instrucciones, facturas y demás archivos adjuntos en JPG, PNG, PDF y TXT de hasta 25 MB.

Ejemplo:

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

En este caso el servidor responderá con un JSON que contendrá el id del archivo en caso que el request haya sido exitoso.

Nota:
La respuesta obtenida se deberá anexar en el mensaje deseado.

Respuesta:

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

Status Error Mensaje
500 File can not be saved, try it later Problemas al almacenar el archivo
400 File attached is empty Attachment vacío o nulo
400 File name cannot include characters like /, \ El nombre del archivo no puede tener caracteres como /, \
400 File attachment is bigger than 25 Mb. El tamaño del archivo excede los 25 Mb.
400 The message exceeds the allowed number of attachments: 25 El mensaje excede la cantidad permitida de adjuntos: 25

Obtener adjunto

Para obtener un mensaje adjunto se deberá hacer una llamada GET.


Llamada:

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

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/attachments/76601286_5946e4c4-168a-45fd-945e-b8f0c306c58d.png

Respuesta:

Si el request es exitoso, la llamada devolverá el archivo solicitado. En caso de que no sea posible acceder al archivo la respuesta del servidor será la siguiente:

Status Error Mensaje
500 File can not be saved, try it later No se pudo obtener el archivo solicitado

Siguiente: Mensajes pendientes.

o regístrate para recibir las últimas novedades sobre nuestra API