Refresh Mercado Libre integration guide

_i18n/en/integrations/connect-mercado-libre.md

@@ -1,26 +1,128 @@
-If you're already selling on Mercado Libre, you can easily connect your Mercado Libre account to take advantage of several benefits.
+Connect your Mercado Libre seller account to bring marketplace sales, customer activity, post-sale conversations, and order notes into Hellotext.
 
-By connecting your Mercado Libre seller account, you can:
+Mercado Libre works as both a commerce data integration and a transaction-specific messaging channel. It is designed for communication related to a Mercado Libre order, not for campaigns or unrelated messages to marketplace buyers.
 
-* Automatically track all purchases made by customers on Mercado Libre, both for new and existing customers.
-* Automatically create customer profiles, including details like phone numbers, for follow-up, segmentation, and reporting.
-* Manage all post-sale communications from the Inbox.
-* Send post-sale follow-ups using prebuilt route templates or playbooks.
-* Manage notes from sales directly in Hellotext.
+The integration is currently available for businesses in Colombia and Uruguay.
 
-If you're a business selling on multiple channels, connecting your Mercado Libre account can help you keep customer profiles in one place, with a complete history of past purchases. That history becomes useful signal data for segmentation, playbooks, routes, campaigns, and attribution.
+## What the integration does
+
+After you connect an account, Hellotext can:
+
+- Track Mercado Libre sales and keep subsequent order activity synchronized.
+- Add order, product, amount, delivery, payment, claim, refund, and status information when Mercado Libre makes it available.
+- Create or update customer profiles with a Mercado Libre identity and any buyer details provided with the sale.
+- Bring post-sale messages and supported attachments into the Inbox.
+- Synchronize private seller notes with the corresponding Mercado Libre order.
+- Use eligible order activity as signals for segments, playbooks, routes, reporting, and attribution.
+
+Mercado Libre does not provide the same buyer data for every order. A customer profile can include the buyer's Mercado Libre username, name, email, or phone number when available, but you should not expect every profile to contain every field.
+
+Connecting Mercado Libre does not perform a complete historical import of every marketplace customer. Hellotext creates and updates customer profiles from the sales and buyer activity available to the integration.
+
+## Before you connect
+
+Confirm that:
+
+- You can sign in to the Mercado Libre seller account you want to connect.
+- The seller account is not already connected to another Hellotext business.
+- Your Hellotext business country is Colombia or Uruguay.
+- Your Hellotext subscription is active so order and message activity can continue syncing.
+- You know which team will manage Mercado Libre conversations in the Inbox.
 
 ## Connect your Mercado Libre account
 
