Catalog & Commerce

Catalog & Commerce overview

Overview The Catalog & Commerce module brings together everything about products and sales inside your conversations. With it you keep a native catalog (products, categories, images and prices), sync that catalog with Meta's WhatsApp Business Catalog, send products and product lists directly in the chat, receive customer orders as a ready-to-charge card, and track the e-commerce lifecycle of external platforms (Kiwify, Hotmart, Nuvemshop, Shopify) without leaving the platform. The goal is to turn the conversation into a sales counter: the customer sees the product, builds the order, and you collect payment — all in one place, integrated with CRM, Payments and Follow-ups. Prerequisites - An active Conversa Labs account with the Catalog & Commerce module enabled for your plan and access role. If you don't see the module, talk to an administrator. - For WhatsApp Business Catalog: a connected WhatsApp (Cloud API) Inbox that can be bound to the Meta catalog. - For the e-commerce lifecycle: access to the external platform (Kiwify, Hotmart, Nuvemshop or Shopify) to set up the webhook. - To charge orders: the Payments module configured (gateways such as Asaas or Mercado Pago). Step by step 1. Create or import your native product catalog (with categories, images and prices). 2. If you serve customers over WhatsApp, bind and sync the catalog with the WhatsApp Business Catalog. 3. During a conversation, send products (a single product or a list) to the customer. 4. When the customer builds a cart, receive the order as a card and generate a charge or a subscription. 5. Connect e-commerce platforms to track the lifecycle (abandoned cart, pending PIX, approved purchase, refund) and recover sales with Follow-ups. Settings & options - Native catalog: product records, categories, images, price and availability. - Sync sources: binding to the WhatsApp Business Catalog (Meta) and to external connectors, with a configurable sync interval. - Sending in the conversation: send a single product, a product list, or open the WhatsApp catalog. - Orders: order card with items, total and shortcuts to Create charge / Create subscription. - Commerce (lifecycle): external platform webhooks with a per-source URL and verification secret. Use cases - A store that serves customers over WhatsApp and wants to show native products without sending the customer to a website. - An operation that receives orders from the WhatsApp cart and bills immediately with PIX or boleto. - A digital-product seller using Kiwify/Hotmart who wants to recover abandoned carts and pending PIX. - A Nuvemshop/Shopify store that centralizes sales recovery inside support. Tips, limits & best practices - Major-unit amounts: a price of 4.97 means R$4.97 — never divide by 100. An order total is the sum of price × quantity for each item. - Native WhatsApp products and orders (catalog, list, order card) work on the Cloud API; on WhatsApp Web, sales use the enriched product card as a fallback. - Keep product images publicly accessible so the sync can download them. - Start with a well-organized native catalog before enabling sync and external connectors. Troubleshooting - I don't see the module: it may not be enabled for your account or role — talk to an administrator. - Products without images after sync: check that the original images are reachable and run the sync again (each run re-attempts the image download). - The customer doesn't receive the native product/order: confirm the inbox is WhatsApp Cloud API. See also - Native catalog: products, categories, images and prices - Sync and WhatsApp Business Catalog - Send a product and receive orders in the conversation - E-commerce lifecycle

Native catalog: products, categories, images and prices

Overview The native catalog is your product base inside Conversa Labs. It's where you record each item with name, description, images, price and availability, organize everything into categories, and keep the data that will be used to sync with WhatsApp and to send products during a conversation. Keeping it well organized is the first step: from it you sync with Meta, send products in the chat, and charge orders. Even if you also use external platforms, the native catalog is the source of truth inside the platform. Prerequisites - The Catalog & Commerce module enabled for your account and access role. - Permission to manage the catalog (create/edit products and categories). - Product images in a common format (for example, JPG or PNG) and reachable. Step by step 1. Open the platform's Catalog area. 2. Create your categories to group products (for example, "Drinks", "Services", "Courses"). 3. Add a product: enter name, description, category and its first variant. 4. For every variant, set a name, SKU, price and options such as Color: Blue and Size: M. 5. Use the arrow controls to set the display order and select exactly one default variant. 6. Attach one or more images to the product. You can then assign a specific product image to each variant; variants without one use the primary product image. 7. Set availability and inventory when applicable, save, and repeat for the rest of your products. Settings & options - Product: name, description, price, category, availability, images and identifiers (such as SKU and external link). - Categories: product grouping that makes search and list building easier. - Images: one or more per product; the first is typically used as the highlight. - Variants: each sellable combination has its own name, options, position, price, stock and optional image. The default variant is the initial choice in lists and sends. - Archiving a variant: the edit form only discards variants that have not been saved yet. Archive a saved variant from the product detail after confirmation; choose another default first. The archived row and its order and payment history remain available. - Variant image: can only be selected from the same product gallery. Deleting it safely returns that variant to the primary product image. - Price: always in major units of the currency (see the tips section). - Automatic stock decrement: when a live sale becomes paid, the quantity of each inventory-tracked variant is decremented exactly once. The charge and order for the same sale share one identity, so duplicate webhooks or both events do not decrement twice. Stock stops at zero; variants without inventory tracking are unchanged. Historical imports and adoptions do not change the current balance either. Tracked stock uses whole units: a fractional line fails safely without rounding or partially decrementing the sale and remains visible in History. Fractional quantities on variants without inventory tracking do not affect stock. - Reports: the report view separates a deal item's quoted budget from the realized value of paid order items. The two metrics are not added together and can differ because of discounts, shipping or orders that have not yet settled. Use cases - A restaurant or snack-bar menu with categories and photos. - A services catalog (appointments, plans, packages) with a price per item. - A list of physical products for a store that sells over WhatsApp. - A catalog of digital products or courses to send directly to the customer. Tips, limits & best practices - Price in major units: type 4.97 to mean R$4.97. The platform does not divide by 100 — the value you record is the value displayed and charged. - An order total is the sum of price × quantity for each item — also without dividing by 100. - Use sharp, publicly reachable images: the WhatsApp sync needs to be able to download them. Images hosted at addresses that go offline won't be imported. - Keep names and descriptions clear — they appear to the customer when you send the product. - In the report, read Budget as the proposal recorded on the deal and Realized as paid order items. An item without a paid order is not included in realized revenue. Troubleshooting - Price shows wrong (e.g. R$0.05 instead of R$4.97): confirm you typed the value in major units; don't multiply or divide by 100. - Image doesn't show: check that the file is valid and the image address is reachable. - A variant cannot be archived or deleted: choose another active variant as the default first. - The wrong image is shown for a variant: edit the product and select one of its gallery images for that variant, or choose the primary-image fallback. - Product won't disappear from lists: mark it unavailable instead of keeping it visible when it's not for sale. - A paid sale did not decrement stock: confirm that the sale line points to a variant with inventory tracking enabled. Records that were only imported or adopted as history remain available for review and intentionally do not rewrite the current balance. - The decrement is shown as failed after the automatic retries: an administrator should open Catalog → Import & Sync → History, locate the Automatic stock decrement run, open its detail, and click Retry stock decrement. The run identifies the charge or order and shows only a sanitized technical reference, without gateway credentials or payload. Retrying is safe: the sale's unique receipt prevents a second decrement if the previous attempt completed ambiguously. If the run is Pending or Processing, wait for the worker instead of clicking again. If the reason reports a fractional quantity, correct the source line to whole units — or disable tracking only when the variant is legitimately fractional — before retrying; the platform never rounds that quantity. See also - Catalog & Commerce overview - Sync and WhatsApp Business Catalog - Send a product and receive orders in the conversation

Sync and WhatsApp Business Catalog

