Reasons to communicate

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.

For MLA, MLM, MCO, MLC:

For MLB:

“REQUEST_BILLING_INFO” template

For MLA:

For MLM:

For MCO:

Para MLU:

Request:

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

Example:

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

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?tag=post_sale

Example:

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

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:

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/messages/action_guide/packs/$PACK_ID/option?tag=post_sale -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"
    }
}

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

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

- Manufacturing time products

Example:

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

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
}

So, the seller may use after-sales messaging without restrictions.

Next: Message management.