Configuration reference

Every setting the module stores, where it appears, at which scopes it can be set and its default. All paths are under conviro_aichat/. Admin page: Stores › Configuration › Conviro › AI Chat (admin permission Conviro_AiChat::config). Sources: AiChat/etc/adminhtml/system.xml, AiChat/etc/config.xml, AiChat/Model/Config.php (the only class that reads these paths). Why each setting has the scope it has: configuration-scopes.md.

Scope legend: D default (installation-wide), W website, S store view. "Wizard" means the setting is written by the setup wizard and not shown as a field; "module" means written by the module itself.

Saving this section (Save Config) with an API key re-registers the store with Conviro: the integration and its permissions are repaired (the OAuth token is reused), the capabilities and trust policy are sent, events held for credentials are re-queued. (Until 1.4.0 this did not happen: the observer listened to an event Magento never dispatches.) A store that is disconnected is not re-registered by a save unless the save pastes a new key (Reconnect and disconnect).

General Settings

Path	Admin label	Scopes	Default	Notes
`general/enabled`	Enable	D W S	`1`	Off for a store view = no widget and no events queued for it.
`general/widget_off_since`	— (module)	D	empty	Set by Disconnect (UTC time) unless Keep the chat widget on my storefront was ticked: the storefront widget and lead form are off. Cleared by a successful (re)registration.
`general/docs_url`	Documentation URL	D	empty = `https://repo.conviro.io/docs/magento2`	Base of the "how to fix it" links on the Integration Health card and in the setup wizard (`<base>/<page>#<anchor>`). The default serves these pages (English), from Conviro's API. A value that is not `https://` on `conviro.io` (or a subdomain) is refused by the admin and by `bin/magento config:set`, and ignored if written to the database some other way; a private or development deployment sets it in `app/etc/env.php` (`'system' => ['default' => ['conviro_aichat' => ['general' => [...]]]]`) and runs `bin/magento app:config:import` (1.4.0, security review R3 M4).
`general/api_key`	API Key	D	empty	Encrypted. Normally set by the wizard's Connect to Conviro; a pasted key starts with `cvr_`. Removed by Disconnect. Pasting or clearing it needs the Conviro Setup permission (1.4.0).
`general/connection_status`	Integration Health	D	—	Not a setting: renders the Integration Health card.
`general/public_key`	Widget Public Key	D W S	empty	The chatbot's widget key (Conviro › Chatbot › Channels). Filled by the wizard only when empty. Without it the widget is not rendered.
`general/api_url`	API URL	D, read-only	`https://api.conviro.io`	Managed by Conviro; receives the API key and every event. The admin shows it and posts nothing back. A value that is not `https://` on `conviro.io` (or a subdomain) is refused by the admin and by `bin/magento config:set`, and ignored if written to the database some other way; a private or development deployment sets it in `app/etc/env.php` (`'system' => ['default' => ['conviro_aichat' => ['general' => [...]]]]`) and runs `bin/magento app:config:import` (1.4.0, security review R3 M4).
`general/app_url`	Conviro App URL	D, read-only	`https://app.conviro.io`	Where Connect to Conviro sends the browser. A value that is not `https://` on `conviro.io` (or a subdomain) is refused by the admin and by `bin/magento config:set`, and ignored if written to the database some other way; a private or development deployment sets it in `app/etc/env.php` (`'system' => ['default' => ['conviro_aichat' => ['general' => [...]]]]`) and runs `bin/magento app:config:import` (1.4.0, security review R3 M4).
`general/enforce_webhook_signature`	Require Signed Webhooks	D	`1`	Sent on registration. Yes = Conviro refuses unsigned requests from this store on the legacy (≤ 1.3.x) endpoints. 1.4.0 always signs, so the default is Yes and the 1.4.0 upgrade turns a saved No into Yes once (data patch `RequireSignedWebhooks`); set No only while support diagnoses a delivery problem.
`general/tenant_id`	Tenant ID	D, read-only	empty	Conviro workspace id, written on connect.
`general/chatbot_id`	Chatbot ID	D, read-only	empty	Written on connect.
`general/webhook_secret`	— (module)	D	empty	Encrypted; the shared secret an older (pre-R3) Conviro backend issues — signs events both ways. Removed by Disconnect and when Conviro issues per-direction secrets.
`general/event_secret`	— (module)	D	empty	Encrypted; issued by Conviro on registration (security review R3); signs Magento → Conviro events. Removed by Disconnect.
`general/receive_secret`	— (module)	D	empty	Encrypted; issued with `event_secret`; verifies Conviro → Magento webhooks on `/conviro/webhook/receive`. Removed by Disconnect.
`general/auth_mode`	— (module)	D	empty	`oauth1` or `bearer`, Conviro's answer on registration. Removed by Disconnect.
`general/oauth_error`	— (module)	D	empty	Why OAuth was refused, if it was.