Overview Sync connects your native catalog to Meta's WhatsApp Business Catalog. Once bound, products exist in both places and can be kept in two-way sync: what you record on the platform is pushed to Meta, and what exists in Meta's catalog can be imported into the platform. This is what makes it possible to send native products on WhatsApp, open the catalog inside a conversation, and receive orders from the customer's cart — all from a single, up-to-date catalog. Prerequisites - A connected, working WhatsApp (Cloud API) Inbox. - A catalog set up in your Meta business account (Business / Commerce Manager). - The Catalog & Commerce module enabled and permission to manage sync sources. - A native catalog with products recorded (recommended before the first sync). Step by step 1. In the Catalog area, open the sync sources configuration. 2. Create a source of type WhatsApp Business Catalog (Meta) and select the Meta catalog to bind. 3. Bind the source to the matching WhatsApp Cloud inbox — the access credential is reused automatically from that inbox, with no need to enter a separate token. 4. Set the sync interval (how often the platform checks Meta's catalog). 5. Run the first sync and review the imported/updated products. 6. From then on, changes flow both ways according to the configured interval, and you can force a manual sync whenever you want. Settings & options - Bound Meta catalog: which catalog from the business account is connected to the source. - Inbox: the WhatsApp Cloud inbox used for the credential and to send products. - Sync interval: how frequently automatic syncs run. - Manual sync: a button to run the sync right away. - Two-way: products recorded on the platform are published to Meta; Meta products are imported into the platform, matching identifiers on each side. Publish safely and review validation Each sellable variant is published as its own Meta catalog item. Variants of the same product stay grouped, but have separate identities so price and availability never bleed between sizes, colors, or other options. Before sending, the platform blocks the variant and shows the reason when a Meta requirement is missing: name, description, brand, public HTTPS link, price, currency, or a public HTTPS image at least 500 × 500 pixels. Complete the fields on the product and try again — a local block is never treated as a synchronized product. After Meta accepts a batch, it still validates the content asynchronously. Open the product and review the status on each variant: Waiting for validation, Validated, Rejected, Publishing blocked, or Inconclusive validation. Treat an item as available on Meta only after it is Validated; a rejection message points to the field that needs correction. Inconclusive validation means Meta answered without a recognized result. Transient states such as “started” are checked again for up to four minutes; if validation timed out appears, publish the product again and follow the execution history. On the way back in, the items of one group return to the same product, each as its own variant. The platform recognizes the product by its group and by each variant identifier, so a re-import updates the existing product instead of creating a copy. Assisted reconciliation of remote items When editing an outbound or two-way Meta source, Assisted Meta catalog reconciliation lists remote items that do not have a local variant with the same retailer_id. It is a review step only: 1. Refresh the list and verify the name and identifier of every potential orphan. 2. Select only items that should really leave the Meta catalog. 3. Click Request selected removal and confirm in the dialog. Nothing is removed by opening or refreshing the list. The platform re-reads the catalog when you submit, rejects a selection that has changed, and also rejects a batch above the 10% remote-catalog safety limit. Even after the request is accepted, Meta validates the batch: the UI says “submitted for validation”, not “removed”, until the remote confirmation arrives. Use cases - A store that already has a catalog in Meta and wants to bring it into the platform to serve and bill. - An operation that prefers to record products on the platform and publish them automatically on WhatsApp. - A team that maintains a single catalog and wants to avoid updating prices in two places. Tips, limits & best practices - Automatic credential: when you bind the source to the WhatsApp Cloud inbox, the platform uses that inbox's credential — you don't need to register a token just for the catalog. - Images must be reachable: the sync downloads product images. If the original image is hosted at an address that goes offline, it won't be imported. Keep images in a public, stable HTTPS location; use at least 500 × 500 pixels for publishing. - Major-unit amounts: prices stay in major units (4.97 = R$4.97) on both sides. - Run the first sync outside peak hours so you can review the result calmly. Troubleshooting - Imported products without images: the original image may be unreachable; ensure a public address and run the sync again (each run re-attempts the image download). - Nothing syncs: confirm the source is bound to a valid WhatsApp Cloud inbox and that the selected Meta catalog is the right one. - A change didn't appear on the other side: wait for the sync interval or run a manual sync. For publishing, open the variant and check whether Meta validation is waiting, blocked, or rejected; an accepted batch response is not yet catalog confirmation. - Validation timed out: Meta did not provide a final result during the automatic checks. Publish the product again; if the warning persists, inspect the item in Meta Commerce Manager. - An item is not listed in reconciliation: remote items without a retailer_id are never offered for automated removal. Locate those items directly in Meta Commerce Manager. See also - Native catalog: products, categories, images and prices - Send a product and receive orders in the conversation - Catalog & Commerce overview

Catalog & Storefront in the WhatsApp inbox

Overview Having a catalog created and synced on Meta is not the same as having the storefront turned on for your WhatsApp number. These are three different things, and all of them must be in place before a product can be sent in a conversation: 1. The catalog exists in your Meta business account and has published items. 2. The catalog is linked to your WhatsApp Business Account (the WABA). 3. The storefront is visible on the number — this is the step that usually goes unnoticed, because Meta creates every number with the storefront turned off by default. When step 2 or step 3 is missing, the catalog looks perfect in Meta's manager, but sending a product in the conversation fails — usually with error #131008. The Catalog & Storefront tab exists to make this visible. It lives inside the inbox settings, reads the state live from Meta, and shows in simple rows what is ready and what is missing. A single button — Turn on storefront for this number — takes care of step 3. The tab owns the commerce of the number. Product synchronization (mapping, scheduling, history) stays in the Sync Studio, inside the Catalog module. Prerequisites - A WhatsApp (Cloud API) Inbox. The tab does not appear for WhatsApp Web inboxes or other channels — the storefront is a Cloud API feature. - A catalog on Meta with published items. If you don't have one yet, create and sync it first from the Sync Studio. - Administrator permission on the inbox, inside the platform. - The Meta connection needs permission over the catalog and over the WhatsApp Business Account. Without it, reading works only partially and activation is refused by Meta. Step by step 1. Open Settings → Inboxes and select the WhatsApp Cloud API inbox. 2. Open the Catalog & Storefront tab. 3. Read the diagnostics. Each row answers one objective question: which catalog is selected, whether it is linked to the WhatsApp Business Account, whether the storefront is visible on the number, whether the cart is enabled, how many items the catalog has, and when it last synced. 4. If no catalog is selected yet, choose the catalog this number should use. 5. If the storefront is off, click Turn on storefront for this number and confirm. 6. Reload the diagnostics and confirm that the link and the storefront now show as active. 7. Open a conversation and send a product to validate end to end. Settings & options - Selected catalog — which Meta catalog this number uses. It is the source of the products you send in the conversation. - Linked to the WhatsApp Business Account — whether the catalog is associated with the WABA. Without the link, the number cannot see the products, even though they exist. - Storefront visible on the number — whether the storefront is on for this specific number. This is what the activation button changes. - Cart enabled — whether the customer can build a cart and send an order. With the cart off, the customer still sees the products but cannot complete an order over WhatsApp. - Items in the catalog — how many products Meta sees today. A count of zero almost always means the synchronization did not complete. - Last sync — when products were last pushed to the catalog. - Turn on storefront for this number — the only button that writes to your Meta account. Nothing is changed there without that click: opening the tab only reads the current state. Use cases - New inbox: you have just connected the number, the catalog is already synced, and you want product sending ready before the first conversation. - Failing sends: an agent reports they "can't send a product". The tab shows in seconds whether the problem is the link, the storefront or an empty catalog. - Several numbers: each number has its own storefront. When you open a new number under the same business account, you only repeat the activation — the catalog stays the same. - Periodic audit: before a campaign, checking the item count and the last sync avoids advertising a product Meta cannot see. Tips, limits & best practices - The storefront starts off. That is Meta's behavior, not a platform failure. Every new number needs the activation once. - Activation is explicit. The platform never turns the storefront on by itself, not even during a sync. The write happens only when you click the button. - Reading is live. The values come from Meta at the moment the tab opens, not from a cache. If someone changes something in Meta's manager, reloading the tab already shows the new state. - Storefront is per number; catalog is per business account. The same catalog can serve several numbers, but each number needs its own activation. - Syncing does not activate. A successful sync in the Sync Studio publishes products but does not turn the storefront on. They are independent steps. - Cart and orders: to receive structured orders in the conversation, the cart must be enabled on top of the storefront. Troubleshooting - Error #131008 when sending a product — Meta reports that a required parameter is missing for the product message. In practice, the number has no usable storefront: the catalog is not linked to the WhatsApp Business Account, or the storefront is off on the number. Fix: open the Catalog & Storefront tab, select the catalog and click Turn on storefront for this number. - Error #131009 when sending a product — Meta reports that a value sent is invalid. Usually the product is not in the linked catalog: the item was never synced, it was archived, or it belongs to another catalog. Fix: check in the diagnostics that the selected catalog is the same one the product was published to, review the item count and run the sync in the Sync Studio. - The tab does not appear — the inbox is not a WhatsApp Cloud API inbox. Storefront and native catalog are Cloud API features. - Activation is refused — the Meta connection does not have enough permission over the catalog or over the WhatsApp Business Account. Review the permissions in Meta's manager and try again. - Items in the catalog = 0 — the sync did not complete, or the products were rejected by Meta. Check the sync history in the Sync Studio. - Storefront active, but the customer cannot complete the order — the cart is most likely disabled. See also - Sync and WhatsApp Business Catalog - Send a product/list and receive orders in the conversation - Native catalog: products, categories, images and prices

