Setup wizard

Stores › Settings › Conviro Setup (also linked from the Integration Health card). Seven steps that connect the store without copying tokens. Admin permission: Conviro_AiChat::setup (Permissions). Plan P3.1 and §20 item 4. Code: AiChat/Service/Setup/*, AiChat/Controller/Adminhtml/Setup/*, view/adminhtml/templates/setup/wizard.phtml.

A step marked attention links to its section of this page ("What went wrong and how to fix it", <Documentation URL>/setup-wizard#step-<step>; the Documentation URL is not published yet — see Integration Health).

The wizard remembers each step as todo, done or attention (with when and why) and opens at the first step never done, then at the first one needing attention. The facts win over the record: if the store is disconnected later, Connect turns back to attention. It is safe to run again at any time.

Step 1 — Environment check

Each line is Pass or Action required with the fix:

Check	Passes when	Fix when it does not
Magento	2.4.4 or later	Upgrade Magento. (Install-tested: 2.4.4-p13, 2.4.7-p4, 2.4.9.)
PHP	7.4.0 or later	Upgrade PHP.
HTTPS	the secure base URL starts with `https://`	Stores › Configuration › General › Web › Base URLs (Secure) = https, Use Secure URLs = Yes.
Outbound connection	an anonymous call to Conviro's API gets any HTTP answer (3 s connect timeout)	Allow outbound HTTPS to `api.conviro.io:443` (Networking).
Magento cron	cron ran in the last 15 minutes	`bin/magento cron:install`; check `bin/magento cron:run` completes.
Delivery	the outbox table exists	`bin/magento setup:upgrade`.
Magento modules	Integration, Web API, Catalog and Sales enabled (MSI optional)	`bin/magento module:enable …` then `setup:upgrade`.
Extension	installed version vs Conviro's latest and security minimum	Run the update command shown.

Step 2 — Connect to Conviro

Click Connect to Conviro. The browser goes to https://app.conviro.io/dashboard/integrations/magento/connect (the general/app_url setting) carrying a one-time state, a PKCE challenge, the admin page to return to, the store URL and the Magento / module versions. The admin session remembers the request for 10 minutes.
Sign in to Conviro if asked. The approval page shows the store, the address you will be sent back to (refused outright if it is not the store's host or a subdomain of it — start the wizard from the store's own admin), the workspace (switchable if you have several), the chatbot to use on this store, the versions, and what approving does. Only workspace owners and admins can approve, and the plan must include API access. If the workspace is already connected to another store, the page says that approving connects this store instead.
Approve and return to Magento. Conviro creates an API key for this store only (Magento – <store host>, scope magento:module only — the routes the module calls, not your conversations or knowledge base — limited to the chatbot chosen on the approval page, and bound to this store's URL) and sends the browser back with a one-time code valid for 5 minutes. Cancel connects nothing and does not redirect.
Magento exchanges the code and its PKCE verifier with Conviro server to server, stores the key encrypted, saves the workspace and chatbot ids, fills the chatbot's widget public key only if none is set, and runs step 3 at once.

A replayed callback, a mismatched state, a reused code or a wrong verifier is refused and nothing changes (measured on the local stack against the mock Conviro).

Advanced: paste an API key. The same step accepts a key that starts with cvr_ — for example when the admin browser cannot reach app.conviro.io. The key needs the kb:write scope. Or paste it in the configuration page and click Save Config; that does the same registration.

Step 3 — Magento OAuth

The wizard lists, in plain words, what Conviro will be able to read (order actions marked optional and off), then creates or repairs the Conviro AI Chat integration with exactly those permissions (Permissions) and sends its OAuth 1.0a credentials to Conviro. Conviro tests them against your store and answers with the connection mode:

OAuth 1.0a — every Conviro request is signed. Step done.
Legacy bearer token — OAuth was refused; the step needs attention and shows why. The usual cause is a load balancer, CDN or proxy that terminates HTTPS without telling Magento: make it pass the header named in web/secure/offloader_header (default X-Forwarded-Proto: https), then run the step again.

This is the same registration as Save Config, Reconnect and the automatic migration of 1.3.x stores.

Step 4 — Store views

A table of every store view: website, store, view, code, base URL, locale, currency. All are ticked by default.

All ticked saves mode all: every current and future store view.
A subset saves mode selected with those store ids.

For unselected store views the module sends no customer, order, cart or payment events, historical sync skips them, and Conviro never reads live data in them (a shopper there is answered from the default store view if it is selected, else from the first selected website's default view). Product and inventory events are catalog-wide and always flow. The mapping is sent to Conviro now and again on every re-registration. See Multi-store.

Step 5 — Data sync

Box	Default	What ticking it does
Catalog	on	Switches Sync Products to KB on and starts the catalog re-sync: every enabled, website-assigned, visible product, 200 a minute by cron; then every product change.
Inventory	on	Starts an inventory re-sync (current stock of every eligible product; salable quantity with MSI); stock changes are then sent as they happen.
Customers	off	Imports existing customer accounts of the selected store views: customer id, group, website, account date and the e-mail, which Conviro stores only as a one-way hash. No names or addresses, never a lead, nothing is sent to them.
Orders + history window	on, 90 days	Switches Send Order Events on (new orders, shipments, refunds as they happen) and, unless the window is none, imports the orders of the selected store views created in the last 30 / 90 / 365 days. Conviro keeps order number, status, total, item count and a one-way hash of the e-mail.
Quotes / abandoned carts	off	Your confirmation that Conviro may receive the shopper's e-mail and cart contents (up to 10 items) to send recovery messages; switches Abandoned Cart Recovery on. Unticking switches it off and withdraws the confirmation.
Failed payments	off	Your confirmation that Conviro may receive the shopper's e-mail, payment method, cart total and a short error text (never card data) when checkout fails; switches Payment Failure Assistance on.

Save and start initial sync records one job per chosen type; Magento cron runs them in the background and each job's status appears under the step and in the Integration Health card. See Data sync and Cart recovery and payment assist.

Step 6 — AI permissions

What the assistant may do in chat, in plain words (AI permissions): order status and tracking lookup, live stock, product search and pricing, returns assistance, recommendations — on by default — and order-action assistance (cancellation), off by default. Saving sends them to Conviro and grants or removes the order-action permissions on the Magento integration.

Step 7 — Verify

Runs every Integration Health check live and sends a test.ping event through the real outbox and delivery path. The result of each check is kept on the page. The step is done when nothing needs action and the test event was delivered.

After the wizard

Reconnect and Disconnect are on the same page — Reconnect and disconnect.
The Integration Health card on the configuration page is the day-to-day view.

Measured: setup-wizard.sh 58/58 on the local Magento 2.4.7-p4 stack against a mock Conviro (3bb49b22). The wizard has not yet been run against the real Conviro backend or on a merchant store.