Gestão de mensagens

Este recurso permite gerenciar a comunicação entre vendedores e compradores no contexto pós-venda, incluindo o envio, consulta e gerenciamento de mensagens e anexos.

Nova arquitetura de mensageria

IDs dos Agentes por país

Considerações

• Os recursos de consulta (GET) compartilham um rate limit de 500 rpm, e os recursos de escrita (POST/PUT) também compartilham entre si um rate limit de 500 rpm.
• A regra de início de conversa permanece inalterada: o vendedor não pode iniciar uma conversa. O fluxo sempre deve ser iniciado pelo comprador.

Parâmetros

• message_id: ID de mensagem.
• date_created: Data de criação.
• date: Data em que a mensagem é salva.
• date_received: Data de recepção da mensagem.
• date_available: Data em que a mensagem passou por moderação.
• date_notified: Data em que a contraparte foi notificada da mensagem.
• date_read: Data em que a contraparte leu a mensagem.
• from: Quem envia a mensagem.
• to: Quem recebe a mensagem.
• user_id: ID do usuário (remetente ou destinatário).
• subject: Assunto do email.
• text: Texto da mensagem.
• plain: Texto plano da mensagem.
• attachments: Anexos.
• attachments_validations: Validações de anexos.
• invalid_size: Tamanho de anexo inválido.
• invalid_extension: Extensão de anexo inválida.
• internal_error: Erro interno.
• site_id: Site do Mercado Livre (MLA, MLB, etc.).
• message_resources: Contém uma lista com IDs relacionados à mensagem, descrevendo a que recurso cada um pertence.
• resource: Relativo à ordem a que pertence (orders).
• resource_id: ID da ordem.
• status: Status da mensagem (available - moderated - rejected - pending_translation).
• moderation_status: Status de moderação da mensagem.
• moderation.status: Resultado do processo de moderação (clean, rejected, pending, non_moderated).
• moderation.date_moderated: Data em que a informação de moderação impactou.
• moderation.source: Modalidade da moderação.
• moderation.reason: Motivo pelo qual a mensagem foi moderada. Valores possíveis: OUT_OF_PLACE_LANGUAGE, SOCIAL_NETWORK_LINK, LINK_SHORT_URL, AUTOMATIC_MESSAGE, PERSONAL_DATA, LINK_MERCADOPAGO, ML_LINKS_PAYPAL, EVASION_CLAIM_SELLER.

Obter mensagens de um pacote

Utilize o pack_id na chamada para obter as mensagens enviadas. Caso o pack_id seja null, você pode utilizar o order_id como padrão, mas mantendo a estrutura do endpoint (ou seja, ainda utilizando /packs). Considere que as mensagens enviadas pelos compradores, que forem moderadas, não estarão visíveis. Por outro lado, as mensagens do vendedor, ainda que moderadas, estarão visíveis.

Quando consultar o /messages/packs/pack_id/sellers/seller_id, as mensagens serão marcadas como lidas. Caso você não queira marcá-las como lidas, execute o GET com o parâmetro mark_as_read=false e a consulta será: /messages/packs/pack_id/sellers/seller_id?mark_as_read=false. Lembre-se de que o restante dos recursos não marcará as mensagens como lidas.

Chamada:

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

Exemplo:

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

Resposta:

{
  "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,
        },
        "to":{
           "user_id": 2332423234,
        },
        "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
}

No final da resposta, você pode ver o número máximo de caracteres que o vendedor pode enviar (seller_max_message_length).

Obter os detalhes da mensagem por ID

Com este recurso você poderá obter as informações da mensagem enviada utilizando o ID retornado no recurso Obter mensagens de um pacote.

Chamada:

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

Exemplo de resposta sem 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
  },
  "to": {
    "user_id": 123456780
  },
  "subject": "Test Item subject",
  "text": {
    "plain": "Exemplo de texto"
  },
  "attachments": [
    {}
  ],
  "attachments_validations": {
    "invalid_size": [],
    "invalid_extension": [],
    "forbidden": [],
    "internal_error": []
  },
  "site_id": "MLB",
  "resource": "orders",
  "resource_id": "1234567871",
  "status": "available",
  "moderation": {
    "status": "clean",
    "date_moderated": "2019-03-13T09:34:26.450-04:00",
    "source": "online"
  }
}