Path	Admin label	Scopes	Default	Notes
`widget/position`	Position	D W S	`bottom-right`	`bottom-right` or `bottom-left`.
`widget/primary_color`	Primary Color	D W S	`#2563eb`	Hex colour.
`widget/loading`	Load the Chat Widget	D W S	`interaction`	1.4.1. `interaction`: the bundle loads on the visitor's first tap, click, key press, scroll or focus, or after `load_timeout_ms`; `idle`: when the browser is idle (at the latest after `load_timeout_ms`); `immediate`: with the page (1.4.0). See Widget loading.
`widget/load_timeout_ms`	Widget Fallback Time (ms)	D W S	`4000`	1.4.1. 1000–30000; for `interaction` and `idle`.
`widget/lead_form_key`	Lead Form Key	D W S	empty	Conviro lead form key (`clf_…`): the form a CMS embed without its own key shows, and the form On every page shows. Where it appears is `lead_form_placement`.
`widget/lead_form_placement`	Lead Form Placement	D W S	`embed`	1.4.1. `embed`: only where a CMS page / block or layout embeds it; `all_pages`: the key's form on every page plus embeds (1.4.0 behaviour); `widget`: no form on the page, lead capture inside the chat widget; `off`: none. New installs: `embed`. The upgrade to 1.4.1 saves `all_pages` at every scope where a key was saved (data patch `PreserveLeadFormPlacement`), so an upgraded store shows its form where it did before. One bundle per page, one render per form.
`widget/greeting_logged_in`	Greeting (Logged-in)	D W S	empty	`{firstName}` and `{name}` are replaced in the browser.
`widget/greeting_guest`	Greeting (Guest)	D W S	empty

1.4.0 loaded the chat widget with the page and fetched the CDN's version.json uncached on every page view before requesting the bundle. 1.4.1:

