Chatbot Campaigns

Chatbot campaigns deliver a site-scoped shopping assistant through the browser SDK. A campaign combines widget presentation, prompt behavior, knowledge, product tools, safety controls, targeting, and optional workflow handoff.

Create the campaign

1. Open Dashboard → Chatbots and create a campaign or choose a template.
2. Select the site and save an operational name.
3. Configure welcome copy, theme, position, launcher, and product recommendation layout.
4. Define the assistant’s role, allowed topics, tone, and failure behavior.
5. Add approved knowledge and catalog context.
6. Configure tools, discounts, and handoff only where the runtime action is genuinely available.
7. Save as Draft until the evaluation checklist passes.

Product cards can render as a stacked grid or a horizontal carousel. The runtime uses catalog availability metadata, treating stock as authoritative when present and quantity only as fallback.

Knowledge and prompts

Knowledge ingestion is asynchronous. Wait for sources to reach a ready state before evaluating answers. Test retrieval with questions that should cite the source and with near-miss questions that should not invent an answer.

Platform AI defaults can set model, generation attempts, tool-turn limit, retrieval limit, and similarity threshold. Campaign guardrails and knowledge settings take precedence when configured.

Conversation state is persisted per chatbot session. The runtime refreshes the hidden prompt preamble each turn while retaining prior non-preamble history.

Targeting and launch triggers

Chatbots support the same page, device, location, ALL/ANY targeting model as overlays. Geo context is resolved server-side and bound into a short-lived targeting token. The message and session endpoints verify the site key, origin, campaign/site scope, token, and geo context.

Trigger matching can be ANY or ALL. An impossible ALL URL trigger set is rejected during campaign validation.

Structured responses

The runtime can return deterministic components:

• product recommendations derived from trusted product tool output;
• focused question forms authored through structured generation;
• discount offer states derived from actual discount tool results.

Coupon issuance returns only a code already configured by the merchant and does not require a commerce-platform mutation. Automatic discount application is a separate action and requires a connector that supports it.

Question answers return through the normal message endpoint. Product and discount components are never accepted directly from model-authored component payloads.

Personalization and handoff

When the SDK provides an identified user or device ID, the runtime can read consented fields allowed for the chatbot surface. Hidden context may support greetings or relevant preferences, but is removed before transcript persistence. Public config never exposes profile values.

Handoff requests can queue a published workflow. Validate the destination, payload, consent, and failure response on staging before activating the campaign.

Release checklist

• Ask supported catalog and policy questions.
• Ask an out-of-scope question and verify the safety response.
• Test missing knowledge, unavailable products, tool failure, and long conversation history.
• Verify question forms, product layouts, discount states, and mobile behavior.
• Confirm geo/page/device targeting with a clean session.
• Verify handoff and discount events only fire for real outcomes.

Measure

Track opens, messages, prompt variants, rendered responses, tool calls/success/failure, handoff requests, goals, and issued discounts. Runtime observability also stores model, prompt ID/variant/version, retrieval count, outcome, and handoff status for governed analysis.

Troubleshooting

• Widget absent: inspect /chatbots/config, campaign status, targeting token, trigger, and lazy bundle request.
• Message rejected: verify the key, origin, targeting token, session, and campaign/site scope.
• Weak answers: check source readiness, retrieval threshold, prompt scope, citations, and product availability.
• No handoff: confirm the workflow is published and the app URL and webhook secret are configured by the platform operator.