Widget setup & persona

Once the widget is embedded, make it yours: its name, tone, color, greeting and what it does when it can't answer are all up to you. Changes apply instantly.

1. Embed (recap)

Setup is one line — full steps in the Quickstart:

<script src="https://semagent.ai/static/widget.js"
        data-tenant-id="your-slug" defer></script>

Adding it on WordPress & WooCommerce

WooCommerce is a WordPress plugin, so adding the widget just means putting the <script> line above into WordPress — no WooCommerce-specific plugin is needed. Don't conflate two separate things:

• Putting the bubble on the site — this section (embedding the script).
• Access to live order/stock data — entering the Consumer Key/Secret under Settings → E-Commerce → WooCommerce in the panel (a separate step; selecting "Read" when generating the key is enough). See Shopify & e-commerce.

To enable e-commerce mode (live store answers), add data-type="ecommerce" to the script:

<script src="https://semagent.ai/static/widget.js"
        data-tenant-id="your-slug" data-type="ecommerce" defer></script>

Method 1 — Header/Footer plugin (recommended)

The most robust; survives theme updates and needs no coding.

1. In the WordPress admin, go to Plugins → Add New → install and activate WPCode (formerly "Insert Headers and Footers").
2. Open Code Snippets → Header & Footer.
3. Paste the script line into the Footer box and click Save.

Method 2 — Theme custom code / Custom HTML area

Many themes (Astra, GeneratePress, Kadence, OceanWP…) offer their own custom-code area: under Appearance → Customize, paste the same line into the Custom HTML / "Footer Scripts" / "Custom Code" field. A site-wide Custom HTML block/widget also works.

Method 3 — For developers (functions.php)

Always use a child theme — otherwise a theme update wipes the code.

add_action('wp_footer', function () { ?>
  <script src="https://semagent.ai/static/widget.js" data-tenant-id="your-slug" data-type="ecommerce" defer></script>
<?php });

2. Persona & appearance

Under Widget → Appearance:

The “SemAgent” signature: on Pro and higher plans (on the Showroom and Flagship packages for stores that came from the Shopify App Store) you can remove the “Answers by SemAgent” line at the bottom of the widget with the Hide the “SemAgent” signature switch on the RAG Widget or E-commerce Widget screen; it applies to both widgets. If the plan drops, the signature shows again. If your package can't hide it, the switch tells you which plans can.

Reply language

The widget opens in the visitor's language: Turkish, English, German, French, Spanish, Italian, Dutch, Russian or Portuguese; English for any other language. In your Shopify store it follows the store's language. Dates, times and prices use that language's format. If you leave the welcome message empty, a ready-made welcome in that language is shown; if you write one, it appears exactly as written in every language.

The assistant answers in the language the customer writes in, judged message by message. When a message gives nothing away (an order number on its own, say), the widget's language decides, then your account's language. Canned sentences that come from the server (the handoff promise, including when the team is back outside working hours; error texts; the check-in question to a customer who goes quiet) exist in all nine widget languages: they go out in the widget's language, or in Turkish or English when the visitor writes in one of those. The order lookup's canned sentences (asking for the order number, the email and the verification code) are in Turkish and English for now: Turkish when the conversation is in Turkish, English otherwise. If your instructions field is empty, English conversations get an English persona. If you want the assistant to always answer in one language, say so in your instructions (e.g. “always answer in English”).

3. Out-of-KB behavior

You choose what the widget does when a visitor asks something outside your knowledge base:

• Politely decline — "I don't have information on that" (the strict-KB default; it won't make things up).
• Redirect — point to a relevant page/contact.
• Escalate to a human — hand off to the support team with a conversation summary.

4. Pre-chat form

Optionally collect name / email / phone before the chat starts. Which fields are requested is configurable (widget_prechat_fields); on escalation this info is passed to human support. API side: widget-settings.

5. Conversation history & CSAT

• The chat persists across page reloads — history is restored via conversation_id.
• A satisfaction score (CSAT) is collected at the end of a conversation; it accumulates in the panel for quality measurement. A 1–2 rating can email your team: Alert me about low ratings.
• Once a person is handling the conversation (taken over, or waiting for the team), the widget keeps a live connection to the panel: the agent's reply and the typing signal show instantly.

Widget modes

The widget runs in two modes: RAG (knowledge-base answers) and e-commerce (live store data). Pick a default mode or set it per request with type — see Shopify & e-commerce.