-To connect your Mercado Libre account, follow these steps:
+1. In Hellotext, go to **Settings**.
+2. Select **Integrations** and then **Browse integrations**.
+3. Find **Mercado Libre** and select **Integrate Mercado Libre with Hellotext**.
+4. Sign in to the Mercado Libre seller account you want to connect.
+5. Review the requested access and authorize Hellotext.
+6. Return to Hellotext and select **Finish**.
+
+Hellotext starts receiving sales and buyer activity from the connected account; it does not import the seller's complete historical customer database. In some cases, new orders, messages, or notes can take up to one hour to appear because of Mercado Libre synchronization delays.
+
+## How Mercado Libre conversations work
+
+Every Mercado Libre conversation is connected to a specific order or package. It is not a general-purpose chat identity that can be messaged independently of a sale.
+
+Mercado Libre decides whether a seller can start or continue a conversation based on the operation and conversation state. For example, sending can be unavailable because:
+
+- The buyer must write first for that operation.
+- The seller has reached a limit on seller-initiated communication.
+- The payment or fulfillment state does not allow messages.
+- The order was canceled or refunded.
+- The buyer blocked the conversation.
+- A claim or mediation is active.
+- Mercado Libre applied a time or guest-shop restriction.
+
+When Mercado Libre requires the buyer to start, Hellotext waits for that first message and then lets your team reply when the conversation becomes available. Hellotext also stops offering an order as an outbound Mercado Libre route 30 days after its last interaction. Mercado Libre can close or restrict it earlier.
+
+Changing the message text does not remove an order restriction. Review [why a message did not send]({% link _troubleshooting-deliverability/why-a-message-did-not-send.md %}) before retrying.
+
+## Manage messages in the Inbox
+
+When a buyer writes through Mercado Libre, Hellotext adds the message to that customer's conversation in the Inbox. Your team can assign the conversation, reply, and close it using the same workflow as other supported channels.
+
+If the customer has more than one eligible Mercado Libre order, choose the order related to the reply. Hellotext sends the message through that order's post-sale conversation.
+
+Mercado Libre moderates message content. Do not include personal data, offensive language, social-network links, or Mercado Pago links. Supported attachments are sent through Mercado Libre and remain subject to its format, size, moderation, and conversation rules.
+
+For team workflow, read [Inbox and conversations overview]({% link _team/inbox-overview.md %}).
+
+## Add notes to a Mercado Libre order
+
+A note is different from a message:
+
+- A **message** is sent to the buyer in the post-sale conversation.
+- A **note** is private to your team and is also added to the selected order in Mercado Libre. It is not sent to the buyer.
+
+When you create a note from a customer conversation, select the Mercado Libre order it belongs to. New notes and note deletions are synchronized between Hellotext and the selected Mercado Libre order.
+
+## Use Mercado Libre in routes, playbooks, and the API
+
+An eligible Mercado Libre order can be used by a route or playbook when the flow has the related order activity and Mercado Libre permits the conversation. Hellotext will not use Mercado Libre merely because the customer profile has a marketplace username.
+
+The same restriction applies to messages created with the API: selecting `mercadolibre` does not bypass the order state or Mercado Libre's conversation rules. Read [Send messages with the API]({% link _developers/send-messages-with-api.md %}) for the request format.
+
+Mercado Libre is not available as a destination for campaigns.
+
+## Verify the integration
+
+After connecting:
+
+1. Wait for a new Mercado Libre sale to appear in Hellotext.
+2. Open the customer profile and confirm that the order and Mercado Libre identity are present.
+3. Check that a real buyer message appears in the Inbox when one is received.
+4. For an eligible conversation, reply from Hellotext and confirm that the message appears in Mercado Libre.
+5. Add a private note to the order and confirm that it appears in Mercado Libre without being sent to the buyer.
+
+Also follow [verify your data and signals after setup]({% link _integrations/verify-data-and-signals.md %}) before launching a route or playbook based on Mercado Libre activity.
+
+## Reconnect or remove the integration
+
+If Hellotext reports that Mercado Libre needs to be reauthenticated, go to **Settings > Integrations**, remove the affected integration, and connect the same seller account again.
+
+Removing the integration stops new order, message, and note synchronization and prevents new Mercado Libre sends. Existing customer profiles and conversations remain available for reference in Hellotext.
+
+## Troubleshoot synchronization
+
+If an order, message, or note is missing:
+
+1. Allow up to one hour for the latest activity to synchronize.
+2. Confirm that the Mercado Libre integration is still active under **Settings > Integrations**.
+3. Check that your Hellotext subscription is active.
+4. Open the sale in Mercado Libre and confirm that the missing activity belongs to the connected seller account.
+5. Reconnect the account if Hellotext shows an authentication warning.
+
+If the integration is active and the activity still does not appear, contact Hellotext support with the Mercado Libre order ID and the approximate time of the missing event.
+
+## Message costs
 
-1. Go to the *Settings* page.
-2. Click on *Integrations* on the left side of the page and then click on *Browse Integrations*.
-3. Select *Mercado Libre* from the list.
-4. You will be redirected to Mercado Libre and may be prompted to sign in if you're not already logged in.
-5. You will be asked to confirm that you want to authorize Hellotext to access your account. Click *Authorize* to grant Hellotext access.
-6. That's it! From now on, you'll start seeing new sales directly in the Inbox and customer data will be automatically tracked.
+Mercado Libre messages are included in Hellotext's non-SMS fair-use calculation. Read [fair-use message policy]({% link _billing/fair-use-message-policy.md %}) for the billing rules.
 
-## Notice on updates
+## Related guides
 