Send a product/list and receive orders in the conversation

Overview With the catalog ready and synced, you can send products to the customer inside the conversation and receive their order back as a structured card. Instead of describing prices in text, you send the right item; when the customer builds a cart on WhatsApp, the order arrives organized, with items, quantities and a total — plus shortcuts to generate the charge. There are three ways to show products: single product, product list and open the catalog. And one way to receive: the order that becomes a card in the conversation. Prerequisites - A native catalog with products and, for native WhatsApp features, active sync with the WhatsApp Business Catalog. - A WhatsApp (Cloud API) Inbox — the native product, list and order formats work on the Cloud API. - An active storefront on the number, in the inbox's Catalog & Storefront tab. Meta creates every number with the storefront turned off: without activating it, sending a product fails with error #131008. See Catalog & Storefront in the WhatsApp inbox. - For an interactive single-product send over WhatsApp Web, an active Web inbox is enough; the native cart and order remain exclusive to the Cloud API. - To charge the order: the Payments module configured. Step by step 1. Open the conversation with the customer. 2. In the composer, choose send product and select an item (single product) or build a product list. When there is more than one variation, choose the right one; when that variation has prices in more than one currency, choose the currency too. You can also open the catalog for the customer to browse. 3. On the Cloud API, the customer can add items to the cart. On WhatsApp Web, they use I'm interested or View product on the interactive card. 4. When the customer completes the cart, the order arrives in the conversation as an order card with items, quantities and the total. 5. On the order card, use Create charge or Create subscription to bill exactly what was ordered — the amount is pre-filled with the order total. 6. Track the payment in the Payments module; once confirmed, the customer receives the confirmation. Settings & options - Single product: sends a specific item from the catalog. - Variation and currency: the card uses the chosen variation and its registered price for the chosen currency; the selection never silently returns to the first variation. - Product list: sends several items grouped into one message while preserving each product's chosen variation and currency. - Open catalog: invites the customer to browse the catalog on WhatsApp. - Order card: shows items, quantities, total and the customer's notes. - Order shortcuts: Create charge (one-off payment) and Create subscription (recurring), already pre-filled with the order amount. - Referred product: when the customer replies quoting a product, an indicator of the quoted item appears next to the message. Use cases - A customer asks about a specific item — you send the single product with photo and price. - Consultative support — you send a list with the best options for the customer to choose from. - The customer builds the cart themselves — the order arrives ready and you bill in seconds. - A recurring sale (subscription/plan) — the order becomes a subscription with the agreed amount. Tips, limits & best practices - Charge what was ordered: the card uses the order total agreed with the customer; the amount is not recalculated from the current catalog prices. Billing the order respects exactly what the customer built. - Major-unit amounts: the total is the sum of price × quantity (4.97 = R$4.97), without dividing by 100. - Cloud API: the native format is used only when the chosen variation is published with its own retailer_id and uses the published currency. Otherwise, the platform sends the enriched card with the exact variation and price instead of substituting an item. - WhatsApp Web: a single product is sent as an interactive card with an I'm interested button and, when the record has a public link, View product. This send requires no additional license. - Review the order before charging: items, quantities and total. Troubleshooting - The send failed with error #131008: the storefront is not usable on the number — either the catalog is not linked to the WhatsApp Business Account or the storefront is turned off. Open the inbox's Catalog & Storefront tab, select the catalog and click Turn on storefront for this number. Details in Catalog & Storefront in the WhatsApp inbox. - The customer didn't receive the native product/list: confirm the inbox is WhatsApp Cloud API and that the catalog is synced. Also check whether the selected variation has its own retailer_id; without it, receiving the enriched card is the expected fallback. - The order didn't become a card: check that the order came from the WhatsApp cart; orders from outside WhatsApp follow the e-commerce lifecycle. - Wrong amount when charging: the card pre-fills the order total; if you edit it manually, remember major units (don't divide by 100). See also - Catalog & Storefront in the WhatsApp inbox - Native catalog: products, categories, images and prices - Sync and WhatsApp Business Catalog - E-commerce lifecycle

E-commerce lifecycle: Kiwify/Hotmart/Nuvemshop/Shopify webhooks

Overview The e-commerce lifecycle connects external platforms — Kiwify, Hotmart, Nuvemshop and Shopify — so that sales events arrive inside your support. When something happens on the external platform (abandoned cart, PIX/boleto generated, purchase approved, declined or refunded), Conversa Labs receives the webhook, normalizes the event, and shows a card in the customer's conversation, with payment data when available. With this, you recover sales without switching tools: the team sees the purchase stage right in the conversation and can trigger automatic Follow-ups to win back anyone who didn't complete. Prerequisites - The Catalog & Commerce module enabled and permission to configure commerce sources. - Access to the external platform (Kiwify, Hotmart, Nuvemshop or Shopify) to set up the webhook. - For automatic recovery: the Follow-ups module configured with event-triggered sequences. Step by step 1. In the Catalog & Commerce area, create a commerce source for the desired platform. 2. Copy the complete webhook URL generated for that source. It includes both the account and the source; do not remove either segment. Also configure the verification secret. On Kiwify, automatic registration can generate and save the token; on Hotmart, enter the application's Hottok. 3. Paste the URL into the external platform's panel (or use automatic registration when available, for example on Kiwify and Nuvemshop). 4. Make a test sale (or a test cart) to confirm the event arrives. 5. See the event card appear in the customer's conversation, with items, amounts and the payment link/data depending on the stage. 6. Set up event-triggered Follow-ups (for example, "abandoned cart") to recover the sale automatically. Settings & options - Commerce source: one per platform, with its own webhook URL and verification secret. - Automatic webhook registration: available on some platforms (e.g. Kiwify and Nuvemshop); on the others, setup is manual in the platform's own panel. - Event card: shows the purchase stage and, when the platform exposes it, PIX/boleto data and the checkout link. - Commerce variables: data from the latest event is available for use in Follow-up messages (payment link, amount, PIX/boleto code, etc.). Choose which events to receive When you edit the source under Catalog → Sync sources → edit the source, the Events section lists the events that platform sends and lets you map each one to a lifecycle stage — or set it to Off (ignore) to drop it entirely. Every enabled event flows through the rest of the platform: automations, flows, webhooks, Follow-up and the CRM. The mapping is what decides which stage it becomes. A prominent Abandoned cart recovery switch turns the platform's abandoned-cart event on and off — it is what drives the recovery cadence in Follow-up (the commerce.cart_abandoned trigger). Available for: | Source | Events you map | |---|---| | Hotmart | purchase, cart, subscription and members-area events | | Kiwify | its 10 real triggers: compra_aprovada, pix_gerado, boleto_gerado, compra_recusada, compra_reembolsada, chargeback, carrinho_abandonado, subscription_renewed, subscription_late, subscription_canceled | | Nuvemshop | the order's payment_status values: paid, authorized, pending, refunded, partially_refunded, abandoned — the Nuvemshop webhook carries only the ID, so the stage comes from the order's payment status | | Generic sources | the documented event names from your system. You explicitly set the event field, ID, buyer/product/item paths and the canonical stage for each event; nothing is inferred from a platform name | Managed sources with no verified sale-lifecycle contract, such as Mercado Livre and OLX, do not show an event selector. Sources powered by the generic connector — including a custom Shopify/API setup — show the signed generic webhook configuration and only receive the events you explicitly map. The defaults are sensible: you only change the mapping if you want a different stage, or if you want to ignore an event. Use cases - Abandoned cart: triggers a Follow-up sequence reminding the customer to finish. - Pending PIX/boleto: resends the payment code and follows up until confirmed. - Approved purchase: confirms with the customer and unlocks the next support step. - Refund/decline: alerts the team to handle the case right in the conversation. Tips, limits & best practices - What each platform exposes varies: some send the PIX code and the boleto line in the event (full recovery inside the conversation); others only provide the checkout link — in those cases, the card shows the link for the customer to complete. - Amounts and formats differ per platform: Conversa Labs normalizes each event; you don't need to worry about conversion — the card already displays the correct amount. - Verification secret: keep it configured so only legitimate events from the platform are accepted. Hotmart, Kiwify, Nuvemshop and generic webhooks are rejected when no secret is configured. A generic sender must also provide the documented timestamped signature and one stable delivery ID per event. - Combine with Follow-ups to automate recovery instead of relying on manual action. Troubleshooting - The event doesn't appear: check that the complete webhook URL was pasted correctly into the platform and that the verification secret is configured and matches. - I don't see PIX/boleto on the card: not every platform exposes that data; when it doesn't, the card carries the checkout link. - Duplicate events: generic deliveries with the same delivery ID are acknowledged only once. If something looks off, confirm that the sender reuses that ID on retries and that only one webhook is configured for the same source. See also - Catalog & Commerce overview - Send a product and receive orders in the conversation - Native catalog: products, categories, images and prices

Configure the sales-recovery messages

Overview Each produced sales-recovery stage (abandoned cart, payment pending, payment declined and overdue) sends a card to the customer. On this screen you customize that card's copy per stage and per language, with no AI automation involved. Anything you leave untouched keeps the shipped Conversa Labs message — so you only change what you want. Due soon remains reserved for compatibility with historical data, but it has no event producer and is not offered for configuration or automation yet. Beyond the body, you also edit the card's auxiliary labels and configure, per stage and per language, the approved WhatsApp template used when the 24h window is closed. Prerequisites - Sales recovery must be enabled on the account. - Administrator permission to change settings. - To configure sending outside the window: a WhatsApp Cloud inbox with templates approved by Meta. Step by step 1. Open Sales recovery → Messages. 2. Pick the language in the selector at the top. It opens on the account language and lists every language the installation enables (up to 40), showing how many already carry your copy ("N of M languages with content"). 3. For each stage, write the body in Markdown. Leave it empty to use that language's shipped message — the Default badge means the stage is inheriting the built-in copy. 4. Use the variables button ({x}) to insert data like {{contact.name}}, the amount and the pay link from the customer's latest event. The picker offers only the variables that actually resolve in that message. 5. Open the Auxiliary labels block to adjust the card's 6 captions and button texts. 6. The Outside the 24h window (WhatsApp Cloud) block shows up open, right under each stage. Pick the approved template for that stage in that language, map the {{1}}, {{2}}… parameters and, if the template has a link button, fill in its value. If no template exists yet, use Create from my text to generate one from the body you wrote. 7. Check the preview per channel and, if you want, use Send test to deliver the message to a real conversation. 8. Save messages — including after creating a template, because creating the template does not store the configuration. To revert a stage to the default, use Restore default — the customization is removed on the server, not only on screen. Settings & options Languages and fallback Language is no longer a fixed trio of tabs: it is a selector with every language the installation enables. At send time, Conversa Labs looks for the copy in this order: 1. the contact's language; 2. the same base language (for example, pt_BR ↔ pt); 3. the account language; 4. the shipped default message. Auxiliary labels The card is more than the body: it carries captions and button texts. The 6 auxiliary labels sit in a collapsible block under the body and follow the same language and restore rules. Outside the 24h window (WhatsApp Cloud) The block appears open and inline right under each message type — it is not a section you have to expand. The template is per message type and per language — each stage has its own, instead of a single template for the whole module. It gives you: - Pick the approved template from the catalog. - Sync from Meta and Create from my text are always visible. When the action is unavailable, the button appears disabled with the reason written next to it: the inbox is not WhatsApp Cloud, the account does not have the WhatsApp Inbox Suite, or your profile does not manage inboxes. - Sync from Meta refreshes the list of approved templates. - Create from my text generates the template from that stage's text in that language, submitting it to Meta as a UTILITY template, converting each {{ variable }} into {{1}}, {{2}}… and pre-mapping them. With no text to generate from, the button is disabled and the screen asks you to write the text first. - After submission the template is not approved yet: it appears in the selector marked awaiting approval and only starts delivering once Meta approves it and you sync. Submitting again with the same name replaces the pending draft instead of failing. - Creating the template does not save the configuration — click Save messages to store the mapping. - The {{n}} parameter mapping and the link-button field, when the template has one. - Native buttons: by default the payment link goes out as a button on WhatsApp instead of a bare URL in the text. Turn it off per message type under Delivery → Native buttons. On WhatsApp Cloud, Meta delivers a single button, so the PIX code stays in the body; on WhatsApp Web both go out. - Delivery: picks which WhatsApp inbox's approved-template catalog is browsed. Everything that depends on that inbox — why syncing/creating is unavailable, how many templates were filtered out, the link to manage them, and the Sync from Meta button — is stated once there, not repeated under every message. The send itself still leaves through the conversation's own inbox. Templates whose header requires media or a variable are not listed here — this send has no way to fill that header — and the screen states how many were left out. They remain usable from the inbox's own Templates tab, linked directly from this screen. Important notes: - WhatsApp Web (WazMeow) has no 24h window — for those inboxes the template block does not appear. - 360dialog can select a template but cannot create one — creation is Cloud-only. - Meta matches name + language + approved. A template in the wrong language is flagged on screen and would be rejected on send. Preview and test send The preview is rendered server-side, per channel, and shows only the channels the account actually has. It also displays the resolved out-of-window template, with the values each parameter will carry. Send test delivers the message to a chosen conversation, honouring the 24h window: if the window is closed and no template is configured, the test is skipped with the reason stated on screen. Variables The picker lists only what resolves in that context. Contact, account, conversation, inbox, agent, CRM and organization data now really render (they used to come out blank), alongside the commerce event data that triggered the card. Tips, limits & best practices - Bodies are Markdown and each channel shows what it supports: attachments are dropped on LINE, TikTok and X; raw HTML disappears in email and the widget; *bold* on WhatsApp shows as a pair of asterisks. The preview spells this out so you never write something that only works on one channel. - Customize your audience's main language first, then the others — the "N of M" counter helps you track coverage. - Configure the out-of-window template in the same language as the body: they are pairs, not a single global setting. - After "Create from my text", the template sits awaiting approval at Meta — use Sync from Meta to see when it is approved and starts delivering. Troubleshooting - The message went out as the default copy: the stage carried the Default (empty) badge in that language, or the contact's language has no copy and the fallback landed on the shipped default. - Nothing was sent outside the window: confirm there is an approved template configured for that stage and that language. - The template shows as flagged: it is in a different language from the card — swap it for an approved template in the right language. - "Create from my text" is disabled: the reason is written next to the button — the inbox is not WhatsApp Cloud (on 360dialog you pick an already-approved template), the account does not have the WhatsApp Inbox Suite, your profile does not manage inboxes, or there is no text in that stage and language to generate the template from. - I created the template but it doesn't show up / isn't used: right after submission it sits awaiting approval — it only delivers once Meta approves it and you use Sync from Meta. Also confirm you clicked Save messages: creating the template does not store the configuration. - I can't find a template in the list: templates with a media header or a header variable are not listed here; use them from the inbox's own Templates tab. - The test send was skipped: the conversation was outside the 24h window and the card had no template configured — the screen states the reason. See also - E-commerce lifecycle: Kiwify/Hotmart/Nuvemshop/Shopify webhooks - WhatsApp Inbox Suite: Templates, Flows and Calls

Sales recovery: card delivery, conversation policy and metrics

Overview Sales recovery is the layer that makes sure a commerce event always becomes a visible action. Previously the recovery card could die in silence: if the customer had no open conversation, or if the message fell outside the WhatsApp window, nothing happened and nobody found out. Now every lifecycle event — from Kiwify, Hotmart, Nuvemshop or the native gateway (Asaas / Mercado Pago) — goes through three guarantees: 1. A conversation resolver decides where the card goes, using a policy you choose. 2. A send-window guard checks whether the channel accepts the message at that moment. 3. A delivery outcome is recorded on every exit path: sent, skipped or failed, always with a readable reason. The practical result: you open the Sales recovery page and see how many opportunities were reached, how many were not, and exactly why — instead of discovering weeks later that an entire cadence never went out. When each stage fires | Stage | Fires when | Actionable? | |---|---|---| | Abandoned cart | the customer built a cart/checkout and did not complete it | Yes | | Payment pending | a PIX or boleto was generated and is still unpaid | Yes | | Payment declined | the card was refused by the issuer or by anti-fraud | Yes | | Overdue | the due date passed without payment | Yes | | Order placed | the order was registered on the platform and remains pending | No (does not settle) | | Payment confirmed | the payment was approved | No (settlement) | | Refunded | the amount was returned to the customer | No | | Chargeback | the customer disputed the charge with the issuer | No | | Subscription late | the subscription renewal failed or is late | No | | Subscription canceled | the subscription was terminated | No | The four actionable stages are the ones that count toward the recovery rate. Refunds and chargebacks never count as recovery — they are the opposite of it. due_soon remains a recognized stored value for backwards compatibility, but no current connector or native gateway produces it. It is therefore not offered in automatic recovery or the Follow-up picker. Prerequisites - The Sales recovery feature (commerce_recovery) enabled on the account. It ships OFF by default; ask whoever administers the installation to turn it on. - An administrator or agent profile on the account. Both can open the recovery page, change policies and resend cards — there is no separate per-module permission here. - At least one commerce source connected (Kiwify, Hotmart, Nuvemshop) or a native gateway configured (Asaas / Mercado Pago), so that events arrive. - To send outside the WhatsApp window: an approved template on the matching inbox. With the feature off, the new page, the sidebar panel and the metrics stay hidden. Delivery itself (conversation policy, recorded outcome) keeps working behind the scenes — it is behavior-preserving infrastructure. Step by step 1. Open Sales recovery from the commerce module menu. 2. Check the actionable stage funnel: it uses the same four stages as attempted and recovered metrics; settlements, refunds and cancellations do not enter this funnel. 3. Look at the delivery block: sent, skipped, failed and not attempted. 4. Open the reasons list — it is ordered from most to least frequent. That is your fix list, in order of impact. 5. Click an event to see the card, the target conversation and the delivery history. 6. If the card did not go out for a reason you have already fixed (channel reconnected, template approved), use Resend. If you need to bypass the duplicate guard, tick force. 7. Adjust the conversation policy on the automation/macro action so the next event of the same type does not fall into the same reason. Settings & options The conversation policy (the most important choice) When the card must be delivered, the platform needs to know which conversation to write into. You have three options: | Policy | What it does | When to use it | |---|---|---| | Use an existing conversation (default) | Delivers into the contact's most recent conversation. Never creates one. If there is none, the card is skipped with reason no_conversation. | The safe default — it is exactly today's behavior. Nothing changes for existing setups. | | Create one if needed | Uses the existing conversation when there is one; creates a new one when there isn't. | When you want maximum reach and accept that a new conversation becomes visible to the customer. | | Only this conversation | Delivers strictly into the conversation where the rule fired. Never looks elsewhere, never creates. | When the card only makes sense in the context of that specific conversation. | Why "create one if needed" is opt-in: creating a conversation is an action that is visible to the customer and to the team's queue. It shows up in the inbox, counts in reports and can trigger notifications. That is why Conversa Labs never does it on its own — you have to choose it. The WhatsApp 24-hour window (no half-truths) WhatsApp only allows free-form messages within 24 hours of the customer's last message. Outside that window: - Without an approved template → the card is skipped, with reason whatsapp_window_closed. It is not delivered. Conversa Labs would rather record the reason than queue a message WhatsApp is going to reject. - With an approved template → delivery degrades to the single template message. You reach the contact, but not with the full rich card: only what the approved template allows. WhatsApp Web has no window. WhatsApp Web inboxes deliver normally at any time — the 24-hour restriction belongs to the official WhatsApp Business API, not to the platform. Exception: hybrid pair. If you run a hybrid pair with Cloud as primary and out-of-window routing to WhatsApp Web, the send goes out in full as a Web session message — it is neither converted to a template nor skipped. Do not expect whatsapp_window_closed in that setup. Other channels The card always carries the payment link in the message body, never only as an attachment. This is deliberate: LINE, TikTok and X (Twitter) drop or reject attachments. If the link travelled only in the attachment, the customer would receive a message missing the one thing that matters. Card delivery and the "not attempted" queue The panel shows the delivery split — sent, skipped, failed and not attempted. The "not attempted" bucket is the one that never got a card at all: no rule ever acted on that event. It is no longer a dead number: you can filter the timeline by it and queue the pending ones in bounded batches, oldest first, up to 50 at a time. The action returns accepted/queued, not a delivery total. Processing happens in the background and the actual sent, skipped or failed outcomes appear later in the timeline. It never opens a new conversation: an event with nowhere to deliver is recorded as skipped with the corresponding reason. Imported or gateway-adopted history is always excluded from this queue. Why "Recoveries attempted" can read 0 with a full list. The count only considers actionable events whose card was recorded as sent. If no card was ever sent, the denominator is zero — the page is not broken, it is telling you nobody has been reached yet. Automatic recovery by stage (default off) Under Messages → Automatic recovery by stage, enable only the live stages you want Conversa Labs to queue automatically. Every switch starts off. The immediate lifecycle event queues the card, and a five-minute backstop repairs a missed queue handoff. Both paths re-check the switch before delivery, reuse an existing conversation, respect the WhatsApp 24-hour window, and defer when the connection's safe send rate is full. Imported and adopted charges are history: they stay visible for audit/reporting with the Historical — sending blocked badge, but are excluded from every customer send. Automatic recovery, manual backlog drains, the backstop, Follow-up, forced resend, automations and Maestro cannot bypass this guard. The order of the card's messages The card is a sequence: summary → pay button → PIX copy-and-paste → QR code → boleto → digitable line. That order is now guaranteed on delivery — each message used to be sent on its own and they could arrive shuffled (the raw PIX code reaching the customer before the message telling them to copy it). Under Messages → Delivery you set the pause between the card's messages. Leave it blank to use the channel default: on phone-linked WhatsApp (WazMeow) it is 1 second, to space the burst out and not look like an automated blast; on other channels there is no pause. Opening the conversation and resending Every live row has Open conversation (jumps straight to that customer's thread) and Resend card. The resend targets the conversation by its public identifier — it can never land on the wrong customer. If the event has no conversation yet, the dialog says so before you confirm that one will be opened with the customer. Historical rows do not show resend, and the API also refuses it even with force. Use cases - A pending PIX that went cold: the customer generated the PIX yesterday and vanished. The card resends the code into the existing conversation, without creating new noise. - A wave of card declines: an issuer knocked down several transactions. You filter by payment_declined, see they were all skipped with channel_unavailable, reconnect the channel and resend in bulk. - An abandoned cart from someone who never talked to you: a new contact, no conversation. With the "create one if needed" policy, the card opens the conversation and starts the support thread. - Cadence audit: the reasons list shows 60% of sends died on whatsapp_window_closed — the clear signal that this cadence needs an approved template. Tips, limits & best practices The delivery outcomes and what to do about each Every event ends in one of these states: sent, skipped, failed — or not attempted, when no rule ever acted on it. | Reason | What it means | What to do | |---|---|---| | no_contact | The event arrived with no identifiable contact (the source platform sent no usable phone/email). | Check the identification mapping on the commerce source. With no contact there is nobody to send to. | | no_conversation | The contact exists, but there is no conversation to receive the card and the policy is "use an existing conversation". | If you want to reach these cases, switch the policy to create one if needed. | | no_channel_inbox | There is no inbox for the channel the action asked for. | Connect that channel's inbox, or point the action at an inbox that exists. | | whatsapp_window_closed | Outside the 24-hour window and without an approved template. | Attach an approved template to the action. Or move the cadence inside the window. | | throttled | The channel's send limit was reached at that moment. | Space the cadence out. Large bursts on WhatsApp also increase the risk of a block. | | channel_unavailable | The channel is disconnected, expired or unavailable. | Reconnect the inbox and resend the affected events. | | sequence_not_published | The Follow-up sequence is still a draft. | Publish the sequence. Drafts never send — that is intentional. | | already_sent | The duplicate guard blocked it: this event already had a card recorded as sent. | Nothing, in most cases. If you really must send again, use Resend with force. | Integrating with external systems Every delivery outcome — sent, skipped or failed — is also emitted as the commerce_card_delivery account webhook event, carrying the canonical reason. That is how an external system (n8n, a CRM) reacts without polling: open a task when the reason is no_conversation, say, or try another channel when it is whatsapp_window_closed. Enable it under Settings → Integrations → Webhooks. The duplicate guard and explicit resend A single event creates and dispatches its card locally once. If an automation and a macro both try to send the same card, the second is skipped with already_sent — that is the local duplicate guard. Final provider delivery still has to be checked in the conversation/channel delivery state. Resending is always explicit and human: you open the event and click Resend. It preserves the record of the first send (original date and message) and only increments the resend counter — history is never erased. To cross the guard on purpose, tick force. How to read the recovery rate (honestly) The recovery rate is the share of actionable attempts recorded as sent and assigned to a later settlement for the same contact and the same order. Precisely: - Denominator: actionable events (abandoned cart, pending, declined, overdue) whose card was recorded as sent. - Numerator: later settlements with the same contact, source and external order/charge id. Paying a different order does not recover the first one. - A settlement counts once. If one order received several actionable cards, it is assigned deterministically to the latest attempt recorded as sent before settlement. Order placed never settles revenue: only payment_confirmed enters the numerator. - Events whose card was never recorded as sent are excluded from both sides. The sent state confirms local card creation and dispatch; it is not yet a final provider delivery receipt. - When nothing was attempted in the period, the rate shows as —, not as 0%. Zero percent would mean "we tried and failed"; the dash means "there was no attempt". This is correlation, not causation. The metric says "the customer paid after we reached out", not "the customer paid because we reached out". Some of those people would have paid anyway. Use the number to compare cadences against each other and to track a trend — do not present it as revenue attributed to a campaign. Recovered revenue uses the settlement's value and currency, not the value shown on the card. Totals are displayed separately per currency — BRL and USD are never added together or labelled as if everything were BRL. Values remain in each currency's major unit, with no hidden conversion. When the source did not report a currency, the interface states that absence explicitly. Troubleshooting - "Not attempted" on many events: no rule is acting on that stage. Create an automation or a Follow-up sequence for the stage in question. - Everything skipped with no_conversation: your base is contacts with no open conversation and the policy is the default. Switch to create one if needed — remembering the new conversation is visible to the customer. - Everything skipped with whatsapp_window_closed: the cadence is running outside the 24-hour window. Approve a template and attach it to the action, or move the trigger earlier. - Card delivered, but "poor": you are outside the window with a template. That is the correct behavior — WhatsApp only accepts the approved template in that situation. - Intermittent channel_unavailable: the inbox is dropping. Check the channel connection before resending in bulk, otherwise the resends fail for the same reason. - The customer received it twice: check whether an automation and a Follow-up sequence both cover the same stage, or whether someone used force on a resend. - The rate shows "—": no recovery card was recorded as sent in the filtered period. Widen the period or check the reasons list. - The page does not appear: the commerce_recovery feature is off on the account, or your user is neither an administrator nor an agent on it. See also - E-commerce lifecycle: Kiwify/Hotmart/Nuvemshop/Shopify webhooks - Catalog & Commerce overview - Send a product and receive orders in the conversation

Operate the recovery queue: owner, outcome, notes and ignored events

Overview The Sales recovery timeline separates two concepts: - Card delivery tells you whether the message was sent, skipped or failed. - Operational outcome tells you whether the opportunity ended as recovered or lost. You can also assign an owner, keep an internal note and ignore an opportunity that must receive no new actions. These fields are operational: they do not change the gateway stage, amount, settlement or delivery history. Prerequisites - The Sales recovery feature enabled on the account. - Permission to manage Commerce in the account. - At least one commerce event in the timeline. Step by step 1. Open Commerce → Sales recovery. 2. Find the event by its displayed customer, email/phone, external ID, source, stage, and value. This context remains available even when there is no conversation yet. 3. If the customer is missing or wrong, use Fix the sale customer and links. Select an existing contact or propose a new one, review the related charge and order, and apply only after preview. 4. Select Manage. 5. Under Owner, choose an agent from the same account or leave it unassigned. 6. Under Outcome, choose Recovered, Lost, or leave it unset while work continues. 7. Write an operational note, if needed, and save. 8. To remove the event from automatic actions, select Ignore and confirm. 9. To work on it again, open it and select Reopen opportunity. 10. To act on several opportunities at once, tick the row checkboxes — or use Select this page and Select every one in these filters — and choose Take out of recovery, Put back in recovery or Send card in the action bar. Every action confirms first, and whatever is refused is listed with its reason and stays selected so you can retry it. Settings & options Outcome The outcome is terminal and manual: | Value | Use | |---|---| | No outcome | the opportunity is still open or has not been reviewed | | Recovered | the team confirmed the operational recovery | | Lost | the team ended the attempt without recovery | The outcome does not replace the financial metric, which remains based on correlated settlement. Owner Only users who belong to the same account can be selected. Clearing the owner returns the event to the unassigned queue. Operational note The note accepts up to 2,000 characters, trims surrounding whitespace and is internal. Do not enter passwords, tokens, card data or other secrets. The audit records that the note changed, never its text. Sale customer and links Correction aligns the contact, charge, order, and recovery event in one transaction. It may update the organization, deal, and conversation, but never the stage, value, settlement, or external identifier. Any owner or affiliate impact requires audited confirmation in preview. For historical events, correction creates internal projections only and sends no card, message, automation, or external conversion. Ignore and reopen Ignoring is reversible. While ignored, the event: - remains visible with its history intact; - does not enter the pending-card queue or automatic cadence; - is not used as the contact's latest actionable opportunity; - refuses new sends and records the operational reason if an integration attempts one. Reopening removes only the block. Owner, outcome, note, stage and previous deliveries remain unchanged. Use cases - Distribute abandoned carts among agents without creating artificial CRM deals. - Mark a charge as lost when its negotiation ended outside the platform. - Ignore a test event or an opportunity whose customer asked not to be contacted again. - Reopen an event ignored by mistake without losing its previous note. Tips, limits & best practices - Use outcome for a human decision and the revenue metric for observed settlement; do not mix them. - Keep notes short and factual. Personal data in a note follows the account's export and anonymization rules. - Ignoring does not delete the event or reverse money. Use Fix the sale customer and links for customer associations, and the matching Payments operation for financial facts. - Before ignoring, check whether the source is only a channel failure that can be fixed and resent. Troubleshooting - The owner is missing: confirm that the user still belongs to the account. - The note will not save: shorten it to at most 2,000 characters. - The card is not sent: check whether the event is ignored; reopen it before trying again. - The event has no customer or points to the wrong contact: open Fix the sale customer and links, resolve the contact, and review the complete preview. This repair sends nothing to the customer. - The outcome did not change recovered revenue: this is expected; revenue uses correlated settlement, not the manual outcome. - I get a permission error: the profile needs the Commerce management permission. See also - Sales recovery: card delivery, conversation policy and metrics - Sales reconciliation

Sales reconciliation center

Overview The Reconciliation center collects historical records with missing or divergent links across charges, CRM orders, and commerce events. The automatic scan suggests relationships only from exact identity; similar names, values, or dates never join sales. Besides confirming a sale counterpart, Fix the sale customer and links aligns the contact, organization, deal and, when requested, the conversation, owner, and affiliate across the complete graph. It neither imports money nor changes amount, status, settlement, dates, or gateway identifiers. A new contact is only proposed in preview and is created after final confirmation. Prerequisites - The Sales recovery module must be enabled for the account. - You need Commerce management permission. - Connected integrations and historical imports must already have brought in the records to review. Step by step 1. Open Sales recovery in the commercial menu and choose Reconciliation. 2. Select Run scan. The analysis is queued and can take a moment for an account with extensive history. 3. Refresh the list and filter by state, source type, reason, or source ID. Each row combines the available customer, email/phone, organization, deal, owner or creator, affiliate, conversation, and primary source facts. Protected fields may be masked or omitted according to your role. 4. Open a pending item. Use Link only when the suggestion has the same gateway source and external ID. 5. When the customer is missing or divergent, choose Fix the sale customer and links from the queue row, charge, order, or event. Select an existing contact or propose a new one with a name and an email, phone, or document. Also decide how to handle an incompatible conversation. 6. Review the complete preview: reached records, changes, conflicts, historical projections, and credit/commission impact. Confirm attribution impact when present and apply. If any record changes between preview and confirmation, the entire operation is refused and must be reviewed again. 7. Confirm the link. The queue records the decision, operator, and time. 8. If the record is not a sale for this account, choose Ignore and add a reason when useful. 9. Use Undo if the decision must be reversed. The platform reverses it only when the link is still exactly as recorded, so it never overwrites a newer change. Settings & options - Pending: requires human review. - Linked: the relationship between existing records was confirmed. - Ignored: the account decided the item must not return to the queue. For charges, this is also honored by future imports and webhooks. - Duplicate: reserved for consolidating equivalent records. - Bulk actions: actionable selected items can be ignored or undone. Select every actionable item in these filters sweeps every page, skips decisions that cannot be bulk-mutated, and honors the 500-item limit. Every failed item is reported; a mixed selection is never presented as complete success. - Filters and sorting: remain in the page URL so the same view can be resumed or shared. - Sale graph correction: runs in one transaction. Either charge, order, and recovery are aligned or nothing changes. Missing historical projections remain internal and send no message, automation, or external conversion. On success, every still-pending queue row for the reached records is closed; a later scan also closes a previously reported issue that is already healed. Use cases - An imported Asaas charge already has an old order with the same payment ID. - A historic Hotmart or Kiwify event arrived before its matching order. - A test charge, another company's charge, or a non-sale record should stay out of future scans. Tips, limits & best practices - Always confirm gateway + external ID. Similar names, emails, dates, or amounts are not proof that two sales are the same. - Automatic correction never fuzzy-matches contacts or organizations. When no exact customer match exists, make an explicit manual choice in preview. - Use Fix customer and links for associations. Correct amount, status, settlement, or gateway identity through the financial operation or source system; those facts remain immutable here. - Review pending items before ignoring them in bulk. Ignored charges do not return until an explicit undo. - Reconciliation creates neither revenue nor commission. It uses the existing canonical keys so reports and credits are not counted twice. Troubleshooting - The queue is empty: run a scan, wait for it to finish, and check active filters. - There is no link suggestion: no exact counterpart exists. Keep the item pending or correct/sync its source. - I cannot undo: an operator or integration changed the link after your decision. Review the history instead of overwriting that newer change. - Correction was blocked by a conflict: the same external identity points to multiple charges or orders, or a conversation is incompatible. Resolve the indicated duplicate and create a new preview; nothing changed. - The preview became stale: a record changed before confirmation. Open correction again and review the new impact. - An ignored charge does not return: this is expected. Undo the decision in the queue before a new import or scan. - I cannot see Reconciliation: verify module enablement and Commerce management permission. See also - CRM Orders Registry - Import charge history - Sales recovery

Order ingest endpoint

Overview The Orders registry accepts sales that happen outside the platform. You get an ingest URL of your own and POST each order to it — from your own checkout, an ERP, an automation, or any gateway Conversa Labs does not integrate natively yet. The URL carries an opaque token that identifies the account. There is no other authentication header: whoever holds the URL can register orders in your account, so treat it like a password. Prerequisites - The Orders module must be enabled for the account. With it off, the URL answers 404. - Administrator (or CRM management permission) to open and rotate the token. Step by step 1. Open Orders and click Ingest endpoint. 2. Copy the ingest URL. The Token field is masked — use the eye to reveal it and the button next to it to copy the token alone. 3. Paste the URL into your source system and send the order as shown below. 4. Confirm the order shows up in the list. Resending the same external_id updates the order instead of creating another one. curl -X POST 'https://YOUR-INSTALLATION/public/api/v1/orders/ingest/YOUR-TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "gateway": "my_checkout", "external_id": "ORD-10231", "email": "customer@example.com", "title": "Pro annual plan", "amount": 149.9, "currency": "USD", "status": "paid", "ordered_at": "2026-08-11T10:00:00-03:00", "line_items": [ { "name": "Pro annual plan", "quantity": 1, "unit_price": 149.9 } ] }' Body fields | Field | Required | What it is | |---|---|---| | gateway | Yes | Identifies where the order came from (e.g. my_checkout, hotmart). | | contact_id / email / phone_number | Yes (one of them) | A reference to find or create the contact. Send name too to label a new one. | | external_id | No, but recommended | The order's id in your system. It is what makes a redelivery idempotent. | | status | No | One of pending, partially_paid, paid, overdue, failed, canceled, refunded. | | amount and currency | No | Total in major units (149.9 = $149.90) and the ISO-4217 currency. | | ordered_at and paid_at | No | ISO-8601 timestamps with offset. Without them, the arrival time is used. | | line_items | No | Items with name, quantity, unit_price and, when available, catalog_product_id, catalog_variant_id, discount and metadata. | | title, crm_item_id, affiliate_id, metadata, raw | No | Extras. The affiliate is only credited when it belongs to this account and is active. | Responses - 201 — {"status": "ok"}. Order registered or updated. - 422 — invalid_payload (missing gateway), contact_reference_required (no contact reference), invalid_order_status (status outside the list) or contact_unresolvable (the contact could neither be found nor created). - 404 — token missing, already rotated, or the Orders module is off for the account. Tips, limits and best practices - Always send external_id. Without it, a redelivery from your gateway becomes a duplicate order. - The endpoint is rate-limited per token. For large loads, send serially and back off on 429. - Rotating the token invalidates the old URL immediately. Do it only with the integration ready to take the new URL — and update it right away. - Amounts go in major units, with a decimal point. Do not send cents as an integer. Troubleshooting - Everything answers 404: the URL was rotated, or the Orders module is off for the account. - 422 contact_reference_required: the body carried no contact_id, email or phone_number. - The same order appears twice: it was sent without external_id, or with a different value on each attempt. - The affiliate got no commission: the affiliate_id does not belong to this account, or it is inactive. See also - Sales reconciliation hub - Commerce lifecycle

Sync your catalog with stores and marketplaces (Sync Studio)

Overview Sync Studio connects external e-commerce platforms and marketplaces to your native catalog in Conversa Labs. You set up sync sources that can: - Import (inbound) — pull the products from the external platform into the native catalog; - Publish (outbound) — push products from the native catalog to the external platform; - Keep both ways — combine import and publish on the same source. Sync Studio is different from two nearby features: - WhatsApp Business Catalog (Meta) sync links the native catalog to the Meta catalog so you can send products on WhatsApp — it has its own article. - The e-commerce lifecycle handles sale events (abandoned cart, pending PIX, approved purchase, refund) that turn into cards in the conversation — it also has its own article. Sync Studio is about the product catalog: what is for sale, with name, price, and images. Prerequisites - The Catalog & Commerce module enabled for your account. - Administrator permission to manage sync sources. - An account and access credentials on the external platform (token, app keys, or authorization, depending on the connector). - Recommended: a native catalog already organized into categories before publishing products outward. Step by step 1. In the Catalog area, open Sync Studio (sync sources) and click to create a new source. 2. Pick the connector/preset: Generic source, Shopify, WooCommerce, Magento, PrestaShop, Medusa, Mercado Livre, Nuvemshop, Hotmart, Kiwify, or OLX. 3. Set the direction: Inbound (import), Outbound (publish), or Both ways. 4. Authenticate the source according to the connector: - Mercado Livre — click Authorize; you are taken to the platform's login screen and, once you approve, returned to the fixed address /catalog_oauth/callback. Tokens are stored encrypted. - Hotmart / Kiwify — provide client_id and client_secret (plus account_id for Kiwify). Hotmart's basic_token remains accepted for legacy sources but is derived automatically when it is absent. Kiwify receives the credentials as a form and generates the token. - Generic source, Shopify, WooCommerce, Magento, PrestaShop, Medusa — choose Bearer, header, Basic (username and password), or URL query parameter authentication, then set the mapping. - Nuvemshop — paste the store token and the store_id. 5. Use Test connection for a saved Hotmart or Kiwify source. For a Generic source, use the live preview before saving: it makes the same call as sync and shows the response, actual parsed format, detected fields, mapping suggestions, and the first mapped record. 6. Save and click Sync now to run the first import (or Publish now for an outbound source). 7. Follow the paginated and filterable run history to see every sync, with times in the account timezone, direction, and result (items read, created, updated, skipped, or failed). The source list also shows safe counters and the latest error without exposing credentials. You can export the filtered history or explicitly selected runs as CSV; a partial export keeps failed run IDs visible. Settings & options - Connector / preset (source_type) — the origin/destination platform. - Direction — inbound, outbound, or both ways. - Credentials — stored encrypted, never shown back, and never written to logs. - Sync interval — how often the source is synced automatically (on top of manual, on-demand syncs). - Source state — a disabled source remains editable, but it does not accept webhooks or execute Sync now, Publish now, or queued pull, publishing, and Meta-validation work. Re-enable it only after reviewing its direction, capabilities, and credentials. - Pagination — large catalogs are walked page by page automatically (Shopify follows the Link header, WooCommerce advances by page); Generic JSON sources can configure the pagination style. If a run reaches the 200-page safety limit while another page still exists, it finishes as partial/truncated and preserves the cursor; the next run resumes from that point. The cursor is cleared only after the feed actually reaches its end. - Format and products root — Generic sources detect JSON, NDJSON, XML, CSV, or TSV from the response; you can choose a format manually. XML uses an XPath root (for example, //products/product); the other formats use a dot path. - Suggested mapping — the preview suggests, but never saves by itself, Portuguese, English, and Spanish field matches with confidence. Review before applying. In addition to name and ID, price, compare-at price, currency, SKU, stock, brand, and external URL are mappable; items.0.price selects the first array position. - Source webhook — each source has its own webhook address (/webhooks/catalog/:account_id/:source_id). Where the platform allows it, Conversa Labs registers it with one click via Register webhook (Nuvemshop, Kiwify); on others, you paste the address into the platform's own dashboard (Hotmart). - Inbound sync secret — used by bulk-sync API clients and masked in the source list. Rotate inbound secret invalidates the previous value immediately, records the operation when the native audit trail is enabled, and reveals the new value once; update every sender. - Platform webhook secret — a value provided by the platform to verify commerce events. It is write-only and never returned. To replace it, paste the new value while editing the source and update the external dashboard too; Conversa Labs does not invent or rotate that value on the platform. - Bidirectional Generic source — configure the event map and field paths in the screen itself. Inbound requests require X-Webhook-Signature: t=…,v1=…, reject a source without a secret, enforce a replay window, and deduplicate the delivery ID. An outbound-only source refuses inbound deliveries. For outbound, provide an HTTP(S) destination without credentials, query parameters, or fragments; authentication uses the shared HMAC secret. Events have searchable history, automatic retries, and confirmed single or bulk manual replay. A delivery that finds the source disabled, deleted, changed, or without its secret fails before any external request and records the reason in that history. - Generic webhook product, variation, and items — product and variation paths start at the event root. Set the items array path first, then map fields relative to each item. Blank fields are never inferred. Once mapped, values are snapshotted on the CRM order and sent only to account webhooks that opted in to commerce details. - Duplicate and loop protection — every imported item keeps the origin identifier (external_id / retailer_id) and the source. On later syncs this updates the same product instead of recreating it, and prevents echoing a change back to the source it came from. Import historical Hotmart or Kiwify sales For a saved Hotmart or Kiwify source, open Management → Backfill sales. Choose both dates within the provider window: up to 31 calendar days for Hotmart or 90 days for Kiwify. You can filter by product and by the provider's documented status/payment values; Kiwify also supports an affiliate filter. With no Hotmart status filter, its API returns only APPROVED and COMPLETE; choose another documented status explicitly when you need it. Click Preview sales: this call is read-only, uses each provider's official pagination, and does not write a contact, organization, event, or order. Review the local action for each row, then explicitly select at least one and at most 500 IDs before queuing the import. Omitting the selection never means “import everything.” The import matches only existing account contacts through exact fields from that sales-list endpoint. Hotmart Sales History provides buyer email (name/ucode are not identity matches); Kiwify GET /sales provides email, mobile and CPF. An organization is associated only through the exactly matched contact's current primary organization. It never guesses between conflicting matches or invents a CNPJ field that the Kiwify list does not document. A buyer without an existing contact, or a provider state without a faithful local meaning, is shown as non-importable; history import never creates people or companies. Imported lifecycle events and CRM Orders preserve the provider's order/approval timestamps and are marked historical. This suppresses customer messages, automation fan-out, commission and ranking credit, engagement, CAPI, stock effects, and outbound account webhooks while still populating the native order registry. Use Run history to inspect selected, created, updated, repaired, skipped and failed counts, the exact failed/skipped transaction IDs, and whether the global provider scan was truncated. An exact duplicate request reuses the active run, and execution is locked per account/source. A completed or partial run offers Undo import only while every locally created order/event is still untouched and unlinked; undo is atomic, never contacts Hotmart/Kiwify, and never deletes contacts or organizations. Use cases - Import a Shopify or WooCommerce store into the native catalog and serve customers from there. - Publish native products to a marketplace (when the connector supports outbound). - Keep Mercado Livre or Nuvemshop connected to feed the native catalog. - Import digital products from Hotmart or Kiwify and still receive sale events in the conversation. Capabilities by platform Each connector declares what it supports; the interface enables the direction and the buttons according to that capability. | Platform | Import (inbound) | Event webhook | Historical sales | Authentication | |---|---|---|---|---| | Generic source (JSON, NDJSON, XML, CSV, or TSV) | Yes | Yes (configurable HMAC signature) | No | Bearer, header, Basic, or URL query parameter | | Shopify | Yes | — | No | Token / header | | WooCommerce | Yes | — | No | Token / header | | Magento, PrestaShop, Medusa | Yes | — | No | Token / header | | Mercado Livre | Yes | — | No | OAuth (Authorize) | | Nuvemshop | Yes | Yes (self-register) | No | Store token (paste) | | Hotmart | Yes (products) | Yes (in Hotmart panel) | Yes (governed preview and selection) | Client credentials | | Kiwify | Yes (products) | Yes (self-register) | Yes (governed preview and selection, up to 90 days) | Client credentials | | OLX | No (no read API) | — | No | Partner only | - Publishing (outbound) to the WhatsApp Business Catalog has its own article; the store/marketplace connectors above focus on import in this version. Not every platform is bidirectional. - The event webhooks above deliver sale events (not products) and feed the e-commerce lifecycle — see that article. - OLX offers no public read API: the integration exists only for approved partners, who publish an ad feed (autoupload). For that reason the OLX connector ships disabled in Sync Studio until partner access is granted. Tips, limits & best practices - Credentials stay on the server: they are encrypted, never returned to the screen, and never appear in logs. OAuth connectors (Mercado Livre) refresh the token on their own through the granted authorization. - Respect the source platform's pagination and limits; very large catalogs are read across several pages and may take longer on the first import. - The description arrives as plain text: stores such as Nuvemshop/Tiendanube and Shopify keep the product description in HTML. On import the platform converts it to text, preserving paragraphs, line breaks and lists — the tags never reach you or the customer, since the description travels as text in the message sent in the conversation and in the Meta catalog. A description you type yourself is stored exactly as you wrote it. - Major units for money: prices stay in major units (4.97 = R$4.97). The platform does not divide by 100. - Run the first import outside peak hours to review the result calmly. Troubleshooting - Mercado Livre authorization failed: confirm the platform app uses the fixed return address /catalog_oauth/callback and redo the Authorize flow (the authorization state expires within a few minutes). - Products were not imported: use Test connection to see the real response; check the token/keys, the store_id/account_id where applicable, and whether the chosen connector is the right one. The Generic preview shows the platform's reason with secrets removed. - The webhook does not fire: confirm the source was registered (Nuvemshop/Kiwify) or that the address was pasted into the platform panel (Hotmart), and that the webhook secret is filled in. - Duplicate items: duplication is avoided by the origin identifier (retailer_id / external_id); if duplicates appear, check whether the items arrived with identifiers different from what already existed. See also - Native catalog: products, categories, images, and prices - Sync and WhatsApp Business Catalog - E-commerce lifecycle: Kiwify/Hotmart/Nuvemshop/Shopify webhooks