Reasons to communicate

Important:
From now on, to initiate post-sale messages with Mercado Envíos 2 (Fulfillment, Cross docking, Drop off and Flex) you must update your integration and the seller should choose a reason to communicate (action guide). Otherwise, you will receive the error blocked_by_conversation_started_by_seller.

Contents

→Check available communication options
→Check available communication options
→Check number of available messages
→Send message according to option_id
→Errors


Check available communication options

With the following resources, sellers have to choose a reason to start the conversation with the buyer and will have a number of messages available to send.


Available templates according the site

The template is a predefined text made available by Mercado Libre, which the seller cannot modify.


“REQUEST_VARIANTS” template

For MLA, MLM, MCO, MLC:

Hola, Si necesitas especificar algo sobre la opción del producto que compraste, por favor indícamelo ahora así puedo prepararlo antes de enviarlo. Gracias

For MLB:

Olá, Se você precisa especificar algo sobre a opção do produto que comprou, por exemplo, a cor, por favor, informe agora e assim podemos prepará-lo antes do envio. Obrigado.


“REQUEST_BILLING_INFO” template

For MLA:

Para adjuntarte la factura de tu compra necesito los siguientes datos:

  • Nombre y apellido
  • DNI
  • Domicilio
  • Código postal

For MLM:

Para adjuntarte la factura de tu compra necesito los siguientes datos:

  • Nombre y apellido
  • RFC
  • Domicilio
  • Código postal

For MCO:

Para adjuntarte la factura de tu compra necesito los siguientes datos:

  • Nombre y apellido
  • Tipo y número de documento
  • Email
  • Domicilio
  • Código postal
  • Código de municipio
  • Código de departamento

Para MLU:

Para adjuntarte la factura de tu compra necesito los siguientes datos:

  • Nombre y apellido
  • Cédula

Request:

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

Example:

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

Response:


{
   "options":[
      {
         "id":"REQUEST_VARIANTS",
         "internal_description":"This is an example...",
         "enabled":true,
         "type":"template",
         "templates":[
            {
               "id":"TEMPLATE___REQUEST_VARIANTS___1",
               "vars":null
            }
         ],
         "actionable":true,
         "child_options":null,
         "cap_available":1
      },
      {
         "id":"REQUEST_BILLING_INFO",
         "internal_description":"This is an example...",
         "enabled":true,
         "type":"template",
         "templates":[
            {
               "id":"TEMPLATE___REQUEST_BILLING_INFO___1",
               "vars":null
            }
         ],
         "actionable":true,
         "child_options":null,
         "cap_available":1
      },
      {
         "id":"SEND_INVOICE_LINK",
         "internal_description":"This is an example...",
         "enabled":true,
         "type":"free_text",
         "templates":null,
         "actionable":true,
         "char_limit":350,
         "child_options":null,
         "cap_available":1
      },
      {
         "id":"OTHER",
         "internal_description":"This is an example...",
         "enabled":true,
         "type":"free_text",
         "templates":null,
         "actionable":true,
         "char_limit":350,
         "child_options":null,
         "cap_available":1
      }
   ]
}

Response fields

char_limit: is the maximum number of characters accepted in the option ( "OTHER" o "SEND_INVOICE_LINK").
The REQUEST_VARIANTS option is only available in the Cross docking and Drop off shipment types.
The DELIVERY_PROMISE option is only available for Flex shipping mode. Within the template type options (REQUEST_VARIANTS and REQUEST_BILLING_INFO) we have the template id, which must be used in the POST to send the message.


Check number of available messages

Within the reasons tree, the categories can have the option of sending a message to the buyer and you can recognize them with the cap_available field:

  • If it is 0 (zero), the seller will not be able to send messages to the buyer
  • If it is 1 (one) or more, indicate the quantity available to ship.

Remember that the message will have limited characters and will keep the moderations of a normal message (only for OTHER and SEND_INVOICE_LINK).
In the event that the vendor has consumed the cap of messages available to send, if he re-enters an open field section (OTHER), the response will return an error that it is no longer possible to do so, and he must wait for the buyer reply.


Request:

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

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/200000000000/caps_available

Response:

[
   {
      "option_id":"REQUEST_VARIANTS",
      "cap_available":1
   },
   {
      "option_id":"REQUEST_BILLING_INFO",
      "cap_available":1
   },
   {
      "option_id":"SEND_INVOICE_LINK",
      "cap_available":1
   },
   {
      "option_id":"OTHER",
      "cap_available":1
   }
]

Send message according to option_id

After looking for the available options for the pack_id, you should send the message as the following POST. Remember that, after the buyer responds, the following messages must be sent directly through the post /messages.
Get to know the option_id available by sites:


Site / Option_id “REQUEST_VARIANTS”:
Request variant data
“REQUEST_BILLING_INFO”:
Request billing information
“SEND_INVOICE_LINK”:
Send link for billing
“OTHER”:
Others, free field
“DELIVERY_PROMISE”:
Informar promessa de entrega
MLA
MLB
MLM
MCO
MLC
MLU

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/messages/action_guide/packs/$PACK_ID/option -H 'Content-Type: application/json'  
{
    "option_id": $OPTION_ID,
    "template_id": $TEMPLATE_ID
}

