Expand troubleshooting and deliverability guidance

_config.yml

@@ -226,7 +226,12 @@ collections:
     order:
       - troubleshooting-overview.md
       - troubleshooting-checklist.md
+      - why-a-message-did-not-send.md
+      - troubleshoot-whatsapp-templates.md
+      - troubleshoot-a-capture.md
       - troubleshoot-missing-signals-or-activity.md
+      - troubleshoot-pages-that-do-not-load.md
+      - contact-hellotext-support.md
       - sms-sending-limits-for-new-businesses.md
     output: true
 

_i18n/en/captures/capture-overview.md

@@ -40,6 +40,8 @@ Name each capture after the placement or campaign where it will be used. This ma
 
 Test every capture before sharing it with customers. For QR codes, scan the final printed or displayed version with a phone. For links and forms, test the full subscription flow from the same device a customer would use.
 
+If a capture does not appear, complete its interaction, or update the customer profile, follow [Troubleshoot a capture that does not appear or register customers]({% link _troubleshooting-deliverability/troubleshoot-a-capture.md %}).
+
 For webchat, test the launcher, teaser, opening sequence, Inbox ownership, and any WhatsApp handoff from both desktop and mobile.
 
 ## Next steps

_i18n/en/troubleshooting-deliverability/contact-hellotext-support.md

