SemAgentWidget 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.
- In the WordPress admin, go to Plugins → Add New → install and activate WPCode (formerly "Insert Headers and Footers").
- Open Code Snippets → Header & Footer.
- 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 });Verify: save and open your site; the chat bubble appears at the bottom right. If it doesn't, the first suspect is a caching plugin (WP Rocket, LiteSpeed, W3 Total Cache…) — clear the cache. Getting an answer proves the widget works; getting real data on an order/stock question proves the WooCommerce data connection is set up.
data-tenant-id = your SemAgent account slug (shown in the panel). If you omit data-type, the tenant's default mode is used. For colour/position/greeting add the data-color, data-position, data-welcome, data-language attributes.
2. Persona & appearance
Under Widget → Appearance:
| Setting | What it does |
|---|---|
| Assistant name | The name shown in the chat header (e.g. "Ada — Support"). |
| Tone | Answer style (e.g. friendly-professional, formal). |
| Primary color | Bubble and accent color — to match your brand. |
| Greeting message | The first text shown when the widget opens. |
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.
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.