Example with REQUEST_BILLING_INFO (template type):

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/messages/action_guide/packs/2000000000000000/option -H 'Content-Type: application/json'  
{
    "option_id": "REQUEST_BILLING_INFO",
    "template_id": "TEMPLATE___REQUEST_BILLING_INFO___1"
}

Message sent response:

{
    "id": "94353d192b9640e8b1ed3c77aa406f39",
    "to": {
        "user_id": 618491100,
        "name": "Test Test"
    },
    "status": "available",
    "text": "Este es un template para solicitar datos de facturación: ",
    "message_date": {
        "received": "2020-09-09T19:07:24.890Z",
        "available": "2020-09-09T19:07:25.056Z",
        "notified": null,
        "created": "2020-09-09T19:07:24.890Z",
        "read": null
    },
    "message_moderation": {
        "status": "clean",
        "reason": null,
        "source": "online",
        "moderation_date": "2020-09-09T19:07:25.056Z"
    }
}
Note:
The text field has the submitted content corresponding to the template.

Example with OTHER (Free text type):

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/messages/action_guide/packs/2000000000000000/option -H 'Content-Type: application/json'  \
{
    "option_id": "OTHER",
    "text": "Cómo estás María, estaría necesitando de..."
}

Response of message sent successfully:

{
    "id": "94353d192b9640e8b1ed3c77aa406f39",
    "to": {
        "user_id": 618491100,
        "name": "Test Test"
    },
    "status": "available",
    "text": "Cómo estás María, estaría necesitando de...",
    "message_date": {
        "received": "2020-09-09T19:07:24.890Z",
        "available": "2020-09-09T19:07:25.056Z",
        "notified": null,
        "created": "2020-09-09T19:07:24.890Z",
        "read": null
    },
    "message_moderation": {
        "status": "clean",
        "reason": null,
        "source": "online",
        "moderation_date": "2020-09-09T19:07:25.056Z"
    }
}
Note:
The text field has the content sent in the request body.

Moderate message response:

{
    "id": "94353d192b9640e8b1ed3c77aa406f39",
    "to": {
        "user_id": 618491100,
        "name": "Test Test"
    },
    "status": "moderated",
    "text": "Cómo estás María, estaría necesitando de...",
    "message_date": {
        "received": "2020-09-09T19:02:11.438Z",
        "available": null,
        "notified": null,
        "created": "2020-09-09T19:02:11.438Z",
        "read": null
    },
    "message_moderation": {
        "status": "rejected",
        "reason": "out_of_place_language",
        "source": "online",
        "moderation_date": "2020-09-09T19:02:11.697Z"
    }
}

Response fields

status: message status. For example: available or moderated
message_moderation:
status: moderation status of the message.
reason: moderation status. For example: out_of_place_language moderation for inappropriate language.



Example with DELIVERY_PROMISE:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/2000000000000000/option -H 'Content-Type: application/json'  \
{
  "option_id": "DELIVERY_PROMISE",
  "template_id": "TEMPLATE___DELIVERY_PROMISE___1",
  "vars": [{
      "id": "TEMPLATE___DELIVERY_PROMISE___1___VAR___INIT",
      "value": 12
  },
  {
      "id": "TEMPLATE___DELIVERY_PROMISE___1___VAR___LIMIT",
      "value": 23
  }]

}

Respuesta mensaje:

{

    "id": "374c945ce97446f5b4a73123adfasdd0e1ed17f",
    "status": "available",
    "text": "Entregaremos tu compra {hoy/mañana/el próximo día hábil} entre las {initial} y las {final} hs.",
    "to": {
        "user_id": 667304586,
        "name": "Test Test"
    },
    "message_date": {
        "received": "2021-01-11T18:06:46.070Z",
        "available": "2021-01-11T18:06:46.450Z",
        "notified": null,
        "created": "2021-01-11T18:06:46.070Z",
        "read": null
    },
    "message_moderation": {
        "status": "clean",
        "reason": null,
        "source": "online",
        "moderation_date": "2021-01-11T18:06:46.450Z"
    }

}

Errors

As an excepted case

The following are excepted:
- Autoparts and manufacturing time products
Remember that we can modify these exceptions without prior notice.

Example:

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

Response:

{
   "cause": "blocked_by_excepted_case",
   "error": "bad_request",
   "message": "This pack belongs to an excepted case, it is requested to use the messaging resource.",
   "status": 400
}

The seller may use after-sales messaging without restrictions.


Status (error) Message Detail
400 - bad_request The text is invalid For exceeding the 350 character limit (option OTHER and SEND_INVOICE_LINK)
403 - limit_exceeded You are not allowed to execute the option OTHER again Quantity (cap) not available
404 - not_found The option selected is not valid Option_id invalid
409 - conflict There is another request locking this operation This error occurs because the seller executes several simultaneous options on the same sale and, to prevent more caps from being made than available, we create a "Lock" of the service on the seller and the sale, which is released when the option is finished.
403 - forbidden The conversation is blocked Pack_id with blocked messages
403 - forbidden You are not allowed to access the information of the pack $PACK_ID Seller is not authorized to consult the information of that pack id
400 - bad_request The template $TEMPLATE_ID is invalid Template_id invalid
500 - internal_server_error Internal server error Internal error

Next: Message management.

or register to recieve the latest news about our API