Exemplo de resposta atualizada (com header):

{
	"paging": null,
	"conversation_status": null,
	"messages": [{
		"id": "fd1d2e37ad004ede9e0bf25d1215002d",
		"site_id": "MLB",
		"client_id": 123456789,
		"from": {
			"user_id": 123456789000
		},
		"to": {
			"user_id": 2332423234
		},
		"status": "available",
		"subject": null,
		"text": "Mensagem de teste",
		"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
	}]
}

Enviar mensagem para o comprador

Utilize este recurso para criar uma mensagem a ser enviada ao comprador. Há um limite de 350 caracteres. Aceitamos os caracteres da norma ISO-8859-1 latin1 e os emoticons dessa listagem.

Considere que a partir de 02/02/2026 estaremos dando início à migração para nova arquitetura de mensageria. Com isso, para MLB e MLC, ao criar a mensagem a ser enviada ao comprador lembre-se de que o campo "to": { "user_id" } deverá conter o ID do Agente do país correspondente. Consulte a tabela de IDs dos Agentes.

O atributo attachments se obtém da resposta do POST de attachments. Veja como Carregar e salvar um anexo. Se não for preciso anexar um arquivo, a seção "attachments" deve ser removida do JSON. Caso necessite inserir um link clicável no texto, pode inserir usando a função href, por exemplo: <a href="sua_url">Seu link de rastreio</a>.

Importante: os anexos devem ser associados a uma mensagem dentro de 2 dias (48 horas) após o seu carregamento; caso contrário, serão eliminados e o envio falhará. Nesse caso, carregue o arquivo novamente para obter uma nova key (ID do anexo).

Chamada:

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

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/packs/2000000089077943/sellers/415458330?tag=post_sale \
  -H 'Content-Type: application/json' \
  -d '{
    "from": {
      "user_id": "415458330"
    },
    "to": {
      "user_id": "3037675074"
    },
    "text": "Olá! Sua encomenda foi despachada.",
    "attachments": ["415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d.pdf"]
  }'

Erro possível:

{
    "status_code": 403,
    "code": "forbidden",
    "message": "blocked_conversation_send_message_forbidden"
}

Carregar e salvar um anexo

Para anexar um arquivo na mensagem, ele deverá ser salvo previamente. A resposta retornará o ID do anexo. O POST deve ser realizado como form-data com key: value → file = referência ao arquivo. O arquivo deve ter um tamanho máximo de 25 MB. Formatos aceitos: JPG, PNG, PDF e TXT.

Chamada:

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

Exemplo:

curl -X POST \
  'https://api.mercadolibre.com/messages/attachments?tag=post_sale&site_id=MLB' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/home/user/Anexo.jpg'

Neste caso, o servidor responderá com um JSON contendo o ID do arquivo, caso a requisição tenha sido bem-sucedida. A resposta obtida deverá ser anexada na mensagem desejada.

Resposta:

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

Vencimento de anexos não atribuídos (TTL de primeira relação):

Todo anexo enviado que não seja atribuído a uma mensagem dentro de 2 dias (48 h) será eliminado automaticamente. Essa limpeza afeta unicamente anexos "órfãos" (sem relação com nenhuma mensagem).

• Início da contagem: a partir da confirmação de envio (resposta bem-sucedida do upload).
• Alcance: aplica-se até a primeira associação do anexo a uma mensagem. Uma vez associado pela primeira vez, o anexo deixa de estar sujeito a esse TTL.
• Efeito: a eliminação é irreversível. Tentativas de usar a key de um anexo eliminado falharão.
• Recomendação: envie o anexo o mais próximo possível do envio e associe a key imediatamente.
• Recuperação: se o anexo foi eliminado, envie o arquivo novamente para obter uma nova key e use-a na mensagem.

Obtenha os anexos enviados

Para obter os detalhes sobre o(s) anexo(s) previamente carregados, realize:

Chamada:

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

Exemplo:

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

Se o request for bem-sucedido, a chamada retornará o arquivo solicitado.

Erros

A seguir estão listados os possíveis erros que podem ocorrer ao utilizar os recursos de mensageria.

Obter mensagens de um pacote

Obter mensagens por ID

Enviar mensagem para o comprador

Carregar e salvar anexo

Obter anexo

Próximo: Mensagens pendentes.