Integration Health card

At the top of Stores › Configuration › Conviro › AI Chat. One row per part of the integration, each Pass, Warning or Action required with the sentence that fixes it, then one verdict. Nothing is shown as healthy without a measurement. Plan §13, §23. Code: AiChat/Block/Adminhtml/IntegrationHealth.php, AiChat/Service/Health/{HealthCheck,HealthFacts,ConviroStatus}.php. Every message quoted below is from HealthCheck.php (2026-09-24; the Store-wide bearer tokens row 2026-09-26).

Verdict

• Integration ready — no row needs action (with "— N warnings" if any row warns).
• Action required: <row> — <first sentence> (+N more) — the first row that needs action.
• Disconnected from Conviro on <date> UTC — nothing is sent and Conviro no longer reads this store — after a Disconnect (a Warning, not a failure).

Where the facts come from

Magento-side facts (queue, cron, settings, the integration's ACL) are read on every page load. Conviro's view comes from one call to GET /api/magento/tenant-info (3 s connect / 4 s total), cached 60 seconds per API URL and key; the card says how old it is. Save Config drops that cache; Test connection bypasses it. When Conviro cannot be asked, rows that depend on it say so ("as of the last Save Config") and show a Warning, not a Pass.

Rows

Every row that is not a Pass links here ("What this means and how to fix it"), to <Documentation URL>/integration-health#row-<row> — the base is Documentation URL (conviro_aichat/general/docs_url, default https://repo.conviro.io/docs/magento2, where Conviro serves these pages).

Connection

Authentication

Webhooks

Catalog sync

Orders / events

Cron / queue

Since 1.4.1 the two jobs that run every minute — conviro_deliver_events (the outbox worker) and conviro_connection_maintenance (OAuth migration, disconnect retry, the health report to Conviro) — record their own last run, last success and last failure (Magento's flag table, rows conviro_cron_<job>); Details shows them as Delivery heartbeat and Maintenance heartbeat. The row judges from these, and uses cron_schedule only until the first heartbeat exists — Magento deletes successful cron_schedule rows after an hour, so "when did it last succeed" was not answerable from it.

A store with nothing to send is never flagged: the heartbeat runs every minute whether or not there are events, and "events waiting" counts only events that exist. Both problems — cron silent for 10 minutes, or an event waiting for 15 minutes while cron runs — are also shown as an admin system message on every admin page of a connected store (1.4.1), and the store reports them to the Conviro dashboard (Delivery health on the Magento store card) every 15 minutes; a report that stops arriving is shown there as "no report since …".

Extension version

The command shown is built by the module from the published version number (since 1.4.0 — any command text Conviro's answer carries is ignored, and a version that is not a plain 1.2.3 / 1.2.3-rc1 is neither shown nor compared). Since 1.4.1 it is built for this store — its Magento mode and the locales a static deploy must build (active store views, active admin users, en_US) — for example, production mode, a tr_TR store: bin/magento maintenance:enable && composer require 'conviro/module-aichat:^<version>' && bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento setup:static-content:deploy -f en_US tr_TR && bin/magento cache:flush && bin/magento maintenance:disable (composer update conviro/module-aichat in place of the composer require when no valid version is known; developer mode: composer, setup:upgrade, cache:flush). The row says which mode it was built for. Run it as the owner of the Magento files, never as root. Each step, and the release-directory method: Installation › Upgrading. The latest-version answer is cached 12 hours (15 minutes after a failed check).

Environment

Pass: Magento version (and deploy mode), PHP, Conviro API latency, HTTPS storefront. Action when any of: Magento older than 2.4.4; PHP older than 7.4; the default store view's base URL is not https ("order and customer data would travel unencrypted"); the API URL is not https; no outbound connection to Conviro.

Cart & payment events (shown only when relevant)

Warning when Abandoned Cart Recovery or Payment Failure Assistance is on (at any scope) but not confirmed — cart.updated / checkout.started / payment.failed are not sent (with "held since the upgrade to 1.4, <date>" when the upgrade held it). Fix: open the admin message's link (Confirm cart and payment data sharing — confirms only, starts no sync), or set Confirm cart / payment data sharing = Yes and Save Config; or switch the toggle off.

Since 1.4.1 the same sentence is also an admin system message (severity major, on every admin page of a connected store) with a link to the confirmation page, until the feature is confirmed or switched off — a merchant who upgraded from the command line sees it without opening this card.

Storefront widget (shown only when relevant)

Since 1.4.1 the card looks at the theme of every active store view — and its parent themes, in Magento's fallback order — for Conviro overrides: Conviro_AiChat/templates/widget.phtml, lead-form.phtml, Conviro_AiChat/web/js/widget-loader.js, any Conviro_AiChat/layout/**, and any theme layout file that names the conviro.aichat.widget block or a Conviro_AiChat:: template (removing or re-adding the widget). The file scan is cached for an hour (cache:flush clears it).

Check storefront (button on the card) makes one read-only GET of the default store view's home page — the public URL, as a visitor gets it, from Magento's full-page cache or Varnish if they answer — and of the widget loader file that page references. It checks: exactly one widget configuration block, carrying this store's widget key (otherwise the page is cached from before a change); exactly one module loader script, and that the file served is this release's loader (otherwise static content was not redeployed after the upgrade); nothing else starting the widget (an inline cw('init' or a direct widget.iife.js tag, e.g. a theme override or a pasted snippet — two widgets); at most one lead-form script. Nothing is sent to Conviro. If the server cannot reach its own public URL (some firewalls), the check says so.

Skipped events (shown only when relevant)

Warning when an observer skipped an event in the last 24 hours because preparing or queuing it failed (1.4.1). Every Conviro observer wraps its whole body: the order, checkout, cart or save it runs in always continues — a Conviro problem never becomes a checkout or payment error — and Conviro misses that one event. The row says how many, the last observer, exception class and time; the details are in var/log/system.log ("[Conviro] … event skipped", no personal data). Counted per hour in the flag table (conviro_observer_failures) and reported to the Conviro dashboard.

Store-wide bearer tokens (shown only when relevant)

Warning when Magento's own Allow OAuth Access Tokens to be used as standalone Bearer tokens (Stores › Configuration › Services › OAuth › Consumer Settings, oauth/consumer/enable_integration_as_bearer) is Yes while Conviro signs with OAuth 1.0a (Conviro's answer; the last Save Config when Conviro cannot be asked). 1.3.x switched it on for the whole store on every Save Config; 1.4.0 never changes it by itself, because another integration of yours may send its access token as a bare bearer token. While it is on, anyone who obtains the access token of any integration on the store can call the REST API with it, without an OAuth signature. Conviro does not need it.

Fix: the row's Turn off store-wide bearer tokens button (needs Conviro_AiChat::setup; asks for confirmation first; a POST with the admin form key) sets it to No at the default scope, the only scope Magento reads — or set it yourself on the page above. Check first that no other integration of yours authenticates with a bearer token; if one stops working, switch it back on there. The button changes nothing while Conviro still uses the legacy bearer connection (the Authentication row says so), and says so when a value in app/etc/env.php or config.php overrides the database. Not shown on the legacy bearer connection or without an API key.

Customer Experience & Identity (1.5.0, unreleased)

1.5.0 (unreleased), read 2026-09-27 on feat/magento-1.5.0-p34-module (Block/Adminhtml/Setup/IdentityCard.php, Service/Identity/IdentityCardView.php; not merged yet). What the feature does: Signed customer identity and My orders.

On this card — below the sync jobs, one line: Customer identity: off., Customer identity: on. or Customer identity: needs attention (…) with a link to the card and — Phase 5, branch feat/magento-1.5.0-p5-module — a link Why doesn't it work? (30-second runbook) that opens the runbook at this store's first failing gate. The reasons it can name: not connected, key not registered, Conviro backend without identity, key refused, key registration failed, PHP sodium missing, key rotation due, order listing permission missing. It reads only this store's facts (no call to Conviro).

The card is on Stores › Settings › Conviro Setup and at the top of Stores › Configuration › Conviro › AI Chat › Signed Customer Identity (beta). It renders even when Conviro cannot be reached; it never shows a secret, a customer or an order.

Key state (the Signed identity line)

Key age: "Key age: N days (since …)". From 180 days the card warns Keys older than 180 days should be rotated (policy set 2026-09-28); a key created before the module recorded its age shows unknown.

Order listing permission missing

Turkish admin: Sipariş listeleme izni eksik. Show verified shoppers their own orders is on, but the Conviro AI Chat integration does not hold the read permission A verified shopper's own orders (read) (Conviro_AiChat::api_customer_orders), so Conviro cannot list a signed-in shopper's orders — the shopper sees "Order details aren't available in the chat for this store" and the account-page link.

Fix: Repair access on the card (needs Conviro_AiChat::setup; an admin without it is told who can). It registers the store with Conviro again, which grants exactly the permissions the switches call for, then reads the grant back; if the permission is still missing it says so — then check the Conviro AI Chat integration under System › Extensions › Integrations and run bin/magento setup:upgrade if the Conviro_AiChat::api_customer_orders resource is unknown (it comes with 1.5.0). The same warning appears in the Conviro dashboard (Order listing permission missing in Magento), also when Magento refused one of Conviro's order reads with "not authorized".

When the integration cannot be read at all the card says Order listing permission: could not be read (reload; see the Authentication row).

Test identity bridge

Signs a synthetic assertion with this store's real key — audience conviro-widget-identity-test, subject synthetic-test, no customer, no binding row — and asks Conviro to verify it without creating anything (Conviro refuses such a token anywhere else, and a real assertion here). Needs Conviro_AiChat::config; Conviro allows 10 tests an hour per store. Steps:

A green test proves the store's key, the mapping, the clock and Conviro's switches — not a real shopper's browser (the same-origin bootstrap). For that, sign in as a test customer and open the chat.

Sync jobs panel

Below the rows: each job type with its progress, counts, times, last error and stall / pause notes, and the buttons Re-sync inventory, Re-sync recent orders, Import customers (only if chosen), Repair failed items (Data sync).

Actions

Measured: admin-health.sh 32/32 on the local stack (3bb49b22); 42/42 with the Store-wide bearer tokens row and its button (2.4.7-p4 dev stack, 2026-09-26); page timings in Performance.