Motivos para comunicar
Conteúdos
→Consultar as opções de comunicação disponíveis
→Consultar a quantidade disponível de mensagens pós-venda
→Enviar mensagem de acordo com a opção
→Erros
Consultar as opções de comunicação disponíveis
Com os recursos a seguir, os vendedores precisam escolher um motivo para iniciar a conversa com o comprador e terão uma série de mensagens disponíveis para enviar. O template é um texto pré-definido disponibilizado pelo Mercado Livre, que o vendedor não pode modificar.
Templates disponíveis segundo país
O template É um texto pré-definido disponibilizado pelo Mercado Livre, que o vendedor não pode modificar.
Template de “REQUEST_VARIANTS”
Para MLA, MLM, MCO, MLC:
Para MLB:
Template de “REQUEST_BILLING_INFO”
Para MLA:
Para MLM:
Para MCO:
Para MLU:
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/$PACK_ID
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/20000000000
Resposta:
{
"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
}
]
}
Campos da resposta
char_limit: é o número máximo de caracteres aceitos na opção.
A opção REQUEST_VARIANTS está disponível apenas nos tipos de envio cross docking e drop off.
A opção de DELIVERY_PROMISE, só estará disponível para envios Flex.
Dentro das opções de tipo de template (REQUEST_VARIANTS e REQUEST_BILLING_INFO) temos o id do template, que deve ser usado no POST para envio da mensagem.
Template de “DELIVERY_PROMISE"
Mocks para enviar promessa de entrega (Flex)
Utilize o pack_id 2000000000000014, o access token test 123123123 e os mocks para fazer a adaptação do desenvolvimento, com o motivo “DELIVERY_PROMISE” para envios Flex. Informamos que todos os outros motivos continuam funcionando em sua normalidade e com recursos produtivos.
Exemplo de motivos com Flex:
curl -X GET -H 'Authorization: Bearer 123123123' https://api.mercadolibre.com/messages_mock/action_guide/packs/2000000000000014
Resposta:
[
{
"options":[
{
"id":"DELIVERY_PROMISE",
"internal_description":"This is an example...",
"enabled":true,
"type":"TEMPLATE",
"templates":[
{
"id":"TEMPLATE___DELIVERY_PROMISE___1",
"texts":{
"mla":{
"html":"Entregaremos tu compra %s entre las %d y las %d hs."
},
"mlm":{
"html":"Entregaremos tu compra %s entre las %d y las %d hs."
},
"mco":{
"html":"Entregaremos tu compra %s entre las %d y las %d hs."
},
"mlu":{
"html":"Entregaremos tu compra %s entre las %d y las %d hs."
}
},
"vars":[
{
"id":"TEMPLATE___DELIVERY_PROMISE___1___VAR___INIT",
"type":"NUMBER"
},
{
"id":"TEMPLATE___DELIVERY_PROMISE___1___VAR___LIMIT",
"type":"NUMBER"
}
]
}
],
"actionable":true,
"char_limit":null,
"child_options":[
],
"cap_available":1
}
]
}
]
Exemplo de envio de mensagem segundo a com DELIVERY_PROMISE:
curl -X POST -H 'Authorization: Bearer 123123123' https://api.mercadolibre.com/messages_mock/action_guide/packs/2000000000000014/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
}
]
}
Resposta:
[
{
"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"
}
}
]
No texto enviaremos o dia de entrega de acordo com a informação do pedido e o horário que foi informado no POST nas variáveis "initial" e "limit" (em horas).
Consultar a quantidade disponível de mensagens pós-venda
Dentro da árvore de motivos, as categorias podem ter a opção de enviar uma mensagem ao comprador e você pode reconhecê-los com o campo cap_available:
- Se for 0 (zero), o vendedor não poderá enviar mensagens ao comprador
- Se for 1 (um) ou mais, indique a quantidade disponível para envio
Lembre-se que a mensagem terá caracteres limitados e manterá as moderações de uma mensagem normal (apenas para OTHER e SEND_INVOICE_LINK).
Caso o vendedor tenha consumido o limite de mensagens disponíveis para envio, se ele entrar novamente em uma seção de campo aberto (OTHER), a resposta retornará um erro de que não é mais possível fazê-lo, e ele deverá aguardar o resposta do comprador.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/$PACK_ID/caps_available
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/200000000000/caps_available
Resposta:
[
{
"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":"DELIVERY_PROMISE",
"cap_available":1
},
{
"option_id":"OTHER",
"cap_available":1
}
]
Enviar mensagem de acordo com a opção
Após procurar as opções disponíveis para o pack_id, você deve enviar a mensagem como o seguinte POST. Lembre-se de que, após a resposta do comprador, as seguintes mensagens devem ser enviadas diretamente com o post /messages.
Conheça os option_id disponibilizados pelos sites:
Sitio / Option_id | “REQUEST_VARIANTS”: Solicitar dados de variações |
“REQUEST_BILLING_INFO”: Solicitar informações de faturamento |
“SEND_INVOICE_LINK”: Enviar link para faturamento |
“OTHER”: Outros, campo livre |
“DELIVERY_PROMISE”: Informar promessa de entrega |
---|---|---|---|---|---|
MLA | |||||
MLB | |||||
MLM | |||||
MCO | |||||
MLC | |||||
MLU |
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/$PACK_ID/option -H 'Content-Type: application/json'
{
"option_id": $OPTION_ID,
"template_id": $TEMPLATE_ID
}
Exemplo com REQUEST_BILLING_INFO (Tipo template):
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": "REQUEST_BILLING_INFO",
"template_id": "TEMPLATE___REQUEST_BILLING_INFO___1"
}
Resposta de mensagem enviada:
{
"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"
}
}
Exemplo com OTHER (Tipo texto livre):
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": "OTHER",
"text": "Cómo estás María, estaría necesitando de..."
}
Resposta de mensagem enviada corretamente:
{
"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"
}
}
Resposta de mensagem moderada:
{
"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"
}
}
Campos da resposta
status: status da mensagem. Por exemplo: available o moderated
message_moderation:
status: status de moderação de mensagem.
reason: razão para moderação. Por exemplo: out_of_place_language moderação para linguagem imprópria.
Exemplo com DELIVERY_PROMISE:
Importante: A partir de 27 de janeiro estará disponível a seguinte opção. Até este dia o seu desenvolvimento estará baseado nos mocks.
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
}]
}
}
Resposta 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"
}
}
Erros
Como um caso excepcional
Os seguintes são exceções:
- Produtos Acessórios para Veículos e com tempo de conclusão (manufacturing time)
- Produtos com envio Flex
Lembre-se de que podemos modificar essas exceções sem aviso prévio.
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/2000000000000012
Resposta:
{
"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
}
O vendedor pode usar mensagens pós-venda sem restrições.
Status (error) | Mensaje | Detalle |
---|---|---|
400 - bad_request | The text is invalid | Por exceder o limite de 350 caracteres (option OTHER e SEND_INVOICE_LINK) |
403 - limit_exceeded | You are not allowed to execute the option OTHER again | Quantidade (cap) não disponível |
404 - not_found | The option selected is not valid | Option_id inválido |
409 - conflict | There is another request locking this operation | Esse erro ocorre porque o vendedor executa várias opções simultâneas sobre a mesma venda e, para evitar que sejam feitos mais caps do que os disponíveis, criamos um "Lock" do serviço no vendedor e na venda, que é liberado ao finalizar a opção. |
403 - forbidden | The conversation is blocked | Pack_id com mensageria bloqueada |
403 - forbidden | You are not allowed to access the information of the pack $PACK_ID | O vendedor não está autorizado a consultar as informações desse pack id |
400 - bad_request | The template $TEMPLATE_ID is invalid | Template_id incorreto |
500 - internal_server_error | Internal server error | Erro interno |
Seguinte: Gestão de mensagem.