@@ -0,0 +1,88 @@
+You can contact the Support team through [hellotext.com/contact](https://www.hellotext.com/contact/) or by emailing [support@hellotext.com](mailto:support@hellotext.com).
+
+A specific report makes it easier to identify the affected business, object, and time. You do not need to diagnose the technical cause before asking for help.
+
+## Before contacting Support
+
+When possible:
+
+1. Reproduce the problem once and note the exact stage where it occurs.
+2. Review the related guide in this section.
+3. Confirm whether it affects one teammate, customer profile, message, or page, or whether it is broader.
+4. Preserve any recent changes that may be related.
+5. Avoid repeating actions that could send messages, create campaigns, charge, import, or modify data more than once.
+
+If incorrect messages continue to send and you can do so without losing information, pause the affected campaign, playbook, or journey while it is investigated.
+
+## Basic information to include
+
+Include:
+
+- business name in Hellotext;
+- exact URL of the affected page;
+- approximate date and time with time zone;
+- what you expected to happen;
+- what happened instead;
+- scope of the problem;
+- short steps to reproduce it;
+- a screenshot or short recording; and
+- recent configuration, integration, permission, or code changes.
+
+Keep the conversation in the same email or request thread when adding evidence about the same problem. Open a separate request for a different problem.
+
+## Information by problem type
+
+| Problem | Useful information |
+| --- | --- |
+| **Message or channel** | Channel, sender, message ID or link, customer profile, delivery status, and reason. |
+| **Campaign** | Campaign link, audience, schedule, and stage where it stopped. |
+| **Playbook or journey** | Link, relevant version or configuration, expected signal, and customer profile used for testing. |
+| **Inbox** | Conversation link, expected team or teammate, status, and assignment time. |
+| **Integration** | Connected platform, store, or account, missing object, source-system identifier, and last known sync. |
+| **Capture** | Type and name, URL or placement, device, browser, and stage where it stopped. |
+| **Report or attribution** | Report, period, time zone, filters, order or conversion, and expected result. |
+| **API or Hellotext.js** | Endpoint or event, time, request ID, response code, and the smallest snippet that reproduces the problem. |
+| **Billing** | Month, invoice, plan, or affected charge concept. Use identifiers, not complete payment details. |
+
+You can partially mask a phone number or email when the complete identifier is not needed to find the case.
+
+## Information not to send
+
+Do not share:
+
+- passwords;
+- API tokens or application secrets;
+- verification codes;
+- cookies or authorization headers;
+- complete card or bank account numbers; or
+- full customer exports when one or two examples are enough.
+
+If Support needs a sensitive file, first confirm what information is required and how to send it securely.
+
+## How to describe impact
+
+Describe the observable impact without trying to assign a technical severity.
+
+For example:
+
+- how many businesses, teammates, or customers are affected;
+- whether it blocks an operation or has a temporary workaround;
+- whether it prevents receiving or sending messages;
+- whether it could create duplicate messages, changes, or charges; and
+- how long it has been happening.
+
+Report any suspected unauthorized access, data exposure, or credential misuse immediately. Do not include the potentially exposed secrets in the message.
+
+## What to expect next
+
+Support may ask for another example, confirm permission to inspect an object, or ask you to reproduce the problem with technical evidence. Reply in the same thread to preserve context.
+
+The public contact page does not define one universal response time. If your plan or agreement includes a specific support commitment, that commitment is the applicable reference. Do not use the SLAs configured for your Inbox conversations as the expected Hellotext Support response time: they are different metrics.
+
+## Related guides
+
+- [Troubleshooting and deliverability overview]({% link _troubleshooting-deliverability/troubleshooting-overview.md %})
+- [Troubleshooting checklist]({% link _troubleshooting-deliverability/troubleshooting-checklist.md %})
+- [Troubleshoot pages that do not load]({% link _troubleshooting-deliverability/troubleshoot-pages-that-do-not-load.md %})
+- [Why a message did not send]({% link _troubleshooting-deliverability/why-a-message-did-not-send.md %})
+- [Troubleshoot missing signals or activity]({% link _troubleshooting-deliverability/troubleshoot-missing-signals-or-activity.md %})

_i18n/en/troubleshooting-deliverability/troubleshoot-a-capture.md

@@ -0,0 +1,118 @@
+Use this guide when a capture playbook is not available in the product, does not load for a customer, does not register submitted information, or does not start the configured action after capture.
+
+All capture playbooks are under **Playbooks > Explore playbooks**, in the **Captures** group. They include different experiences: Website Popup, Website Form, Webchat Widget, QR codes, shareable links, checkout opt-in, and AI interactions such as Subscriber Booster and Property Collector.
+
+## Identify where it stopped
+
+Before changing the configuration, reproduce the problem and place it in one of these stages:
+
+| Stage | What you observe |
+| --- | --- |
+| **Availability** | The playbook is missing from **Explore playbooks** or shown as **On request**. |
+| **Loading** | The capture exists but does not appear on the expected website, checkout, or channel. |
+| **Interaction** | The capture appears but does not open, advance, or submit. |
+| **Verification** | The customer submitted information but must still verify a new phone number or email. |
+| **Customer profile** | The interaction finished, but the information is not on the expected customer profile. |
+| **Next action** | The profile was updated, but a coupon was not delivered, a journey did not start, or a message was not sent. |
+
+This separation keeps you from reinstalling a capture when the problem is a pending verification or a later action.
+
+## If the playbook is not available
+
+1. Open **Playbooks** and click **Explore playbooks**.
+2. Find the **Captures** group.
+3. Confirm that the playbook is available for your business and plan.
+4. If it is shown as **On request**, disabled, or not yet available, check with your Hellotext team before preparing the installation.
+
+After configuring it, confirm that it was saved and enabled. Popups and forms published on a website must also complete their installation or publishing step.
+
+## If a popup or Webchat does not appear
+
+Check these points in order:
+
+1. Confirm that the playbook is enabled and its latest version was saved.
+2. Confirm that the supported integration, plugin, or Hellotext.js loads on the live page.
+3. For a manual installation, compare the code running on the website with the current code generated by Hellotext.
+4. Check the exact domain and URL where it should appear.
+5. Confirm that the configuration includes the device you are testing.
+6. Check whether the experience opens automatically, after a delay, or only when someone clicks a launcher, bubble, or teaser.
+7. Test in a private browser window and on a real phone to separate previous session state from an installation problem.
+8. Check whether website styles, consent banners, or other elements are hiding the capture.
+
+For a Subscriber Booster teaser, both **Webchat Widget** and **Subscriber Booster** must be enabled. Webchat provides the visible entry point, while the other playbook handles the AI subscription invitation.
+
+## If a form does not load
+
+First, test the hosted link for the same form.
+
+- If the hosted link works, inspect the installation, container, and website styles or scripts where the form is embedded.
+- If the hosted link also fails, inspect the form configuration, required fields, and status in Hellotext.
+
+For an embedded form, confirm that the current snippet is present and that the eCommerce integration or Hellotext.js loads successfully. A developer can also observe `forms:collected` to confirm that the library found the form definitions and `form:completed` to confirm that the process finished, including any required verification.
+
+## If a QR code or link does not register the subscription
+
+Scan or open the final version from a phone and confirm that it uses the expected number, channel, message, and capture reference.
+
+Opening the QR code or link does not complete the subscription. The customer must send the prefilled message through SMS or WhatsApp. Hellotext records the capture and updates the customer profile after receiving that message.
+
+If the message does not leave the phone or reach Hellotext, inspect the channel and number before changing the capture.
+
+## If checkout opt-in does not register the customer
+
+Confirm that:
+
+- the eCommerce integration is connected and syncing orders and customer profiles;
+- the consent option is visible in the published checkout;
+- the customer selected the relevant option; and
+- you are checking consent for the correct channel on the customer profile.
+
+Creating a profile from a purchase does not mean that the customer accepted marketing messages. Subscription status depends on the consent they provided at checkout.
+
+## If data is missing from the customer profile
+
+1. Repeat the test with a phone number or email that you can safely inspect.
+2. Complete every required field.
+3. If Hellotext sends verification to a new phone number or email, complete it. The process is not finished while that verification is pending.
+4. Search for the customer profile using every identifier submitted. Hellotext may update an existing profile or merge matching profiles instead of creating a new one.
+5. Check that custom properties used by the capture still exist and match the configured fields.
+6. Confirm that consent was requested for the channel you are checking.
+
+The same browser can remember a completed capture. Use a private window when you need to repeat the experience from the beginning.
+
+## If the next action failed
+
+A completed capture and a later action are separate stages.
+
+- If the customer profile was updated but a coupon or message was not delivered, review [Why a message did not send]({% link _troubleshooting-deliverability/why-a-message-did-not-send.md %}).
+- If a journey should have started, confirm that the journey is enabled and inspect its activity.
+- If a Webchat conversation should have opened, confirm that the message reaches Inbox and inspect its assignment.
+- If Subscriber Booster did not participate, confirm that the conversation started through Webchat or was initiated by the customer on WhatsApp, and that the playbook is enabled.
+
+Do not use message delivery as the only test of whether capture failed. First confirm whether the profile and consent were updated.
+
+## What to include when asking for help
+
+Include:
+
+- business and capture name;
+- capture type;
+- URL, domain, or placement tested;
+- device and browser;
+- approximate date and time with time zone;
+- exact stage where it stopped;
+- customer profile identifier used for the test;
+- a screenshot or short recording; and
+- visible console errors or failed network requests, if you have technical access.
+
+Do not include verification codes, tokens, passwords, or real payment information.
+
+## Related guides
+
+- [Capture tools overview]({% link _captures/capture-overview.md %})
+- [Website Popup]({% link _captures/website-popup.md %})
+- [Website Form]({% link _captures/forms.md %})
+- [Webchat Widget playbook]({% link _captures/webchat-widget-playbook.md %})
+- [Subscriber Booster playbook]({% link _captures/subscriber-booster-playbook.md %})
+- [Who you can message]({% link _audience/consent-and-subscriber-status.md %})
+- [Verify your data and signals after setup]({% link _integrations/verify-data-and-signals.md %})

_i18n/en/troubleshooting-deliverability/troubleshoot-pages-that-do-not-load.md

@@ -0,0 +1,80 @@
+Use this guide when a Hellotext page is blank, remains in a loading state, shows incomplete information, responds slowly, or repeatedly shows the same error.
+
+## Before reloading
+
+First, preserve the information that will make the problem easier to investigate:
+
+- copy the full URL;
+- note the selected business;
+- record the approximate date and time with time zone;
+- take a screenshot of the visible message or state; and
+- note the last action performed.
+
+If the error appeared while sending a campaign, importing data, changing billing, or performing another action that could create duplicate results, confirm its status before repeating it.
+
+## Define the scope
+
+Check how broad the problem is:
+
+1. Does one page fail, or do all Hellotext pages fail?
+2. Does one business fail, or does it also happen after switching businesses?
+3. Does it affect one teammate or several people?
+4. Is the page blank, or does it load with data that does not match the filters?
+5. Did it start after a role, integration, browser, or network change?
+
+A page that loads without results is not always experiencing a technical failure. Check the period, time zone, filters, business, and permissions before treating it as an outage.
+
+## Recover the page
+
+Try these steps in order and check again after each one:
+
+1. Reload the page once.
+2. Open the same URL in a private window in the same browser.
+3. Confirm that your connection can open other pages and that a VPN, proxy, or corporate filter is not blocking Hellotext.
+4. Try another updated browser or network when your team policy allows it.
+5. Sign out and back in if the problem appears limited to your session.
+6. Temporarily disable privacy or content-blocking extensions for the test when it is safe to do so.
+
+Clear site data only after preserving evidence and any unsaved work. This signs you out and removes local browser preferences, but it does not delete information stored in your Hellotext business.
+
+## Check permissions and context
+
+If general navigation works but one page does not:
+
+- confirm that you are in the correct business;
+- check whether your role can access that setting or report;
+- open the page from Hellotext navigation instead of an old bookmark;
+- remove filters to see whether the view returns data; and
+- check whether the linked object still exists and remains available to your business.
+
+An access error, an empty data view, and a technical loading failure need different solutions. Preserve the exact warning text.
+
+## Collect technical evidence
+
+If you can use browser developer tools:
+
+1. Open **Console** and **Network** before reproducing the problem.
+2. Reload the page and repeat the action once.
+3. Preserve the text of the first relevant error.
+4. In **Network**, identify failed requests and note the URL, method, status, and time.
+
+A HAR file can contain customer identifiers, message content, cookies, or authorization headers. Do not share it unless Support requests it and you have confirmed a secure way to send it.
+
+## When to contact Support
+
+Contact Support when:
+
+- the problem also happens in a private window and another browser or network;
+- it affects multiple teammates or businesses;
+- it blocks access to Inbox, channels, campaigns, playbooks, billing, or essential data;
+- an action remains in an uncertain state and repeating it could create duplicates; or
+- you see repeated server errors or failed requests that you cannot resolve.
+
+Use [Contact Hellotext Support]({% link _troubleshooting-deliverability/contact-hellotext-support.md %}) to gather the information needed.
+
+## Related guides
+
+- [Troubleshooting checklist]({% link _troubleshooting-deliverability/troubleshooting-checklist.md %})
+- [Troubleshoot missing signals or activity]({% link _troubleshooting-deliverability/troubleshoot-missing-signals-or-activity.md %})
+- [Troubleshoot a capture that does not appear or register customers]({% link _troubleshooting-deliverability/troubleshoot-a-capture.md %})
+- [Data completeness and reporting gaps]({% link _analytics-reporting-attribution/data-completeness-and-reporting-gaps.md %})