-Please note that due to Mercado Libre's integration limitations, in some cases there may be a delay of up to one hour for new orders, messages, and notes to appear in Hellotext.
+- [Setup and integrations overview]({% link _integrations/setup-overview.md %})
+- [Messaging channels overview]({% link _numbers/messaging-overview.md %})
+- [Inbox and conversations overview]({% link _team/inbox-overview.md %})
+- [Why a message did not send]({% link _troubleshooting-deliverability/why-a-message-did-not-send.md %})
+- [Send messages with the API]({% link _developers/send-messages-with-api.md %})

_i18n/en/numbers/messaging-overview.md

@@ -12,9 +12,11 @@ Use **Instagram DM** when customers discover your business on Instagram and init
 
 Use **Facebook Messenger** when customers contact your Facebook Page and your team needs those conversations in the Inbox.
 
-Many businesses use several channels: SMS for reach, WhatsApp for richer outbound and conversational experiences, and Instagram or Messenger for customer-initiated social conversations. Campaigns, routes, and playbooks can use the channels differently, so confirm how channel selection works for the experience you are launching.
+Use **Mercado Libre** when you sell through the marketplace and need transaction-specific post-sale conversations in the Inbox. It is tied to eligible Mercado Libre orders and is not a general campaign destination.
 
-Keep reading: [SMS channel fundamentals]({% link _numbers/sms-channel-fundamentals.md %}), [WhatsApp channel fundamentals]({% link _numbers/whatsapp-channel-fundamentals.md %}), [Instagram DM fundamentals]({% link _numbers/instagram-dm-fundamentals.md %}), and [Facebook Messenger fundamentals]({% link _numbers/facebook-messenger-fundamentals.md %}).
+Many businesses use several channels: SMS for reach, WhatsApp for richer outbound and conversational experiences, Instagram or Messenger for customer-initiated social conversations, and Mercado Libre for marketplace post-sale support. Campaigns, routes, and playbooks can use the channels differently, so confirm how channel selection works for the experience you are launching.
+
+Keep reading: [SMS channel fundamentals]({% link _numbers/sms-channel-fundamentals.md %}), [WhatsApp channel fundamentals]({% link _numbers/whatsapp-channel-fundamentals.md %}), [Instagram DM fundamentals]({% link _numbers/instagram-dm-fundamentals.md %}), [Facebook Messenger fundamentals]({% link _numbers/facebook-messenger-fundamentals.md %}), and [Connect Mercado Libre]({% link _integrations/connect-mercado-libre.md %}).
 
 ## SMS sender options
 
@@ -39,6 +41,7 @@ Before launching a campaign, playbook, or route, confirm that:
 - [WhatsApp channel fundamentals]({% link _numbers/whatsapp-channel-fundamentals.md %})
 - [Instagram DM fundamentals]({% link _numbers/instagram-dm-fundamentals.md %})
 - [Facebook Messenger fundamentals]({% link _numbers/facebook-messenger-fundamentals.md %})
+- [Connect Mercado Libre]({% link _integrations/connect-mercado-libre.md %})
 - [Connect WhatsApp]({% link _integrations/connect-whatsapp.md %})
 - [Who can I message? Consent and subscriber status]({% link _audience/consent-and-subscriber-status.md %})
 - [Capture tools overview]({% link _captures/capture-overview.md %})

_i18n/en/team/inbox-overview.md

@@ -64,6 +64,8 @@ For website conversations, also review [Webchat Widget playbook]({% link _captur
 
 For social conversations, review [Instagram DM fundamentals]({% link _numbers/instagram-dm-fundamentals.md %}) and [Facebook Messenger fundamentals]({% link _numbers/facebook-messenger-fundamentals.md %}).
 
+For marketplace post-sale conversations, review [Connect Mercado Libre]({% link _integrations/connect-mercado-libre.md %}).
+
 For satisfaction after closed conversations, also review [CSAT Pulse playbook]({% link _journeys/csat-pulse-playbook.md %}).
 
 For loyalty feedback after delivered orders, also review [NPS Pulse playbook]({% link _journeys/nps-pulse-playbook.md %}).