When: interaction (default) keeps the widget bundle off the critical path — nothing is requested until the visitor taps, clicks, presses a key, scrolls or focuses something, or load_timeout_ms passes. A keyboard user's first key press loads it at once; the fallback gives it to visitors who do none of these (for example a screen-reader user in browse mode). idle loads when the browser is idle. immediate is the 1.4.0 behaviour.
Which build: the build id from version.json is kept in the browser (localStorage) — used without a request for 5 minutes, used and refreshed in the background up to 30 minutes, fetched first (800 ms limit) after that. A widget release, a security fix included, reaches every visitor within 30 minutes, most within 5; purging version.json on the CDN is enough. Without an answer the bundle is requested with an hourly stamp.
Theme hook: before the widget starts, the loader dispatches conviro:before-init on window with detail.appearance = { position, primaryColor }. A theme may change those two (valid values only: bottom-right / bottom-left, a #hex colour). Nothing else is exposed or read back — tenant, API host, keys, identity and privacy policy cannot be changed from the page:
```
window.addEventListener('conviro:before-init', function (e) {
    e.detail.appearance.position = 'bottom-left';
});
```
One widget per page: a second loader, or a widget another embed already mounted, is not started again.

Sync Activity

activity/log (Recent Events) is not a setting: it lists recent outbox events.

Sync Settings

Read for the store view the event belongs to, so a website value overrides the default (configuration-scopes.md).

Path	Admin label	Scopes	Default	Controls
`sync/order_events`	Send Order Events	D W	`1`	`order.*` events and the order-history job. Chat order lookups work either way.
`sync/product_sync`	Sync Products to KB	D W	`0`	`product.` events (per website) and `inventory.updated` (default scope); the catalog and inventory re-syncs. Wizard step 5 Catalog* switches it on.
`sync/customer_lead`	Create Leads on Registration	D W	`1`	`customer.created` — a storefront registration becomes a lead in Conviro.
`sync/cart_recovery`	Abandoned Cart Recovery	D W	off	`cart.updated`, only together with `sync/cart_recovery_confirmed`. The default-scope value (with the confirmation) is also the workspace's `cartRecovery` capability that lets Conviro send the recovery e-mail.
`sync/payment_assist`	Payment Failure Assistance	D W	off	`payment.failed`, only together with `sync/payment_assist_confirmed`. The default-scope value (with the confirmation) is also the workspace's `paymentAssist` capability: whether Conviro may offer the shopper help once after a failed payment (Payment assist).
`sync/cart_url`	Cart page URL (headless stores)	D W S	empty	The recovery e-mail's link for this store view; empty = the store view's own `checkout/cart` URL. Absolute http(s) only.
`sync/cart_recovery_confirmed`	Confirm cart data sharing	D	`0`	Your confirmation that cart contents and the shopper's e-mail may go to Conviro. Until Yes, no cart event is sent even with the toggle on.
`sync/payment_assist_confirmed`	Confirm payment-failure data sharing	D	`0`	Same for failed-payment data.
`sync/confirmation_required_since`	— (module)	D	empty	When the 1.4.0 upgrade held a toggle that was already on.
`sync/product_utm_enabled`	Tag product links with UTM	D W S	`1`	Adds UTM parameters to `productUrl` in product events.
`sync/product_utm_source`	utm_source	D W S	empty	Empty = the store code.
`sync/product_utm_medium`	utm_medium	D W S	`chat`
`sync/product_utm_campaign`	utm_campaign	D W S	`product_card`
`sync/attribution`	Revenue attribution	D W	`1`	The widget may keep its two first-party attribution cookies (only on a positive consent signal) and their ids are added to `order.placed` / `checkout.started` / `payment.failed` (Privacy).
`sync/attribution_without_consent`	Attribution cookies without a consent signal	D W	`0`	Security review R3. Yes = the widget also writes the cookies on a page with no consent signal and no consent platform at all — only for regions where analytics cookies need no consent. A refusal, a platform still loading or an unreadable platform still means no cookie.

Signed Customer Identity (beta)

1.5.0 (unreleased). Read 2026-09-27 on feat/magento-1.5.0-customer-hub and feat/magento-1.5.0-p34-module. Group identity; website scope; every switch off by default, and changing one needs the Conviro Setup permission (Conviro_AiChat::setup) — a forged save without it is refused. Nothing changes for shoppers until Conviro also switches the feature on for your workspace (table below). What it does: Signed customer identity and My orders.

Path	Admin label	Scopes	Default	Notes
`identity/customer_experience`	Customer Experience & Identity	D	—	Not a setting: renders the Customer Experience & Identity card (also on Stores › Settings › Conviro Setup).
`identity/enabled`	Enable signed customer identity	D W	`0`	On for a website = a signed-in shopper's widget may ask the store (`GET /conviro/identity/bootstrap`) for a 60-second signed assertion of their customer id and store view. The first save with it on anywhere creates the key pair and installation id and registers the public key with Conviro. The bootstrap answers 404 on a website where it is off, and where the widget does not render.
`identity/my_orders_enabled`	Show verified shoppers their own orders	D W	`0`	Works only with `identity/enabled` on the same website. On for at least one website = the store announces `myOrders` and the Conviro AI Chat integration is granted `Conviro_AiChat::api_customer_orders` at the next registration (Save Config); off everywhere = the grant is withdrawn.
`identity/order_scope`	Orders a verified shopper sees	D W	`store_view`	`store_view` = only orders placed in the store view the shopper signed in to; `website` = every store view of that website. No global option.
`identity/guest_verification_enabled`	Ask guests for a one-time code before showing an order	D W	`0`	Independent of signed identity. On for a website = the store announces `guestVerification`. The Conviro side is not built yet (2026-09-27): guests keep today's lookup.

Written by the module, never shown as fields (default scope):

Path	Meaning
`identity/installation_id`	UUID generated once; the assertion's issuer is `magento:<installation id>`.
`identity/signing_key`	The Ed25519 secret key, encrypted with the store's `crypt/key`. Never rendered, never sent.
`identity/public_key`, `identity/key_id`	The public key and its `kid` (base64url of the first 16 bytes of its SHA-256).
`identity/previous_key_id`, `identity/rotated_at`	The key a rotation replaced and when.
`identity/integration_id`	Conviro's integration id, returned by the key registration.
`identity/key_state`, `identity/key_error`	`off`, `not_registered`, `registered`, `backend_unsupported`, `refused`, `failed`, `sodium_missing`, and the last error. The card and module-health also report `reset_pending` (read from `identity/reset_pending`).
`identity/reset_pending`	A Reset identity whose outcome is not known yet (1.5.0, owner decision 2026-09-27): JSON `{requestId, startedAt, adminId, attempts}`, written before Conviro is called and cleared when Conviro confirmed or (first attempt) refused it. While set, nothing signs. Written by the module only; never set it by hand — click Reset identity again to settle it.
`identity/registered_for`, `identity/registered_at`, `identity/registered_kid`	The last key registration with Conviro: for which connection, when, and which key.
`identity_key/created_at`	When the current key pair was created (UTC); the card's key age. Older installs fall back to `registered_at`.

Set at Conviro, per workspace (not in Magento; ask Conviro support):

Platform flag	Opens	Default
`magento_identity_bridge`	signed customer identity	off (missing = off)
`magento_my_orders`	My orders for verified shoppers	off
`magento_guest_otp`	guest one-time code (not built yet)	off
`magento_verified_actions`	verified shoppers' cancel / return requests (not built yet)	off

AI Capabilities

Settings of your Conviro workspace, sent on every registration, so default scope only. Full meaning: AI permissions and the action policy.

Path	Admin label	Default	Sent to Conviro as
`capabilities/allow_order_lookup`	Order status & tracking lookup	`1`	`allowOrderLookup`
`capabilities/allow_stock_check`	Live stock & availability	`1`	`allowStockCheck`
`capabilities/allow_product_search`	Product search & pricing	`1`	`allowProductSearch`
`capabilities/allow_returns`	Returns & RMA assistance	`1`	`allowReturns`
`capabilities/allow_recommendations`	Product recommendations (cross-sell)	`1`	`allowRecommendations`
`capabilities/allow_order_actions`	Order-action assistance (cancel, hold, comment; returns and B2B quotes on Adobe Commerce)	`0`	`allowOrderActions`; also grants `Magento_Sales::cancel`, `::hold`, `::comment` to the integration and, where the installation's ACL tree has them (Adobe Commerce), `Magento_Rma::magento_rma` and `Magento_NegotiableQuote::manage` with their parents
`capabilities/return_window_days`	Return window (days)	empty	`returnWindowDays`, only when a positive whole number
`capabilities/warranty_months`	Warranty length (months)	empty	`warrantyMonths`, only when a positive whole number

A fresh install that never saved these reads the defaults above.

Written by the setup wizard (not shown as fields)

Path	Scope	Default	Meaning
`stores/mode`	D	`all`	`all` = every store view including future ones; `selected` = only `stores/selected`.
`stores/selected`	D	empty	Comma-separated store view ids.
`stores/saved_at`	D	empty	When the selection was last saved; empty = never (then `all` applies and no mapping is re-sent on registration).
`initial_sync/catalog`	D	on until saved	Step 5 choice.
`initial_sync/inventory`	D	on until saved
`initial_sync/customers`	D	off	Also the switch that allows the customer-import job to run.
`initial_sync/orders`	D	on until saved
`initial_sync/orders_window_days`	D	`90`	`0` (none), `30`, `90` or `365`.
`initial_sync/quotes`	D	off
`initial_sync/requested_at`	D	empty	When step 5 was saved.

State outside `core_config_data`

Lifecycle state that is not a setting lives in Magento's flag table: conviro_setup_state (wizard progress), conviro_setup_environment and conviro_setup_verify (last step 1 / step 7 results), conviro_connection_state, conviro_pending_disconnect, conviro_oauth_migration.

Checking for values at scopes that are no longer read

1.3.x offered website/store-view fields for settings that 1.4.0 reads at default scope only. Such values stay in the database but are ignored:

SELECT scope, scope_id, path FROM core_config_data
WHERE path LIKE 'conviro_aichat/%' AND scope <> 'default';