Home / Docs / Welcome

Welcome to SAL docs.

Set up SAL on your WordPress site, configure it for your business, and connect it to your CRM — all in under five minutes for a first install. This is where you'll find guides, references, and answers to the questions that come up along the way.

Just installed SAL?

Start here.

Our five-minute setup walks you through plugging in your AI key, choosing what SAL reads, and seeing your first conversation come through.

1Install 2Add API key 3Choose pages 4Start chatting
Get started

What is SAL?

SAL is an AI chat widget that lives on your WordPress site. When a visitor opens it and asks a question, SAL reads your pages, menus, and the facts you've given it in admin — and answers in real time, in conversational language, grounded in your actual content. No training, no FAQ rewrites, no knowledge base to maintain. If you update a page tomorrow, SAL knows tomorrow.

The product is designed around one observation: the contact-form era is over. Most decisions happen on a phone, after hours, with three tabs open. Visitors have one question, and if they don't get an answer in thirty seconds, they're gone. SAL exists to close that gap — answer instantly when it can, capture the lead along the way, and hand off to WhatsApp when a real person should take over.

Every captured lead can be synced to your CRM the moment it's submitted — Brevo, HubSpot, or any other system via webhook (Zapier, Make, Slack, custom dashboards). Each lead flows in with full context: name, email, phone with international country code, company, every page they visited before the conversation, and where they were when they submitted.

SAL is the product, Smith Aegis is the publisher

SAL® - AI Chat is built and maintained by Smith Aegis, an integrated marketing and advertising agency in Nairobi. SAL is available to any WordPress business worldwide as of version .

What you'll need.

Before you start, gather these. SAL doesn't need much, but the things it needs, it needs upfront.

  • A WordPress site Any modern version (5.0+). SAL is a regular plugin — no theme changes, no rebuild.
  • An AI provider API key SAL works with Anthropic (Claude), OpenAI (GPT), or Google (Gemini). Pick one, create an account if you don't have it, and grab an API key — most take under two minutes. You pay the AI provider directly for usage; SAL never sits between you and your model.
  • About five minutes Install, paste the key, save. That's it. Configuration can come later.
  • Optional: a CRM account If you want leads to flow into Brevo or HubSpot automatically, have an account ready. Skipping this for now is fine — leads still get saved in WordPress and exported as CSV.
  • Optional: a WhatsApp number If you want SAL to hand off complex conversations to a human, point it at the WhatsApp number your team monitors.

How it works, in three moves.

The architecture is simple by design.

1. SAL reads your site

When a visitor opens the chat, SAL pulls in the page they're on, the menu items on your WordPress site, and any extra facts you've defined in admin. That context goes to Claude alongside the visitor's question. Claude grounds its answer in that material rather than guessing.

2. The conversation happens in real time

Words stream onto the page as Claude generates them — no "thinking…" spinner, no awkward wait. If SAL doesn't know the answer (because it isn't on your site, or because the question is one only a person can really resolve), it doesn't fabricate. It quietly offers a WhatsApp handoff with the conversation history carried over.

3. Leads flow where they need to go

When the visitor leaves their details, SAL captures them — name, email, phone with country code, company — alongside the path they took through your site to get there. Within seconds, that lead lands in Brevo, HubSpot, or whichever webhook destination you've configured. No CSV copy-paste, no manual entry, no delay.

A glimpse of what gets sent

When a lead is captured, SAL dispatches a structured payload to every configured integration. Here's what HubSpot or Brevo receives:

lead.payload — JSON
{
  "lead": {
    "name": "Amina Otieno",
    "email": "amina@example.co.ke",
    "phone": "+254765941351",
    "company": "Acme Co."
  },
  "context": {
    "page_url": "/pricing",
    "page_journey": ["/", "/services", "/pricing"],
    "messages_count": 8,
    "started_at": "2026-06-05T09:14:02Z"
  },
  "site": "yoursite.com",
  "conversation_id": "conv_8f2a3c"
}

The full payload schema reference covers every field, optional vs required values, and how the same payload maps to Brevo attributes and HubSpot properties.

No transcript leakage

By design, the conversation transcript is not sent to your CRM. Lead identity and journey context are — the message log stays in your WordPress admin where you control it.

For the full release history — from 1.0.0 through the current 2.3.5.x line — see the Changelog. The latest major addition: multi-provider AI — you can now pick Anthropic (Claude), OpenAI (GPT), or Google (Gemini) as your AI engine, switch any time, and pay your chosen provider directly with no Smith Aegis markup.

Docs / Get started / Install SAL

Install SAL.

Get SAL running on your WordPress site in under five minutes. You'll sign up for a free 30-day trial, download the plugin from your dashboard, install it on WordPress, paste in an AI provider API key (Anthropic, OpenAI, or Google — your choice), and see your first chat launcher appear on your live site.

Start with a free trial

Before installing, sign up for a free 30-day trial at app.smithaegis.co.ke. You'll download the plugin from your dashboard after signup, get a license key for your site, and have full access to everything in SAL during the trial. See Creating your account for the dashboard walkthrough.

Before you begin.

SAL is a regular WordPress plugin. It doesn't touch your theme, doesn't require database migrations, and doesn't compete with anything else you've got installed. Most installs take three to four minutes start to finish. Before you click anything, make sure you have:

  • A WordPress site, version 5.0 or newer. Almost any host works — shared, managed WP, VPS. If you can install plugins from Plugins → Add New, you can install SAL.
  • An AI provider API key. SAL works with Anthropic (Claude), OpenAI (GPT), or Google (Gemini). Pick whichever you prefer — you'll create the key at console.anthropic.com, platform.openai.com, or aistudio.google.com respectively. Each takes about 90 seconds. SAL is bring-your-own-key — you pay the provider directly (typically a few dollars a month for a moderately-trafficked site).
  • A SAL account at app.smithaegis.co.ke. Sign up for the free trial — no credit card required — and you'll have access to the plugin download and a license key for your site.

Why an API key instead of a subscription?

SAL is "bring your own key" — you create the account with whichever AI provider you choose, you control the credits, you see the usage in your own dashboard with that provider. SAL doesn't put a billing wrapper around any of them. The trade-off: you do the one-time API key setup. The benefit: pricing scales linearly with use, you can switch providers any time without involving us, and there's no per-conversation markup.

Get the plugin file.

Log in to your dashboard at app.smithaegis.co.ke. From the Downloads section, grab the latest plugin file — it'll be named something like (or whatever the current version is). Save it somewhere you can find it.

The file is around 250 KB. If yours is much larger, it might be a duplicate or wrapped in another archive — open it and check.

Install in WordPress.

Three steps, about 60 seconds.

  1. Open your WordPress admin at yoursite.com/wp-admin and go to Plugins → Add New.
  2. Click "Upload Plugin" at the top of the page, then "Choose File" and pick the sal-ai-chat-*.zip you downloaded.
  3. Click "Install Now" and wait for the green confirmation message.

If your host blocks plugin uploads

Some managed-WordPress hosts (WP Engine on certain plans, Kinsta on starter tiers) disable plugin uploads through the admin UI. If you see "Sorry, you are not allowed to install plugins on this site" — you'll need to upload via SFTP. The plugin folder goes in wp-content/plugins/. Reach out to support and we'll walk you through it.

Activate the plugin.

Once the install finishes, click Activate Plugin (or go to Plugins → Installed Plugins and activate it there). You should now see a new menu item in your WordPress admin sidebar called SAL® - AI Chat, with three sub-items:

  • Settings — where you'll add your API key and tune the chat behavior.
  • Conversations — the inbox where every chat that's happened on your site lives.
  • Integrations — where you'll connect Brevo, HubSpot, or a webhook later.

If the SAL menu doesn't appear, refresh the admin page. If it still doesn't show, the activation didn't complete — go back to Plugins → Installed Plugins and click Activate again.

Add your API key.

SAL needs an API key from your chosen AI provider — Anthropic, OpenAI, or Google. Pick one to start; you can switch later or run different providers on different sites if you want.

If you're going with Anthropic (Claude)

  1. Go to console.anthropic.com and sign up (or sign in if you have an account).
  2. Add a payment method. Anthropic uses pre-paid credits. $5 is enough to test; $20 covers most small business sites for several months.
  3. Create an API key at Settings → API Keys → Create Key. Name it "SAL — yoursite.com" so you'll remember what it's for.
  4. Copy the key. Starts with sk-ant-. Anthropic only shows it once — store it somewhere safe before closing the tab.

If you're going with OpenAI (GPT)

  1. Go to platform.openai.com and sign up (or sign in).
  2. Add a payment method. OpenAI also uses pre-paid credits. $5 minimum, $20 covers most small business sites.
  3. Create a key at API keys → Create new secret key. Name it "SAL".
  4. Copy the key. Starts with sk-. Same one-time-display rule as Anthropic.

If you're going with Google (Gemini)

  1. Go to aistudio.google.com and sign in with your Google account.
  2. Get API key from the left sidebar → Create API key. Google offers a generous free tier — many small business sites won't pay anything in the first months.
  3. Copy the key. Long alphanumeric string. Save it somewhere safe.

Now, in WordPress, go to SAL® - AI Chat → Settings → AI. Choose your provider from the dropdown, paste your key into the matching field, pick a model from the model dropdown, and click Save Changes.

SAL encrypts the key before storing it. Nothing in your WordPress database stores the raw key after this point — even if someone exports your database, the key stays unreadable.

API key formats — what to expect
# Anthropic — sk-ant- prefix
sk-ant-api03-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-XXXXXXXX

# OpenAI — sk- prefix
sk-proj-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Google — no prefix, just long alphanumeric
AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Paste the whole key — including any prefix — into the matching
# field on the SAL Settings → AI page after picking your Provider.

Verify it's working.

Two checks. First, in the SAL Settings page, click the Test connection button next to the API key field. You should see a green "Connection verified" message within a couple of seconds.

Second, open your live site in a new browser tab (or an Incognito window if you want to avoid your admin styling getting in the way). Scroll to the bottom-right corner. You should see a small chat launcher with the SAL avatar. Click it. A chat window opens, and you can start a conversation.

Ask it something specific about your business — like "What do you do?" or "How can I get in touch?". If your homepage has that information, SAL should answer correctly, in plain language, in real time.

If you see the launcher and the chat works — you're done with install.

SAL is now reading your homepage and answering visitors. The rest of this page covers what to configure beyond the defaults: which pages SAL reads, where leads go, how to hand off to WhatsApp. But you can leave SAL exactly as it is right now and it'll work fine.

Docs / Get started / Your first chat

Your first chat.

See SAL respond on your live site for the first time. We'll walk through what to do, what to ask, and what's actually happening behind the scenes — so when things look right (or off), you know what you're looking at.

Open your site as a visitor.

The single most useful thing you can do right after installing SAL is open your site the way a real visitor sees it — not as the logged-in admin. There are a few reasons this matters:

  • Your WordPress admin bar at the top of the screen can shift SAL's launcher position by 32 pixels, so what you see isn't what your visitors see.
  • Some themes load different scripts for admins vs guests, so visual glitches show up for one and not the other.
  • If you're testing lead capture, you don't want your own admin email going into your CRM.

The easiest fix: open an Incognito window (Chrome, Edge), Private window (Safari, Firefox), or just a different browser you're not signed into. Then load your homepage.

Find the launcher.

Scroll to the bottom-right corner of your screen. You should see a small chat bubble icon — about 56 pixels across — sitting just above the corner. That's SAL's launcher.

The launcher follows you as you scroll. It stays out of the way of your content but is always within reach. Click it.

Ask SAL a question.

When you click the launcher, the chat window opens with a welcome message ("Hi — how can I help you today?" or whatever you customized it to say). The text input is at the bottom. Type your question and hit Enter.

For a first-chat sanity check, ask something specific your homepage answers. A few that work well on most sites:

  • "What do you do?" — tests that SAL is reading your homepage and can summarize what you offer.
  • "How can I get in touch?" — tests that contact info is being surfaced correctly.
  • "What are your business hours?" — tests whether the kind of detail visitors often want is reachable.

SAL should respond within two to four seconds. The response will appear word by word, streaming in — not all at once. That's intentional. It means you're seeing the AI generate the answer in real time, the same way ChatGPT does.

What's happening behind the scenes.

Every time a visitor types a question, SAL does three things, fast:

  1. Reads your page. SAL pulls the visible content of whichever page the visitor is on — the headline, the body text, the calls to action.
  2. Reads your main menu. SAL also grabs your site's primary navigation so it knows what other pages exist and roughly what each is about. That's why it can answer "where do I find your pricing?" even from your homepage.
  3. Sends both, plus the visitor's question, to your chosen AI provider. The AI reads everything you've provided as context and generates an answer grounded in that. The answer streams back to the visitor's browser as it's written.

Because the AI only sees what SAL sends, SAL is only as good as what you tell it about your business. By default that's your current page + menu. As you'll see in the Configuration section below, you can expand that to specific other pages, custom facts (things you want SAL to know that aren't on any page), and your full menu structure.

When SAL says "I don't know."

Ask SAL something your site genuinely doesn't cover — like "What's your return policy?" on a site that has no returns page — and you'll get an honest "I don't have that information on this site" response (or something similar in tone).

This is the right behavior. SAL is built to not invent answers. If your business doesn't publish refund terms anywhere, SAL won't make them up. That's the difference between an AI chat that genuinely helps and one that confidently misleads.

When you see "I don't know" responses, you have two options:

  • Publish the missing information on your site. Add a Returns page, a FAQ, a Pricing page. SAL will start using it the moment you include it in its site awareness settings.
  • Add it as a custom fact. In Settings, you can write short fact statements ("We accept returns within 30 days of purchase, no questions asked") that SAL injects into every conversation. Faster than publishing a full page when you just need to cover one thing.

If something looks off.

Three common things on a first chat and what they usually mean:

The launcher doesn't appear at all. Cache, almost always. If you use Cloudflare, WP Rocket, W3 Total Cache, LiteSpeed Cache, or your host has its own caching layer (Kinsta, WP Engine), the launcher script may not yet be in the cached version of your page. Clear the cache, hard-refresh your browser (Cmd+Shift+R / Ctrl+Shift+R), and try again. If you have a "Coming soon" or maintenance-mode plugin active, those usually block third-party scripts including SAL.

Launcher opens but no response comes back. The API key is the usual cause. Go back to SAL® - AI Chat → Settings and click Test connection. If it fails, the key needs to be re-pasted or your AI provider's credit balance is empty. Less commonly, your hosting environment may be blocking outbound requests to your AI provider's API endpoint. If you're on a very locked-down corporate host, ask them to allowlist api.anthropic.com, api.openai.com, or generativelanguage.googleapis.com depending on which provider you've chosen.

SAL is answering, but the answers are wrong or vague. This usually means SAL doesn't have access to the right information. Two checks:

  • Is the page content actually loaded? Some page builders (some Elementor templates, some custom Gutenberg blocks) render content via JavaScript after page load. SAL reads the HTML — if your content isn't in the HTML, SAL can't see it. Right-click the page → "View Page Source" — if your actual copy isn't in there, that's the issue.
  • Is the system prompt overriding things? In Settings, the system prompt tells SAL how to behave. If you've over-constrained it (e.g. "Only answer questions about pricing"), it'll ignore relevant questions about other topics. The default system prompt is a good starting point.

When the first chat works, you've validated three things.

Your plugin is installed correctly, your API key is talking to your chosen AI provider, and your site content is being read. That's the whole pipeline working end-to-end. From here, everything is tuning.

Docs / Get started / Configuration

Configuration.

Tune what SAL knows about your business, how it talks to visitors, and where leads go. This section walks the full Settings panel start to finish — what each control does, what to change first, and what to leave alone.

Open Settings.

In your WordPress admin, click SAL® - AI Chat → Settings in the left menu. The Settings page is organized into five tabs along the top:

  • Connection — AI provider, API key, model selection.
  • Behavior — system prompt, conversational tuning, fallback handling.
  • Site context — which pages SAL reads, custom facts, menu inclusion.
  • Appearance — chat title, welcome message, theme color, launcher position.
  • Leads — form fields, when to ask, lead notifications.
  • Targeting & limits — where SAL appears, rate limits, retention.
  • License — license key and activation status.

You don't have to touch all of them. The defaults work fine for most sites. We'll cover the tabs in the order you'd want to think about them — starting with Appearance (what visitors see), then Connection (the AI engine), then Site context (what SAL knows about you), then Leads (how it captures contact info).

Appearance settings.

The Appearance tab is where you tune what visitors actually see when the chat opens. The controls that matter most:

  • Chat title. Shown at the top of the chat window. Default: "Chat with us". You can change this to your business name ("Chat with Smith Aegis") or to set expectations ("Ask anything"). Keep it short — under 30 characters renders best.
  • Welcome message. The first thing visitors see when they open the chat. Default: "Hi — how can I help you today?". A more inviting variant on a services business: "Hi! Looking for help with marketing, or just exploring? Either way, I'm here." Set tone here — formal, casual, playful — and SAL will match it.
  • Theme color. The launcher button, send button, and accent color throughout the chat window. Pick a color that contrasts with your site's background. SAL ships with a black default; most users change it to their brand color.
  • Launcher position. Bottom-right (default) or bottom-left. RTL languages typically use bottom-left.
  • Show on these pages. By default, SAL launches on every page. You can restrict it to specific pages, exclude certain pages (e.g. checkout, login), or use page templates.

Exclude SAL from checkout and login pages.

If you run an e-commerce site, exclude /cart, /checkout, and /my-account. Visitors at those points are converting — you don't want a chat window pulling their attention. Use the "Exclude on these pages" field with one URL path per line.

Connection & Behavior settings.

The Connection tab is where you choose which AI provider powers SAL — Anthropic Claude, OpenAI, or Google Gemini — and paste your API key. The Behavior tab shapes how SAL sounds on your site, with one main control: your brand voice.

  • AI provider (Connection tab). Pick one: Anthropic Claude, OpenAI, or Google Gemini. You can switch any time — just paste a key from the new provider and choose a model. SAL doesn't lock you in.
  • Model (Connection tab). The dropdown changes based on your chosen provider. Anthropic offers Claude Haiku 4.5 (fastest, cheapest, recommended for chat), Claude Sonnet 4.6 (best balance), and Claude Opus 4.8 (highest quality). OpenAI offers GPT 5.4 Mini, GPT 5.4, and GPT 5.5. Google offers Gemini 2.5 Flash, Gemini 2.5 Pro, and Gemini 3.1 Pro.
  • Max response tokens (Connection tab). Default 1024. Cap on AI reply length. 1024 is a good default; raise it if visitors are asking complex questions that need longer answers.
  • Enable widget (Behavior tab). Master on/off switch — "Show chat widget on the front of the site." Leave on for normal operation.
  • Brand voice (Behavior tab). A long-form text area where you describe how SAL should sound and what it should know. This is the single most important control for SAL's conversational character. Use the placeholder {business_name} anywhere you want your site name inserted — it's substituted automatically. A recommended template ("natural, professional, 'we'-voice") is provided collapsed below the field; expand it to start from a tested baseline you can edit.
  • Rate limit (msgs/hour/IP) (Behavior tab). Number — messages per visitor IP per hour. Default 20. Lower to combat abuse, raise if real visitors are getting throttled.

You don't need to add handoff rules or mechanics to Brand voice

SAL handles WhatsApp routing, the handoff card UI, callback prompts, and site context automatically at runtime — they're appended below your brand voice on every request. Just focus on how you want to sound.

Brand voice — example starting point
# An illustrative example. The product ships with its own recommended
# template available in the collapsed section below the Brand voice
# field — start from that and adapt. {business_name} is substituted
# with your site name automatically.

You speak for {business_name}. Use "we" and "our" — you are part
of the team, not an outside observer describing it.

Tone:
- Warm and professional. Confident without being formal.
- Clear and direct. Skip filler and hedging.
- Lead with what you can answer from the context provided.

When a question needs a real person (specific pricing, custom scopes,
account-level details, claims-handling):
- Share whatever is relevant from what you do know.
- Then invite the visitor to continue with the team — WhatsApp or
  a callback are easy next steps.

Site awareness.

This is the most important tab for getting SAL answering well. It controls what SAL knows. Three things to set up.

Pages SAL reads.

By default, SAL reads whichever page the visitor is currently on. You can additionally include specific pages in the context for every conversation — useful for pages SAL should always be aware of (Pricing, Services, FAQ, About).

Click Add pages, search your site's page list, and tick the ones you want SAL to always have access to. Most sites add: Homepage, About, Pricing or Services, FAQ, Contact.

A practical limit: SAL keeps the total context under about 8,000 words. If you add too many pages, older or less relevant ones get trimmed automatically — but it's better to be intentional. Five well-chosen pages beats twenty mediocre ones.

Custom facts.

Sometimes there's information you want SAL to know that doesn't live on a published page — your delivery turnaround, your refund policy, the fact that you're closed on certain holidays, that your CEO's name is "Smith". Add these as short fact statements.

  • Keep each fact under two sentences. SAL reads them as plain text, no formatting.
  • Add the question framing if useful: "When asked about delivery times, say: orders ship within 48 hours within Nairobi, 5–7 working days for the rest of Kenya."
  • Update facts when reality changes. Stale facts make SAL confidently wrong.

SAL automatically reads your primary navigation menu so it knows the shape of your site ("we have a Pricing page, a Blog, a Contact page"). You usually want this on — it lets SAL guide visitors to the right place when it doesn't have a direct answer.

Turn it off only if your menu has internal-only items (admin links, draft pages) that you don't want SAL referencing.

Lead capture.

The Leads tab controls when and how SAL asks visitors for their contact info. This is the difference between a chat that just answers questions and a chat that grows your pipeline.

  • Trigger. When does SAL show the lead form? Default: after the first AI response. Other options: after 30 seconds, after 3 messages, manually only (visitor clicks "Get in touch"). The default is a good balance — visitors have seen value before being asked for their email.
  • Fields. Default is name, email, phone with country picker, optional message. You can add company, mark fields optional, or hide phone entirely if your business doesn't need it.
  • Required fields. Be intentional. Every required field reduces conversion. A common pattern: require name + email, make phone and company optional.
  • Submit confirmation. What SAL says after a visitor submits the form. Default: "Thanks! We'll be in touch within 24 hours." Customize to match your real response time.
  • Notification email. Where lead notifications go in addition to your integrations. Defaults to your WordPress admin email; set to a sales-specific address if you want.

Lead capture and CRM sync are separate.

This tab controls the form. The Integrations section (coming soon) controls where leads go after capture (Brevo, HubSpot, webhook). You can have lead capture on without any integrations — leads just go to your conversations dashboard and the notification email. Add integrations when you're ready.

WhatsApp handoff.

For Kenyan businesses especially, WhatsApp is often where conversations actually convert. SAL can hand off to WhatsApp at any point in a chat.

  • Your WhatsApp number. In international format with country code, no spaces or hyphens. Kenya example: 254765941351.
  • Show "Chat on WhatsApp" button. A persistent button in the chat header. Visitors can tap it any time. Recommended on.
  • Auto-offer handoff. SAL detects when a visitor's question needs human nuance (pricing negotiation, custom request, complaint) and offers WhatsApp directly. Default: on. The detection uses the AI itself, so it's reasonably calibrated.
  • Handoff message. What visitors see when SAL offers WhatsApp: "Want to continue this on WhatsApp? Click the button below." Customize to your tone.

When a visitor taps the handoff button, WhatsApp opens (web or mobile, whichever they're on) with a pre-filled message that includes a summary of what they've been discussing with SAL. They tap send. The conversation continues in your WhatsApp inbox where you'd handle it manually.

Rate limits and safety.

Found in the Targeting & limits tab (you usually don't need to touch these, but they're there):

  • Per-IP rate limit. Default: 30 messages per visitor per hour. Prevents abuse without throttling real visitors.
  • Daily site cap. Default: 1,000 messages per day across your whole site. Hard ceiling on cost. Set higher if you have heavy traffic; lower as a budget guard.
  • Block list. IP addresses or words that, if matched, refuse to engage. Useful for blocking spam patterns.

Save and watch real conversations.

Once you've configured what's important, click Save Changes and let SAL run for a few days. Go to SAL → Conversations after about a week — reading the actual transcripts will tell you exactly what to tune next. Did SAL miss a topic? Add it as a custom fact. Did visitors ask for pricing? Make sure Pricing is in your reading list.

Docs / Account & licensing / Creating your account

Creating your account.

Your SAL account lives at app.smithaegis.co.ke. It's where you manage your license, register the WordPress sites you want SAL on, view invoices, and start or convert your trial. This page covers signing up.

Sign up at app.smithaegis.co.ke.

Go to app.smithaegis.co.ke and click Start free trial. You'll need:

  • A working email address. Used for login, billing notifications, and password resets. Use a real address you check — if your license verification email gets caught in spam, your trial doesn't start cleanly.
  • A password. Minimum 12 characters. Use a password manager.
  • The URL of your first WordPress site. You can add more sites later, but you'll register at least one during signup so we can issue a license key tied to a real site.

No credit card is required. The trial is 30 days, full-featured, and ends without any charge unless you choose to convert.

Confirm your email.

Within a minute or two of signing up, you'll receive a confirmation email from support@smithaegis.co.ke. Click the link inside to verify your address. Until you confirm:

  • You can log in to the dashboard normally.
  • You can register sites and generate license keys.
  • You cannot activate SAL on a WordPress site — license verification requires a confirmed email.

If you don't see the email, check spam first. Then check that the address you signed up with is the address you're looking at. If neither works, log in to the dashboard and click Resend confirmation on the banner at the top of your account page.

Your trial starts.

The 30-day trial begins the moment you sign up — not when you confirm your email, not when you install the plugin. This is intentional: even if you take a week to get to the plugin install, you still have 23 days of real-world testing left.

What you get during the trial:

  • The full product. No feature gates. Multi-provider AI, all CRM integrations, WhatsApp handoff, conversation dashboard, CSV export — everything that's in the paid plan is in the trial.
  • Unlimited sites. Add as many WordPress sites as you want to test on. Common pattern: a staging site, a production site, and one or two client sites. All under one trial.
  • Customer support. Same channels as paid customers — email, WhatsApp, live chat at chat.smithaegis.co.ke/support. Trial users aren't second-class.

What's in the dashboard.

After signup, you land on your dashboard at app.smithaegis.co.ke. The main sections:

  • Subscription. Plan status, days to renewal, your license key and HMAC secret (the two credentials you'll paste into the WordPress plugin), site count and remaining slots, and the renew or add-a-site actions.
  • Sites. The list of WordPress sites connected to your license. Add a site, deactivate a site, manage capacity. Each active site uses one slot on your plan.
  • Billing. Invoices, payment history, and the Pay now flow when it's time to renew.
  • Downloads. The plugin ZIP file for the current SAL release. Download from here when you're ready to install on WordPress.

Recommended first steps.

The fastest path from signup to first successful chat:

  1. Confirm your email (1 minute).
  2. Download the SAL plugin from the Downloads section of your dashboard.
  3. Copy your license key and HMAC secret from the Subscription section. These are the same credentials for every site under your license.
  4. Install the SAL plugin on your WordPress site (see Installing SAL).
  5. Paste your license credentials into the plugin's License tab (see Activating SAL on your site — next page).
  6. Get an AI provider key (Anthropic, OpenAI, or Google — see the install page for setup walkthroughs).
  7. Test the chat on your live site.

End-to-end, this is typically a 10-15 minute exercise — most of which is creating accounts on third-party services. The SAL-specific work is a few minutes.

Docs / Account & licensing / Activating SAL on your site

Activating SAL on your site.

Once you've installed the SAL plugin on WordPress, you'll need to activate the license to unlock the chat. This is two short copy-and-pastes from your dashboard into the plugin's License tab.

Get your credentials from the dashboard.

Log in to app.smithaegis.co.ke. From the Subscription section:

  1. Find the Plugin credentials block. It contains both pieces you need.
  2. Copy the License key. Looks like SAL-XXXX-XXXX-XXXX-XXXX. Use the copy button next to the field.
  3. Copy the HMAC secret. Masked by default — click the show/eye icon if you want to verify it, then use the copy button. Keep it secret; anyone with both your license key and HMAC secret can activate a site under your license.

Both credentials are account-level — the same license key and HMAC secret apply to every WordPress site you activate under your license. There aren't separate per-site secrets to track.

Paste into WordPress.

In WordPress, go to SAL® - AI Chat → License. You'll see two fields under Update credentials:

  • License key. Paste the key from the dashboard.
  • HMAC secret. Paste the secret. If you're re-saving an existing license, leave this field blank to keep the existing secret.

Click Save & re-activate. The license is verified against the dashboard and the Status panel updates within seconds.

Watch for invisible whitespace

Copy-paste from web pages sometimes picks up trailing spaces or invisible Unicode characters. If activation fails on first try and you're sure the keys are correct, clear the fields and re-paste — most "license invalid" failures are clipboard quirks, not real mismatches.

What "verified" looks like.

After successful activation, the Status panel on the License tab shows:

  • Active (green badge) — or Trial during the trial period — with the renewal date.
  • Sites used. How many slots on your plan are in use (e.g. 2 / 5).
  • AI providers. Which providers are enabled for your plan.
  • WhatsApp handoff. Whether the handoff feature is enabled.
  • Footer "Powered by". Whether you can hide the attribution footer on your plan.
  • Last verified. Timestamp of the most recent successful license check.
  • Refresh now button — forces an immediate license check against the dashboard.

On the WordPress side, the launcher script now starts loading on your pages, and the rest of the SAL menu (Settings, Conversations, Integrations) becomes fully functional.

License health checks.

After initial activation, SAL keeps a quiet eye on the license. You don't need to do anything; this is just so you know what's happening in the background:

  • Periodic re-verification. SAL re-checks the license against the dashboard on a regular cadence. If anything changes (you renewed, you freed up a site slot, your subscription state changed), the plugin picks it up automatically within minutes.
  • Network-tolerant. If your site temporarily can't reach the licensing servers (your hosting had a brief outage, our servers were maintaining), SAL doesn't shut down. There's a grace period during which the cached license is honored. This is intentional — license checks shouldn't take your chat offline because of a network blip.
  • Surfaced honestly. If your license ever genuinely fails (subscription lapsed, site deactivated, etc.), the License tab will say so clearly with the specific reason and what to do.

If activation fails.

The most common causes, in order:

  1. License key or HMAC secret pasted incorrectly. Re-paste both, watch for whitespace.
  2. No site slots left. Your plan covers a fixed number of sites. If you've hit the cap (e.g. 5 / 5 in your dashboard's Sites section), either deactivate a site you're no longer using or upgrade your plan from Billing.
  3. Email not confirmed. Activation requires a confirmed email. Check your inbox, click the link, retry.
  4. Trial or subscription expired. Check the dashboard for status. Renew or upgrade, then retry activation.

For everything else, see Troubleshooting → License issues.

Docs / Account & licensing / Managing your sites

Managing your sites.

Your SAL account can run on as many WordPress sites as you want — your own, your clients', staging, side projects. Each site you activate becomes a separately billed line on your subscription, so adding and deactivating sites directly affects your monthly bill. This page covers adding sites, deactivating them, removing them, and what happens at each stage.

Adding a site.

From your dashboard at app.smithaegis.co.ke:

  1. Go to Sites.
  2. Click Add a site.
  3. Enter the WordPress site's full URL with protocol (e.g. https://yoursite.com). Don't include trailing slashes or sub-paths unless WordPress is genuinely installed in a subdirectory.
  4. Optionally name the site (e.g. "Main site", "Client A", "Staging"). The name is for your reference only; it doesn't affect anything functionally.
  5. Save.

The site is registered against one of your plan's site slots. Use the same license key and HMAC secret from the Subscription section to activate the plugin on the new WordPress install — those credentials are account-level, not per-site. See Activating SAL on your site for that flow.

Your plan covers a fixed number of sites — visible in the Subscription section ("X sites on your plan") and on the License tab in WordPress ("Sites used: X / Y"). When you fill all your slots, the dashboard's Sites section shows At capacity. To register more sites beyond that, you'll need to free a slot by deactivating an existing site, or upgrade your plan.

Deactivating a site.

Deactivation frees up the site's slot on your license so you can use it elsewhere. It can be done from either side:

  • From the plugin (WordPress side): SAL® - AI Chat → License → Deactivate license on this site. The credentials are cleared from this WordPress install, and the slot is freed in your dashboard within ~5 minutes.
  • From the dashboard (account side): Sites → find the site in Active sites → Deactivate. A confirmation panel explains: deactivating frees this site slot on your license; the chat widget on this site will stop responding within ~5 minutes (or within 24 hours on plugin versions older than 2.3.1) unless reactivated. Click Confirm.

Either path achieves the same result: the slot is returned to your pool, ready to be used on another site, and the deactivated site moves to the Previously activated list at the bottom of your Sites page.

What deactivation does.

  • Chat stops on the live site within ~5 minutes (or within 24 hours on plugin versions older than 2.3.1). The launcher no longer loads on your pages.
  • WordPress plugin stays installed. You don't have to uninstall anything. SAL's WordPress menu still exists; the Settings tabs just become inert until you reactivate.
  • Stored data is preserved on your WordPress site. Conversations, lead records, dispatch log entries — all kept in your WordPress database. Deactivation does not delete any of it. Only deleting the SAL plugin entirely from WordPress (Plugins → Delete) removes the stored data.
  • The site slot is freed and the site moves to "Previously activated". Your dashboard's Sites section reflects the freed slot immediately. You can register a new site to take its place without changing your plan, and the deactivated site stays in your account history (without consuming a slot) in case you want to reactivate it later.

Reactivating a site.

If your account still has the deactivated site registered in the Previously activated list, reactivating is a click — provided you have a free slot on your plan:

  • From the dashboard: Sites → Previously activated → find the site → Reactivate.
  • From WordPress: paste your license key and HMAC secret back into the License tab → Save & re-activate.

Either way, the chat resumes on the live site within minutes. Your stored data on the WordPress site is still there from before deactivation.

Removing a site permanently.

For sites in the Previously activated list that you don't intend to use again — a sold WordPress site, a project that was wound down, a test environment you no longer need — you can remove them from your account entirely. This is different from deactivation, which keeps the site in your history.

From the dashboard: Sites → Previously activated → find the site → Remove. The site disappears from your account history. This is irreversible — if you change your mind later, you'll need to add the site fresh.

Removal doesn't touch the WordPress installation itself. If SAL is still installed on that site's WordPress, the plugin's license check will simply fail (no matching site on the license) and the chat will stop loading. To clean up the WordPress side as well, deactivate the plugin from WordPress's Plugins page or uninstall it entirely.

Adding more site slots.

Your dashboard's Sites page shows your current quota at the top: "Your plan allows X active sites" with a usage bar (e.g. 5 / 5, At capacity). If you need more slots than your plan covers, click Add more sites — this opens a flow to upgrade your plan or purchase additional site capacity, billed against your account.

When a site's URL changes.

WordPress site URLs change more often than you'd think — migrations, domain renames, http→https, www→non-www, dev→production. SAL's licensing is URL-aware, so a mismatch makes the license check fail. Handle URL changes this way:

  1. Update WordPress first (Settings → General → both WordPress Address and Site Address). Make sure the site actually loads on the new URL.
  2. Log in to your dashboard. Sites → click the site → Edit URL. Enter the new URL. Save.
  3. Within a few minutes, the plugin's License tab will show the updated URL and verified status.

If you migrate before updating the dashboard, the plugin's license check will start failing and the chat will eventually stop. There's a grace period built into the license check so a brief mismatch doesn't take you offline immediately — but it's cleanest to update both sides on the same day.

Docs / Account & licensing / Subscription & billing

Subscription & billing.

How SAL is priced, how to pay, what to expect at renewal, and how to handle billing edge cases. Everything billing-related happens in your dashboard at app.smithaegis.co.ke.

How pricing works.

Pricing is per-site, per-month or per-year. Each active SAL site under your account is a separately billed line. Everything else is included — no per-conversation overage, no feature gates, no per-AI-provider fees on top.

  • KES 2,500 / site / month or KES 25,000 / site / year — annual saves you KES 5,000 per site (about two months free).
  • USD $20 / site / month or USD $200 / site / year — annual saves you $40 per site.

For agencies running multiple client sites, this means your monthly bill scales with the number of sites actively running SAL. A two-site portfolio is KES 5,000/month (or USD $40). A five-site portfolio is KES 12,500/month (or USD $100). Deactivate a site from the dashboard and that line drops off your next bill.

Choose KES or USD at signup based on your billing preference. The currency stays with your account; you don't need to do anything to lock it in.

What's not included: your AI provider costs. SAL is bring-your-own-key — Anthropic, OpenAI, or Google bill you directly for AI usage, with no Smith Aegis markup in between. For a moderately-trafficked site, that's typically $3-15/month in AI costs depending on which provider you choose. Google Gemini has a generous free tier that often costs nothing for small sites.

Payment methods.

SAL doesn't store payment methods. There's no card on file and no autopay. Every payment is initiated manually from your dashboard — for the initial conversion from trial to paid, and again at every renewal.

  • KES billing goes through Pesapal. From Pesapal's checkout you can pay by M-Pesa, Airtel Money, card (Visa, Mastercard), or bank transfer. M-Pesa is the most common and fastest path.
  • USD billing uses card payment (Visa, Mastercard, American Express) through Pesapal's international checkout.

To pay: dashboard → Billing → Pay now. Pesapal's checkout opens, you complete the payment, and the license updates within minutes of confirmation.

Invoices & receipts.

Every successful payment generates an invoice. You'll receive a PDF copy by email at the address on file, and all invoices are stored in your dashboard under Billing → Invoices indefinitely (no expiry).

Invoices include:

  • Smith Aegis details (Nairobi business address, PIN number).
  • Your account details (email, optional business name if you've added one).
  • Plan, period covered, per-site line items, amount, payment date, payment method.
  • Tax line where applicable (Kenya: 16% VAT included in the per-site KES prices for Kenyan-billed customers).

If you need a custom invoice (different billing entity, PO number, multi-line breakdown), email billing@smithcorp.co.ke with the details and we'll re-issue.

Converting from trial to paid.

You can convert at any time during the 30-day trial — you don't need to wait until day 30. To convert:

  1. Dashboard → Billing → Choose a plan.
  2. Pick currency (KES or USD) and billing period (monthly or annual).
  3. Confirm the per-site line items based on the sites you've activated.
  4. Click Pay now. Pesapal's checkout opens; complete payment.

Converting before the trial ends doesn't waste any days — your first paid period runs from the original trial-end date, not from the moment you paid. So you don't lose the rest of the trial period by converting on day 5.

Renewals & missed payments.

Because SAL doesn't run autopay, every renewal is a manual action. At the end of each paid period (monthly or annual), you log into the dashboard and pay for the next period — the same flow as your first conversion.

We send reminder emails before your period expires so a renewal doesn't slip by accident. If you do miss the renewal:

  • The chat stops loading on your sites within ~24 hours of the expiry date.
  • Your data stays on your WordPress site — conversations, lead records, settings, integrations all live in your WordPress database. Deactivating SAL or letting the trial expire does not delete any of it; only deleting the plugin from WordPress removes the data.
  • You can renew any time from the dashboard. Pay for the next period and the license reactivates within minutes. No re-entry of credentials, no reinstallation.

If a payment fails at Pesapal's end (M-Pesa balance, card declined, etc.), the dashboard shows the failure inline and you can retry immediately. No multi-day wait.

Cancelling — or just not renewing.

Since there's no autopay, "cancelling" is mostly just not renewing. Your current paid period runs out, the license enters the same state as a missed renewal, and your data is preserved.

If you want to formally close the account, contact billing@smithcorp.co.ke and we'll archive it.

Changing plans.

Switch between monthly and annual at your next renewal — just pick the other option at the dashboard's pay-now step. Switching the other way is also possible but rarely worth it given annual is cheaper per-month-per-site.

Switching currencies (KES ↔ USD) is supported but rare — contact billing@smithcorp.co.ke if you need this.

Billing questions.

Any billing question we haven't covered — refunds, custom contract terms, invoice format requirements, regional VAT specifics — email billing@smithcorp.co.ke. We respond same-day during East African business hours.

Docs / Account & licensing / Trial vs paid

Trial vs paid.

The short version: the trial is identical to paid in every functional way. You don't unlock new features at conversion — you just keep using the product you already evaluated. This page covers the small set of things that actually do change at the 30-day mark.

What's included during the trial.

Everything. We don't gate features behind the paid plan because a trial that hides the good parts isn't a real trial. Specifically:

  • Multi-provider AI — pick Anthropic, OpenAI, or Google, switch any time.
  • All CRM integrations — Brevo, HubSpot, Generic Webhook.
  • WhatsApp handoff with full conversation context.
  • Country-picker phone field, lead capture, lead dashboard.
  • Conversation history, transcripts, dispatch audit log.
  • Filtered CSV export.
  • Multiple sites on the license. Add and activate the WordPress sites you want to test SAL on — production, staging, client sites. The trial is free; activate the sites you're ready to evaluate it on.
  • Full support — same channels paid customers get. Email, WhatsApp, live chat at /support.

Visitors on your live site won't see any "Trial" indicator on the chat itself — the chat looks and behaves the same as on a paid account. The trial state is visible in your WordPress plugin admin (License tab) and in your customer dashboard so you always know where you stand.

What actually changes at day 30.

One thing: you need to have upgraded to a paid plan, or the license stops working and the chat stops loading on your sites. That's it. Nothing else flips, nothing else turns off, no feature degrades.

What doesn't change:

  • The product itself — same code, same models, same integrations.
  • Your data — conversations, leads, settings, integrations, all preserved on your WordPress site.
  • Your AI provider relationship — you keep paying them directly, just like during the trial.
  • Your site URLs, license credentials, plugin installation — all unchanged.

How to upgrade.

You can upgrade any time during the trial — earlier is fine, you don't lose the rest of your 30 days. Steps:

  1. Dashboard at app.smithaegis.co.ke → Billing.
  2. Pick a plan — KES or USD, monthly or annual.
  3. Confirm the per-site line items based on the sites you've activated.
  4. Click Pay now. Pesapal's checkout opens; complete payment manually.

See Subscription & billing for the full payment methods and invoice details.

If you don't upgrade.

The trial ends and the license stops working. Practically:

  • The chat stops loading on your live sites within about 24 hours of trial expiry. Visitors stop seeing the launcher; existing conversations that were already open complete normally then close.
  • Your data stays on your WordPress site. Conversations, leads, dispatch logs, and settings live in your WordPress database — deactivating SAL or letting the trial expire does not delete any of it. Only deleting the plugin entirely from WordPress (Plugins → Delete) removes the data.
  • Your dashboard account stays active. You can log in any time to see your account state and upgrade to a paid plan.

After trial expiry.

The trial is one-per-account and doesn't reactivate. If you decide to come back after the 30 days have passed, the path forward is upgrading to a paid plan — log into app.smithaegis.co.ke, pick a plan, and pay via the dashboard. Your existing WordPress installation, license credentials, and stored conversations all resume working within minutes of the paid license activating.

If you want to deactivate and reactivate an active paid license on a site (different from trial expiry — see Managing your sites), that's possible from either the plugin's License tab or the customer dashboard at any time.

Decision checklist.

By the end of your 30 days, you should know:

  • Is the AI quality good enough for your business? Did you get answers your visitors would have called you about?
  • Did at least one real lead come through that you wouldn't have caught otherwise?
  • Did the CRM integration land the lead where you needed it, in the format you needed it?
  • Does the cost (KES 2,500/site/month or KES 25,000/site/year — or USD equivalents) make sense given the leads you saw during the trial?

If yes to most, upgrade. If no — tell us why. We're a small team and trial feedback genuinely changes the roadmap. Email support@smithaegis.co.ke or open a chat at /support.

Docs / Core concepts / How SAL reads your site

How SAL reads your site.

SAL doesn't make things up. Every answer is grounded in what you've told it about your business — specific pages, structured facts, and content matched per question. This page explains the three sources of context SAL uses and why that architecture matters for answer quality.

The flow at a glance.

When a visitor sends a message, SAL doesn't just forward it to the AI provider. It builds a context package and sends both: the question + your business's relevant information. The AI answers grounded in that package, not from a generic web-scraped model. This is why answers are accurate and on-brand instead of vague or made-up.

The context comes from three sources, blended on every request:

  1. Always-on pages — content you've designated as "the AI should always know this."
  2. Key facts — structured business facts that aren't necessarily on any page.
  3. Search-based context — content matched to the specific question being asked.

Always-on pages.

Pages SAL has in context for every conversation, regardless of what the visitor asks. Configured in Site context → Always-on core pages. Two ways to populate this:

  • Auto-include from menu. Pick a menu location (typically your Primary navigation) and SAL automatically includes every page linked from it. Maintenance-free: when you add a new page to the menu, SAL picks it up on the next visit.
  • Additional content. A manual list of any pages, posts, or custom post types you want always-on, regardless of whether they're in the menu. Useful for things like FAQ posts, product pages, or a documentation hub.

Together these answer "what should the AI always know about my business?" without you needing to repeat the information anywhere else.

Key facts.

Structured business facts that may not live on any specific page. Configured in Site context → Key facts. Each fact is a label + value pair — for example:

  • Office hours → Mon–Fri 8am–5pm EAT
  • Delivery zones → Nairobi, Kiambu, Machakos (free delivery for orders over KES 5,000)
  • Founders' background → Eric and Smith founded the agency in 2019 after 10 years in Big-4 consulting.

Key facts are sent on every conversation, like always-on pages, but in a structured form that the AI can quote precisely. Use them for the small set of business specifics that visitors regularly ask about.

For everything that isn't always-on, SAL searches your site per question. When a visitor asks something, SAL finds the most relevant content on your site (top N matches), pulls a slice of each, and adds it to the AI's context for that specific question.

Configured in Site context → Search-based context. Three controls:

  • Posts/pages to include per question — how many matches to pull. Higher means more context, more token cost, slightly slower answer.
  • Words per post — how much of each match to include. Default is generous; trim down on high-traffic sites where token cost adds up.
  • Searchable content types — which post types (Posts, Pages, Products, Portfolio items) the search runs against. Restrict this if you have unrelated content types you don't want surfacing.

Why this architecture matters.

The reason answers are accurate is that SAL never asks the AI to "know your business." It asks the AI to "read this context I'm giving you and answer the question." The AI generates fluent language, but the facts come from your site.

The practical consequence: if SAL is answering wrong about your business, the fix is almost always in Site context. Either the relevant page isn't included in always-on, the fact isn't in Key facts, or the relevant content isn't being matched by search. The Troubleshooting page walks through how to diagnose each.

Docs / Core concepts / Lead capture

Lead capture.

A chat that just answers questions is helpful. A chat that captures contact details is a sales channel. SAL turns the second on by default — every conversation has the potential to leave behind a lead in your CRM. This page covers how that mechanism works.

When SAL asks for contact details.

SAL invites visitors to leave their details two ways:

  • Auto-prompt after N exchanges. Configured in Leads → Auto-prompt after N messages. After the visitor has had a few useful exchanges with the AI (default: 3), a soft inline prompt offers the lead form. The prompt is shown once per session — SAL doesn't badger.
  • Manual button. The chat widget shows a persistent button labelled with your Lead button label (customize to whatever matches your business — common choices: Request a callback, Get a quote, Book a slot, Request a Demo). Visitors can click any time, including before any conversation.

Both paths surface the same lead form. There's no penalty for visitors who use one or the other — they're alternative entry points to the same outcome.

What's in the form.

The default lead form asks for the minimum that's actually useful for follow-up:

  • Name — single field, no first/last split.
  • Email — validated against basic email format.
  • Phone — country picker + E.164 output. SAL handles the formatting; visitors just pick their country flag and type digits.
  • Company — optional, hidden by default. Enable on B2B sites where company context matters for qualification (toggle in Leads → Company field).

Every extra field reduces conversion. SAL's defaults are deliberately short. Resist the temptation to add more — let your CRM enrich the lead after capture instead.

Where leads go.

A captured lead lands in up to three places simultaneously:

  1. Your WordPress conversations dashboard. Always. Every captured lead appears in SAL® - AI Chat → Conversations with the full transcript, contact details, and page-history context.
  2. Your Notify email (if set in Leads → Notify email). A formatted email lands in your inbox with the lead's details and a link to the conversation.
  3. Your CRM (if connected). Every Integration you've configured fires asynchronously with the lead payload. Brevo, HubSpot, custom webhook — each gets its own copy.

The three destinations run independently. If your CRM is down, the email still arrives. If email's misconfigured, the lead still lands in WordPress. Defense in depth.

The lead payload.

Every captured lead becomes a structured payload — the same JSON shape sent to every integration. For the full field-by-field reference, see Lead payload schema. The headline is: contact details + journey context (pages viewed, captured-on page, referrer) + conversation summary, all in one JSON object that any modern CRM can consume.

Docs / Core concepts / Page history tracking

Page history tracking.

When a lead lands in your CRM, you don't just get a name and email — you get the journey. Which page they landed on, every page they viewed before reaching out, where they were when they finally submitted. This page explains how SAL captures that and why it changes how you follow up.

What gets tracked.

For every visitor session that starts a SAL conversation, the widget records three things in addition to the chat itself:

  • Landed-on page. The first page the visitor viewed in this session — the entry point. Useful for attribution: paid ad traffic lands on different pages than organic.
  • Pages viewed. An ordered list of every page the visitor browsed before submitting the lead form. Includes the landed-on page and the captured-on page; everything in between is in order.
  • Captured-on page. The page they were on when they actually submitted the lead form. Often different from the landed-on page — it's where the conversation closed.

All three are captured automatically. No tracking pixels, no third-party analytics calls, no cookies beyond what WordPress already sets.

Why this matters.

Without page history, a lead is just a row in a CRM. With it, you can answer questions like:

  • How serious is this lead? A visitor who viewed three case studies and the pricing page before reaching out is qualified differently than someone who landed on the homepage and immediately asked a question.
  • What were they shopping for? A visitor who viewed three different service pages is comparing offerings. A visitor who viewed the same product twice is hesitating.
  • What was the conversion driver? If most of your leads convert on the pricing page, that page is doing the work. If most convert on the FAQ, that FAQ is closing them.
  • Where did the journey start? Landing pages from paid ads, organic search, social — each tells a different story about where to invest next.

In the lead payload.

Every lead payload includes a context object with three relevant fields:

  • context.landed_on — string, the first page (e.g. "/", "/services/marketing").
  • context.pages_viewed — array of strings, in order (e.g. ["/", "/services", "/services/marketing", "/pricing", "/contact"]).
  • context.captured_on — string, where the lead form was submitted (e.g. "/pricing").

Plus context.referrer if the browser sent one (where they came from before your site). Full field reference in Lead payload schema.

Privacy posture.

Page history is collected client-side in the visitor's browser and only sent with the lead payload — never as a separate beacon, never to a third-party tracking service. If the visitor never submits a lead, the page history never leaves their browser. If they do submit a lead, the history is included as context for your follow-up, alongside the contact details they explicitly gave you.

This is meaningfully different from page-view analytics, which collect every visitor's path regardless of intent. SAL only records the path of visitors who chose to identify themselves to you.

Docs / Core concepts / WhatsApp handoff

WhatsApp handoff.

In Kenya and across much of Africa, real customer conversations don't close in a chat widget — they close on WhatsApp. SAL bridges the two: visitors get AI-grounded answers in the chat, and when they're ready to talk to a human, the handoff is one click with their conversation context already attached.

When SAL offers WhatsApp.

Two modes, both configurable in Leads → WhatsApp handoff:

  • Always-on button. A persistent "Chat on WhatsApp" button in the chat widget header. Visitors can click any time — including when they're frustrated with the AI, want a human, or simply prefer WhatsApp. Toggle this with Enable WhatsApp.
  • Smart auto-suggest. SAL detects when the AI hedges or recommends contacting a human (phrases like "I don't have that information" or "please reach out to us"). When that happens, SAL inserts a contextual prompt offering WhatsApp as the next step. Shown once per session — the AI doesn't badger.

What happens when a visitor taps it.

The visitor's WhatsApp opens — mobile app, WhatsApp Web, or WhatsApp Desktop — with a message already drafted. The message includes:

  1. Your configured Pre-fill intro. A typical phrasing: "Hi! I was using your website's AI chat and would like to speak with someone. Here's our recent conversation:" — customize to your tone.
  2. The visitor's recent conversation history with SAL — the last N exchanges, configurable via Exchanges to include (default: 3).

The visitor still has to tap Send — SAL never auto-sends a message on someone else's behalf. But the friction of "I have to summarize what I just discussed with the AI" is removed; they just tap Send and your team picks up where SAL left off.

Why this works for the African market.

SAL was built in Nairobi for a market where WhatsApp Business is the default conversation channel. The handoff isn't bolted on — it's central. Three reasons it matters:

  • Visitors expect it. If your business is on WhatsApp (and it should be), visitors look for it. A chat widget that doesn't offer WhatsApp feels foreign.
  • Conversion happens there. Price negotiations, scheduling, follow-up questions — these naturally move to WhatsApp. SAL gets the visitor 80% of the way; WhatsApp closes the deal.
  • Context transfers. Without SAL, the visitor opens WhatsApp, your team asks "what are you looking for?", and they re-explain. With SAL, the conversation is already there. The first WhatsApp message your team sees is a continuation, not a starting line.

Setup essentials.

For SAL's WhatsApp handoff to work, you need:

  • A WhatsApp Business number registered at business.whatsapp.com. Personal WhatsApp numbers technically work but lose business features (away messages, quick replies, multiple devices).
  • The number entered in SAL — Settings → Leads → WhatsApp number, in E.164 format with country code, no +, no spaces. Kenya example: 254712345678.
  • Someone on the receiving end who'll actually pick up. SAL hands off; your team has to be there to catch the handoff.
Docs / Integrations / Overview

Integrations overview.

SAL turns every captured lead into a dispatched event — sent in parallel to every CRM, webhook, or inbox you've connected. This page covers the dispatch model, what gets sent, what happens on failure, and where to look when something doesn't arrive.

How dispatch works.

When a visitor submits the lead form in a SAL chat, three things happen in sequence:

  1. The lead is saved. SAL writes the contact details, the full conversation transcript, and the visitor's page history into the WordPress database. This happens first because it's the source of truth — if anything else fails, the lead is still captured.
  2. The visitor gets a confirmation. SAL shows the "Thanks, we'll be in touch" message right away. The visitor doesn't wait for any of the downstream syncing.
  3. The dispatch fires. SAL fans out the lead payload to every integration you've connected — Brevo, HubSpot, webhook, all of them — in parallel. Each integration runs in its own queue, so a slow HubSpot doesn't block a fast webhook.

This separation matters in practice. The visitor experience is decoupled from your CRM's mood. If HubSpot has a slow afternoon, your visitors don't see it. If Brevo is down, your leads still land in the SAL conversations dashboard.

Built-in connectors.

Three connectors ship with SAL today. Each is configured independently — you can run any combination, including all three at once.

  • Brevo — Native integration with Brevo's contacts API. Best for businesses already using Brevo for email marketing, newsletters, or transactional sends. Brevo setup →
  • HubSpot — Native integration with HubSpot's contacts CRM. Best for sales-led businesses where leads need to land in a pipeline. Uses HubSpot's Private App tokens (the modern, recommended auth method). HubSpot setup →
  • Generic Webhook — Universal escape hatch. Sends each lead as a JSON POST to any URL you provide. Use this for Zapier, Make, n8n, Slack, custom backends — anything that can receive an HTTP request. Webhook setup →

The lead payload.

Every integration receives the same payload — what differs is how each one maps it to its destination. Brevo maps to Brevo attributes, HubSpot maps to HubSpot properties, the webhook just forwards the raw JSON. Here's what's in the payload:

SAL lead payload — JSON
{
  "lead_id": "lead_a8f3c2b1",
  "captured_at": "2026-06-05T14:32:18+03:00",
  "contact": {
    "name": "Amina Otieno",
    "email": "amina@example.co.ke",
    "phone": "+254712345678",
    "phone_country": "KE",
    "company": "Acme Ltd"
  },
  "context": {
    "landed_on": "/pricing",
    "captured_on": "/contact",
    "pages_viewed": ["/", "/pricing", "/about", "/contact"],
    "referrer": "https://google.com/",
    "user_agent": "Mozilla/5.0..."
  },
  "conversation": {
    "message_count": 7,
    "summary": "Visitor asked about enterprise pricing for 20+ seats.",
    "transcript_url": "https://yoursite.com/wp-admin/admin.php?page=sal-conversations&id=..."
  },
  "site": {
    "name": "Your business name",
    "url": "https://yoursite.com"
  }
}

For a full field-by-field reference (which fields are always present, which are nullable, formatting rules for phone numbers), see the Lead payload schema in the Reference section.

Retry behavior.

Networks fail. Endpoints time out. APIs have bad afternoons. SAL handles all of this with bounded retries.

When a dispatch fails, SAL retries up to three times with exponential backoff — the gap between attempts widens with each retry so a momentarily-overloaded receiver gets a chance to recover before SAL gives up.

After the third failure, SAL marks the dispatch as permanently failed. The lead is still in your conversations dashboard — you can manually retry from there once the underlying issue is fixed.

Smart retry classification.

SAL doesn't blindly retry every failure. A connection timeout or an HTTP 500 from the destination gets retried (those usually recover). An HTTP 401 (bad credentials) or 422 (validation error) does NOT — those won't succeed on retry, so SAL gives up immediately and surfaces the error to you. This stops your dispatch log from filling up with the same hopeless attempt for 5 hours.

The dispatch log.

Every dispatch attempt — successful, failed, retrying — is logged. You'll find the log in two places:

  • Per-conversation: Open any conversation in SAL → Conversations and scroll to the bottom. You'll see a status badge for each integration ("Brevo · Sent · 2 sec", "HubSpot · Failed · 3 attempts"). Click any badge for the full attempt history with HTTP responses.
  • Global: SAL → Conversations → Dispatch log shows every attempt across all conversations, filterable by integration and status. Best place to spot patterns ("HubSpot has been failing all afternoon").

For the full dispatch log walkthrough, see the Dispatch audit log page in the Admin guide.

Multiple integrations in parallel.

Running two or three integrations simultaneously is the norm, not the exception. SAL doesn't dedupe across integrations — each one gets its own copy of the lead. A common Kenyan SMB setup:

  • Brevo for the marketing list. Every lead joins the newsletter.
  • HubSpot for the sales team. Every lead becomes a contact in the pipeline.
  • Slack webhook for instant team notifications. Every lead pings the #sales channel so someone can WhatsApp them within an hour.

You configure each integration independently. They run in parallel. If one fails, the others still succeed. If you remove one, the others keep going.

Docs / Integrations / Generic Webhook

Generic Webhook.

Send every SAL lead to any URL you control — Zapier, Make, n8n, Slack, your own backend. Webhooks are the universal escape hatch when SAL doesn't have a native connector for your tool.

What a webhook is.

A webhook is a URL on your server (or someone else's) that receives HTTP POST requests when something happens. SAL POSTs each captured lead to your webhook URL with a JSON body. Your webhook handler reads the JSON and does whatever you want with it — store in a database, forward to Slack, trigger an automation, anything.

Webhooks are the most flexible integration option because they don't care what's on the receiving end. Zapier exposes catch-hook URLs. Make.com exposes custom webhooks. Slack has incoming webhooks. n8n has webhook nodes. Your own backend can have whatever you write.

Add the integration.

  1. Open your SAL admin at SAL → Integrations.
  2. Click "Add integration" and choose Generic Webhook.
  3. Give it a name you'll recognize later — "Zapier · sales pipeline" or "Slack · #leads channel" — especially if you'll have multiple webhooks.
  4. Paste your webhook URL into the URL field.

The webhook URL.

Wherever you want SAL to POST. Some examples:

  • Zapier: Create a new Zap, set "Webhooks by Zapier" as the trigger, choose "Catch Hook", copy the URL Zapier provides.
  • Make.com: Create a new scenario, add a "Webhooks → Custom webhook" module, copy the URL.
  • Slack: In Slack admin, install the "Incoming Webhooks" app, generate a webhook for the channel you want. Note that Slack webhooks expect a specific JSON shape — you'll likely want a transform layer (like Zapier or Make) between SAL and Slack rather than pointing SAL directly at Slack.
  • Your own backend: Whatever URL your server handler lives at. Must be HTTPS in production — HTTP is rejected.

The HMAC signature.

Optional but strongly recommended. SAL signs each request using HMAC-SHA256 with a secret you provide. Your handler can verify the signature to confirm the request actually came from your SAL site (and isn't someone POST-ing bogus data to your URL).

  1. In the SAL admin, click "Generate signing secret" — SAL creates a strong random secret.
  2. Copy the secret and store it in your destination's environment (Zapier secret variable, Vercel environment variable, .env file, etc.).
  3. Save the integration. SAL will now send the signature in the X-SAL-Signature header on every request.

On the receiving end, you re-compute the signature locally using the same secret and compare. If they match, the request is genuine.

What gets sent.

The full SAL lead payload in the request body, as JSON. Plus these headers:

  • Content-Type: application/json
  • X-SAL-Event: lead.captured — identifies what kind of event this is (lead.captured is currently the only event; more in future versions)
  • X-SAL-Signature: <hex> — the HMAC-SHA256 signature, if you've configured a secret
  • X-SAL-Timestamp: <unix-seconds> — when SAL sent the request (useful for rejecting replays)

Verifying the signature.

The signature is HMAC-SHA256(secret, raw_body). Here's verification in Node.js, which translates straightforwardly to other languages:

Verify SAL webhook signature — Node.js
const crypto = require('crypto');

function verifySalSignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  // timingSafeEqual prevents timing-attack leaks
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In an Express handler:
app.post('/sal-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-sal-signature'];
  const ok = verifySalSignature(req.body, sig, process.env.SAL_SECRET);
  if (!ok) return res.status(401).send('Bad signature');

  const lead = JSON.parse(req.body);
  // Process the verified lead...
  res.status(200).send('OK');
});

Verify against the raw body, not the parsed JSON.

HMAC signatures are computed over the exact bytes SAL sent. If you parse JSON first and re-stringify it, whitespace and key order can differ, the signatures won't match, and you'll think your secret is wrong when it isn't. Configure your framework to give you the raw body for the SAL endpoint specifically (in Express: express.raw()).

Test the integration.

Click Test connection in the SAL admin. SAL sends a fake-lead payload (with lead_id: "test_lead") to your URL. You should see:

  • A 200 response within ~10 seconds (SAL gives up after 10s timeout)
  • The fake lead arriving at your destination (check Zapier task history, Slack channel, your backend logs)
  • A green "Connection verified" message in SAL

If you're still building your receiving endpoint, use webhook.site — paste their URL into SAL, run a test, and inspect the exact payload SAL is sending. Helps debug receiving-side issues by giving you a known-good intermediate.

When dispatches fail.

A few common patterns in the dispatch log:

  • Connection timeout (10s). Your endpoint took too long to respond. SAL retries. Either speed up your handler or move the heavy work to a queue and respond fast.
  • HTTP 401 / "Bad signature". Either you haven't set your secret on the receiving side, or you're verifying against the parsed body instead of the raw body. See the warning above.
  • HTTP 4xx other. Your endpoint is rejecting the payload. SAL gives up immediately (no retries on 4xx). Check your endpoint logs to see why.
  • HTTP 5xx. Your endpoint crashed. SAL retries up to 3 times. If it keeps crashing, the lead gets permanently failed and you'll need to fix the bug + manually replay.
Docs / Integrations / Brevo

Brevo.

Sync SAL leads into your Brevo contacts in under a minute. Every captured lead lands as a new contact in the list you choose, with name, email, and phone mapped to Brevo's standard attributes.

What you need.

  • A Brevo account — free tier is fine for setup and testing. Most Kenyan SMBs use the Lite or Premium plan.
  • A Brevo API key (generated in your Brevo dashboard — instructions below).
  • At least one contact list in Brevo where new SAL leads will land. If you don't have one yet, create one in Contacts → Lists → Create a list.

Generate a Brevo API key.

  1. Log in to Brevo at app.brevo.com.
  2. Open Settings from the avatar menu in the top-right corner.
  3. Click "SMTP & API" in the settings sidebar.
  4. Go to the "API Keys" tab and click Generate a new API key.
  5. Name the key something like "SAL — yoursite.com" so you'll know what it's for if you ever audit your keys.
  6. Copy the key. Brevo shows it once. Save it somewhere safe before you close the dialog. It starts with xkeysib-.

Add the integration in SAL.

  1. Open SAL → Integrations in your WordPress admin.
  2. Click "Add integration" and choose Brevo.
  3. Paste your Brevo API key into the API key field.
  4. Click "Connect" — SAL validates the key with Brevo and fetches your contact lists.

Like all credentials in SAL, the Brevo API key is encrypted with AES-256 before storage. Even if your WordPress database is exported, the key stays unreadable.

Choose a target list.

Once SAL has validated your key, it shows a dropdown of your Brevo lists. Pick the one new SAL leads should join.

Most setups use a dedicated "Website leads" or "SAL captures" list — keeps SAL leads separate from leads you've imported from other sources, making it easier to track conversion rates and clean up over time.

Attribute mapping.

SAL maps the lead payload to Brevo's standard contact attributes:

  • NAME ← the first part of the visitor's full name (everything before the first space)
  • SURNAME ← everything after the first space (or blank if no space)
  • EMAIL ← the visitor's email (this is also the unique identifier Brevo uses to dedupe)
  • SMS ← the visitor's phone in E.164 format (e.g. +254712345678)
  • COMPANY ← the company name (if captured)

If you have custom attributes in your Brevo account that you want SAL to populate, contact support — custom attribute mapping is a 2.2.0 feature in development.

Phone number handling.

Brevo requires phone numbers in E.164 format — international format with the + prefix, country code, and number, no spaces or dashes. SAL formats numbers correctly because the chat's phone capture uses a country picker that produces E.164 output natively.

The phone goes into Brevo's SMS attribute (Brevo doesn't have a separate "phone" attribute — SMS is the canonical one for messaging-related sends).

If Brevo rejects the SMS attribute

Brevo sometimes rejects phone numbers it considers invalid (test numbers, certain country codes, numbers it's seen rejected before). When this happens, SAL retries the dispatch without the SMS field — the contact still lands in Brevo with name and email, just no phone. You'll see a partial-success note in the dispatch log. You can fix it manually by editing the contact in Brevo.

Test the connection.

Click Test connection in the SAL admin. SAL sends a fake-lead contact to your chosen Brevo list. Within a few seconds, you should see a "Connection verified" message, and a test contact (test@example.com) appear in your Brevo list.

You can delete the test contact afterward, or just leave it — SAL ignores it on subsequent runs.

Common gotchas.

  • Dedup by email. Brevo dedupes contacts by email address. If a visitor submits the same email twice, the second submission updates the existing contact (with the latest name, phone, company) instead of creating a duplicate. This is usually what you want.
  • Unsubscribed contacts re-subscribe. If a visitor previously unsubscribed and then comes back through SAL with the same email, Brevo's policy may treat them as still-unsubscribed. Check Brevo's compliance settings if this matters for your sends.
  • API rate limits. Brevo's free tier limits API calls per second. If you suddenly get a burst of leads (e.g. you ran an ad campaign), some may queue and arrive a few seconds later. The dispatch log will show successful sends with slight delays — that's normal.
Docs / Integrations / HubSpot

HubSpot.

Sync SAL leads into HubSpot as new contacts in your sales pipeline. SAL uses HubSpot's Private App tokens — the modern, recommended authentication method, no OAuth round-trips required.

What you need.

  • A HubSpot account. Any tier works, including the free CRM tier — SAL only uses contact APIs that are available across all plans.
  • A Private App access token created in HubSpot with the right scopes. Instructions below.

Create a Private App.

Private Apps replaced HubSpot's legacy API keys in 2022. They're per-app tokens with granular scope control — the modern equivalent of a service account.

  1. Log into HubSpot at app.hubspot.com.
  2. Open Settings from the gear icon in the top-right.
  3. Navigate to Integrations → Private Apps in the left sidebar.
  4. Click "Create a private app".
  5. Name the app something descriptive — "SAL — yoursite.com" works.
  6. Add a logo (optional, helps with audit log readability).
  7. Skip to the Scopes tab — this is where the important configuration happens.

Required scopes.

On the Scopes tab, SAL needs exactly two CRM scopes to create and update contacts:

  • crm.objects.contacts.read — to check if a contact already exists before creating
  • crm.objects.contacts.write — to create new contacts and update existing ones

That's it for the basic setup. Don't grant extra scopes you don't need — the principle of least privilege applies to API tokens just like to people.

After you've ticked those two boxes, click Create app. HubSpot generates the access token and shows it to you once. Copy it — it starts with pat-.

If you want lifecycle stage updates

If you've set up a lifecycle stage workflow in HubSpot and want SAL to set the lifecycle stage on new contacts (e.g. "lead", "marketingqualifiedlead"), also enable crm.schemas.contacts.read. Without this scope, SAL creates contacts without a lifecycle stage and your HubSpot defaults apply.

Add the integration in SAL.

  1. Open SAL → Integrations in your WordPress admin.
  2. Click "Add integration" and choose HubSpot.
  3. Paste your access token (the pat-... string from HubSpot).
  4. Click "Connect" — SAL validates the token by making a quick read call against HubSpot's contacts API.

Like all credentials, the token is AES-256 encrypted before storage in your WordPress database.

Property mapping.

SAL maps the lead payload to HubSpot's standard contact properties:

  • firstname ← first part of the visitor's name
  • lastname ← everything after the first space
  • email ← the visitor's email (HubSpot dedupes on this)
  • phone ← the visitor's phone in E.164 format
  • company ← company name if captured
  • website ← your SAL site's URL (where the lead came from)
  • hs_lead_status ← "NEW" by default
  • lifecyclestage ← "lead" (if the schemas scope is enabled)

If your HubSpot has custom properties you want SAL to populate, that's coming in 2.2.0 — for now, you can use a Generic Webhook in parallel to handle custom-property writes via Zapier or a small backend.

Lifecycle stage.

By default, SAL sets lifecyclestage: "lead" on every new contact. This is HubSpot's standard top-of-funnel value.

If your HubSpot pipeline uses different stage names (e.g. you've renamed "lead" to "Inquiry" or added a custom stage), set the lifecycle stage manually in the SAL admin's HubSpot integration settings to match your HubSpot setup. Wrong stage names cause HubSpot to silently set the contact with no stage at all.

Test the connection.

Click Test connection in the SAL admin. SAL creates a fake-lead contact (test@example.com) in your HubSpot. Verify by going to your HubSpot contacts and finding the test contact. Delete it after, or let it sit — SAL won't recreate it on subsequent test runs (HubSpot dedupes by email).

Common gotchas.

  • "Insufficient scopes" error. The most common HubSpot integration issue. Go back to your Private App's Scopes tab in HubSpot, confirm the two required scopes are ticked, and save. If you've added lifecycle stage support, also confirm the schemas scope.
  • Lifecycle stage silently null. You set lifecyclestage: "lead" but your contact has no stage in HubSpot. Almost always means your pipeline has the stage renamed (e.g. "qualifiedlead" instead of "lead"). Check your pipeline's stage internal names in HubSpot settings.
  • Dedup updates an existing contact. HubSpot dedupes by email. If a visitor submits a lead with the same email as an existing contact, HubSpot updates that contact (name, phone, etc.) instead of creating a new one. This is usually correct — but if you have a heavily-customized contact and don't want SAL touching it, exclude that email at the SAL side.
  • "Property does not exist" errors. Rare, but possible if your HubSpot account has had a Contact property deleted. Restore the property in HubSpot, or exclude that field at the SAL side. Email support if you hit this — it usually needs a custom config adjustment.
Docs / Admin guide / Settings

Settings.

Complete reference for every setting in SAL's WordPress admin. If you're setting up SAL for the first time, the Configuration walkthrough is the better starting point — this page is for when you need the full list.

Where to find Settings.

In your WordPress admin, click SAL® - AI Chat in the left sidebar. The Settings page is organized into seven tabs along the top: Connection, Behavior, Site context, Appearance, Leads, Targeting & limits, and License. All settings save independently — clicking Save Changes only commits the tab you're currently on.

Connection tab.

What powers SAL's responses. Pick any of three providers — Anthropic, OpenAI, or Google — and switch any time. You bring your own API key for whichever you choose, and pay the provider directly.

  • AI provider. Dropdown — Anthropic Claude, OpenAI, or Google Gemini. Each provider stores its own API key independently; switching previews the new provider's fields. Click Save Changes to apply.
  • {Provider} API key. Password field. The field label updates to match your selected provider. Anthropic's key starts with sk-ant- (from console.anthropic.com), OpenAI's starts with sk- (from platform.openai.com), Google's is a long alphanumeric string (from aistudio.google.com). All keys are stored encrypted. Leave the masked value to keep your existing key; paste a new one to rotate.
  • Model. Dropdown — populated based on the provider selection.

    Anthropic: Claude Haiku 4.5 (fastest, cheapest, recommended for chat), Claude Sonnet 4.6 (best balance of quality and price), Claude Opus 4.8 (highest quality).

    OpenAI: GPT 5.4 Mini (fastest, cheapest), GPT 5.4 (balanced default), GPT 5.5 (highest quality).

    Google: Gemini 2.5 Flash (fastest, cheapest), Gemini 2.5 Pro (balanced), Gemini 3.1 Pro (highest quality, latest generation).
  • Max response tokens. Number — cap on AI reply length. Default: 1024. 1024 is a good default for most chat use cases; raise it if visitors are asking complex questions that need longer answers.
  • Test connection. Section with a Send test ping button — fires a minimal API call to your chosen provider to verify the key works and your hosting environment can reach the provider's servers.

Which provider should you pick?

Anthropic (Claude) tends to be the best at long, nuanced answers and feels most "brand voice" friendly out of the box. OpenAI (GPT) is often the cheapest of the three for equivalent quality, and the brand most visitors already know. Google (Gemini) has the most generous free tier (you may not pay anything for low-traffic sites in the first months) and the latest 3.1 Pro is competitive with the top tier of the other two. If you're undecided, start with Anthropic Claude Haiku 4.5 — it's the default for a reason.

Behavior tab.

How SAL behaves at runtime — whether the widget is enabled, the brand voice it uses, and the per-IP rate limit.

  • Enable widget. Checkbox — "Show chat widget on the front of the site." Master switch for the launcher; unchecking takes SAL off your live site without uninstalling.
  • Brand voice. Long-form text area that shapes how the AI sounds — your voice, tone, and business facts. Use the placeholder {business_name} anywhere you want your site name inserted; it's substituted automatically. A recommended template ("natural, professional, 'we'-voice") is collapsed below the field — expand it to start from a good baseline you can edit.
  • Rate limit (msgs/hour/IP). Number — messages per visitor IP per hour. Default: 20. Lower to combat abuse, raise if your real visitors are getting throttled.

You don't need to add handoff rules or mechanics here

SAL handles WhatsApp routing, the handoff card UI, callback prompts, and site context automatically at runtime — they're appended below your brand voice on every request. Just focus on how you want to sound.

Site context tab.

Controls what site information is fed to the AI on every conversation. The richer this is, the better the AI can answer questions about your business. Three sub-sections:

Always-on core pages

  • Auto-include from menu. Checkbox + menu picker. When enabled, every page linked from the chosen menu location (e.g. Primary) is sent to the AI as context. Best practice: enable for your main navigation so the AI always knows about your About, Pricing, Contact, etc.
  • Additional content. Multi-select list of all pages, posts, and custom post types on your site, grouped by type. Hold Ctrl/Cmd to select multiple. These items are always sent to the AI in addition to any menu pages above. Refresh list rebuilds the list after you've added new content.

Key facts

Quick facts always provided to the AI — things like office hours, pricing, contact details. Use this for info that may not be in your posts or pages.

  • Label / Value pairs. Add fact-by-fact (e.g. Label: Office hours Value: Mon–Fri 8am–5pm EAT). Click + Add fact to add another row.

Search-based context

SAL can search your site's content per-question to surface the most relevant material. Tune how aggressively it does so:

  • Posts/pages to include per question. Number — top relevance matches for each user message. Default: 5. Set to 0 to disable search-based context entirely (and rely only on the always-on pages above).
  • Words per post. Number — how much of each search-matched post to include. Default: 2000. Larger = better answers, higher token cost.
  • Searchable content types. Checkboxes for each content type on your site (Posts, Pages, Products, Portfolio items, etc.). Choose which the AI can search through when answering.

Appearance tab.

The controls that shape what visitors see when they open the chat.

  • Widget title. Text — appears at the top of the open chat window. Default: SAL - AI Chat. Customize to your business name or tone-setter.
  • Greeting message. Text — the first thing visitors see when the chat opens. Example: Hi — how can I help you today?. Sets the tone for the conversation.
  • Input placeholder. Text — the prompt text inside the message-input field before the visitor types anything. Examples: Ask us anything, Type your question…, How can we help?. Useful as a soft invitation to engage.
  • Accent color. Color picker — launcher background, send button, accent highlights. Pick something that contrasts with your site's background.
  • Position. Dropdown — Bottom right (default) or Bottom left. RTL languages typically use bottom-left.
  • Subtle pulse. Checkbox — "Animate the launcher on first page load to draw attention." Default: on. Soft visual cue that the chat is available without being pushy.
  • Default state. Dropdown — controls whether the chat panel is open or closed when a visitor arrives:

    Closed — visitors see only the launcher bubble and click it to start a chat. Least intrusive.

    Open on first visit — the panel opens automatically the first time a visitor lands on any page in their session, then stays closed for the rest of that session. Friendly without being pushy.

    Open — the panel opens on every page load. Visitors can close it for the current page, but the next page reopens it. Use sparingly — most appropriate for landing pages where chat is the primary conversion path.
  • Attribution footer. Checkbox — "Hide 'Powered by' footer." The footer is shown by default. Tick to hide it for white-label deployments (availability depends on your plan).

Leads tab.

How SAL captures contact details and (optionally) hands visitors off to WhatsApp. The tab has two sections.

Lead capture

  • Enable lead capture. Checkbox — "Allow visitors to leave their email/name in the chat." Master switch for the lead form.
  • Lead button label. Text — what the chat widget's lead-capture button says. Common examples: Request a callback, Book a slot, Get a quote, Talk to us, Request a Demo. Match it to your business's primary conversion intent.
  • Auto-prompt after N messages. Number — inline prompt shown once after this many exchanges. Default: 3. Set to 0 to disable the auto-prompt entirely (visitors can still click the lead button manually).
  • Notify email. Email address that gets notified when a lead comes in. Leave blank for none. SAL emails this address with the lead's details and a link to the conversation transcript.
  • Test notification. Send test notification button — fires a sample lead-notification email to the Notify email above and shows the delivery result inline. Use this to verify SMTP works on your site before relying on it for real leads. The last successful delivery timestamp is shown next to the button.
  • Email when sinks set. Checkbox — "Also send the admin notification email when integrations are configured." Default: on. When you set up a CRM connector under SAL → Integrations, leads are delivered there automatically; keep this checkbox enabled if you also want the admin email, disable to stop duplicate notifications.
  • Company field. Checkbox — "Show an optional Company / business name field in the lead form." Useful on B2B-leaning sites where company context helps qualify the lead. Keep disabled on consumer-facing sites to keep the form short — every extra field reduces conversion.

WhatsApp handoff

Add a "Chat on WhatsApp" button that hands the visitor off to a human agent. When enabled, the AI will also automatically suggest WhatsApp when it cannot answer a question.

  • Enable WhatsApp. Checkbox — "Show 'Chat on WhatsApp' button in the widget header."
  • WhatsApp number. Country code + number, digits only, no + or spaces. Kenya example: 254712345678.
  • Button label. Text — default Chat on WhatsApp. Localize if needed (e.g. Swahili: Soma kwa WhatsApp).
  • Pre-fill intro. Long text — the message that's pre-filled in WhatsApp when the visitor clicks the button. The visitor's recent chat history is appended below this intro automatically.
  • Exchanges to include. Number — how many recent user/AI exchanges to include in the pre-filled WhatsApp message. Default: 3. Set to 0 for no chat history.
  • Smart auto-suggest. Checkbox — "Inline-prompt the visitor when the AI hedges or suggests contacting someone." Detects phrases like "I don't have that information" or "please contact us" and offers WhatsApp as the next step. Shown once per session.

Targeting & limits tab.

Where SAL appears, where it doesn't, who sees it, and a protective per-conversation token cap.

  • Include URL patterns. Long text — one URL pattern per line, wildcard * supported. Empty means show everywhere. Examples: /blog/*, /services/*.
  • Exclude URL patterns. Long text — pages where the widget should NEVER appear. Excludes win over includes. Default values include /wp-admin/* and /wp-login*.
  • Hide for logged-in users. Checkbox — "Do not show the widget to logged-in users." Useful when SAL is for prospects, not existing customers logged into a member area.
  • Exclude roles. Checkboxes for each WordPress role on your site (Administrator, Editor, Author, Contributor, Subscriber, Customer, Shop manager, etc.). Tick a role to hide SAL from users with that role. Defaults to no exclusions.
  • Per-conversation token cap. Number — combined input + output tokens for a single conversation. Default: 50000. Set to 0 for unlimited. Stops a single visitor from running up your AI bill with an open-ended chat.

License tab.

Where your SAL license is activated and verified against your account at app.smithaegis.co.ke. See Activating SAL on your site for the full activation walkthrough. The tab has three sections.

Status

  • Active or Trial badge with the renewal/expiry date.
  • Sites used — how many of your plan's site slots are in use (e.g. 2 / 5).
  • AI providers — which providers are enabled for your plan (Anthropic, OpenAI, Google).
  • WhatsApp handoff — whether the feature is enabled on your plan.
  • Footer "Powered by" — whether you can hide the attribution footer on your plan.
  • Last verified — timestamp of the most recent successful license check.
  • Refresh now button — forces an immediate license check against the dashboard.

Update credentials

  • License key. The account license key from your dashboard (format SAL-XXXX-XXXX-XXXX-XXXX).
  • HMAC secret. The account HMAC secret. Leave blank to keep the existing secret; paste a new value only if rotating.
  • Save & re-activate button — commits the credentials and triggers a fresh license check.

Deactivate this site

Frees up this site's slot under your license so you can use it on another site. Your credentials are also cleared from this WordPress install. Click Deactivate license on this site to perform the action — the site's slot is returned to your pool within minutes.

Resetting to defaults.

Each tab has a Restore defaults link in its bottom-right corner. Clicking restores that tab's settings to factory values without touching the others. There's a confirmation prompt because the action isn't reversible.

For a full reset across all tabs, deactivate and reactivate the plugin from Plugins → Installed Plugins. Settings clear on reactivation. Conversations and integrations are kept.

Settings interact in two ways worth knowing.

System prompt overrides site awareness. If your system prompt says "only discuss pricing," SAL will ignore other topics even if those pages are in the site awareness list. The system prompt is the highest-authority instruction.

Custom facts supplement, don't replace. Custom facts are added to whatever SAL already reads from your pages. If a fact contradicts the page, the more recent context (the page) typically wins.

Docs / Admin guide / Conversations dashboard

Conversations dashboard.

Every conversation visitors have with SAL — successful, abandoned, lead-captured, anonymous — lives in one place. This is where you read transcripts, follow up on leads, and spot what visitors are actually asking.

Where to find it.

In your WordPress admin, click SAL® - AI Chat → Conversations. The page loads with the most recent conversations at the top.

The list view.

The main view is a chronological list with one row per conversation. Each row shows:

  • Visitor identifier. Name if a lead was captured, or "Anonymous · IP-suffix" if not. Tap to open the conversation detail.
  • First message snippet. The visitor's opening question, truncated to ~80 characters. Useful for scanning what people are asking.
  • Message count. Total messages exchanged.
  • Lead status. A badge: Lead captured (green) or No lead (gray).
  • Dispatch status. A row of per-integration badges showing whether the lead was successfully sent to Brevo, HubSpot, your webhook. • = success, ! = failed, ↻ = retrying.
  • Captured at. Relative timestamp ("2 hours ago", "yesterday").

Filters at the top.

Five filters narrow the list without affecting the underlying data:

  • Date range. Last 7 days (default), last 30 days, last 90 days, all time, or a custom range.
  • Lead status. All / With lead / Without lead.
  • Dispatch status. All / All dispatched OK / Has a failed dispatch / Currently retrying.
  • Source page. Where the conversation started. Useful for understanding which pages generate the most chat (and the most leads).
  • Search. Free-text search across visitor name, email, conversation snippets. Hits show a yellow highlight on the matching text.

The detail view.

Clicking any conversation row opens the detail view. Three columns on desktop, stacked on mobile:

  • Left: visitor + page journey. Name, email, phone (with country code), company. Below that: the page history — every page the visitor viewed before submitting the lead, in order, with timestamps. The page where the lead was captured is highlighted.
  • Center: transcript. The full conversation in chat bubble format. Visitor messages right-aligned, SAL messages left-aligned. Streaming indicators and edit markers preserved as they happened.
  • Right: dispatch + actions. Per-integration dispatch status (badges with attempt details on hover), and actions: Mark as handled, Resend dispatch, Archive, Delete.

Dispatch badges.

Each integration you've connected gets its own badge on every conversation row. The badge state reflects the most recent dispatch attempt:

  • Green dot. Successfully sent. Tap to see the timestamp and response.
  • Amber arrow. Retrying. Tap to see how many attempts have been made and when the next one fires.
  • Red exclamation. Permanently failed (after 3 retries, or after a non-retryable error like a 401). Tap to see the error message.
  • Gray dash. Not yet dispatched. Either the lead is still being processed, or this integration was added after the lead was captured (SAL doesn't backfill historic leads automatically).

For the full dispatch detail per attempt, see the Dispatch audit log.

Lead actions.

Three per-conversation actions in the detail view:

  • Mark as handled. Adds a checkmark to the conversation row. Use this when a team member has followed up — keeps the list scannable for what still needs attention. Filterable via the dispatch status filter.
  • Resend dispatch. Manually re-fires the dispatch to all integrations. Use this when a previously-failed dispatch's underlying issue is fixed (e.g. you renewed a HubSpot token). Each integration runs through its full retry behavior again from scratch.
  • Archive. Hides the conversation from the default view (but keeps the data). Filterable via "Show archived". Useful for old conversations you've handled but don't want to permanently delete.
  • Delete. Permanent. Erases the conversation, transcript, lead details, and dispatch log entries. Confirmation prompt because this can't be undone. Used for GDPR/privacy requests or explicit visitor deletion requests.

Bulk actions.

Select multiple conversations using the checkboxes on the left of each row, then choose an action from the bulk-action dropdown at the top:

  • Mark as handled (bulk) — checkpoint a batch you've worked through.
  • Archive (bulk) — hide old conversations en masse.
  • Delete (bulk) — permanent, with confirmation.
  • Export to CSV — exports the current selection (or the current filtered view if nothing is selected). See Filtered CSV export.

Read the transcripts. Especially in the first month.

The dashboard isn't just for following up on leads. Reading what visitors actually ask SAL — and what SAL says back — is the fastest way to spot configuration gaps. Visitors asking about pricing? Add Pricing to your site awareness. SAL giving vague answers about delivery? Add a custom fact. The transcripts are signal, not just record.

Docs / Admin guide / Filtered CSV export

Filtered CSV export.

Export the exact slice of leads you need — for sales follow-up, CRM import elsewhere, weekly reporting, or backup. Filter first, then export only what matches.

Why filter before exporting.

Exporting all leads ever captured produces large files with lots of data you don't currently care about. A few common slice-then-export workflows:

  • "Leads from last week with successful HubSpot sync" — for a sales rep's Monday follow-up list.
  • "Leads from /pricing in the last 30 days" — for a marketing report on what's converting.
  • "Leads with failed Brevo dispatch" — to manually re-import after you fix whatever broke.
  • "All leads from 2025" — annual archive.

Running an export.

  1. Open SAL → Conversations.
  2. Apply filters at the top of the page — date range, lead status, dispatch status, source page, search. The list updates as you change them.
  3. Click "Export CSV" in the top-right corner of the page. (Optionally, tick the checkboxes for specific conversations first if you only want a subset of the filtered view.)
  4. The file downloads as sal-leads-YYYY-MM-DD.csv. Filename includes today's date.

What gets exported.

One row per conversation. Columns (in order):

  • captured_at — ISO timestamp with timezone, e.g. 2026-06-05T14:32:18+03:00.
  • name — full name as entered.
  • first_name, last_name — pre-split for tools that need them separate (most CRMs do).
  • email — visitor email.
  • phone — in E.164 format with the leading +. Important: see Excel-safe formatting below.
  • phone_country — 2-letter ISO code, e.g. KE, NG, UG.
  • company — company name (blank if not captured).
  • landed_on — the page the visitor first arrived at.
  • captured_on — the page where the lead form was submitted.
  • pages_viewed — semicolon-separated list of pages in viewing order.
  • conversation_summary — a one-sentence summary of what the visitor was asking about.
  • message_count — number of messages exchanged.
  • brevo_status, hubspot_status, webhook_status — per-integration dispatch outcomes: sent, failed, retrying, n/a.
  • referrer — incoming referrer URL if available.
  • handled — yes if marked-as-handled, otherwise no.

Excel-safe phone formatting.

Phone numbers in E.164 format start with +. Excel and Google Sheets interpret +254712345678 as a math expression, calculate it, and display it as 254712345678 — losing the leading +. This silent transformation has caused many "why aren't my SMS sends working?" tickets across the industry.

SAL prevents this by exporting phones in a quoted-formula format that Excel respects:

How phones appear in the exported CSV
# In the CSV, phones look like this:
name,email,phone,company
"Amina Otieno",amina@example.co.ke,="+254712345678","Acme Ltd"

# The leading =" tells Excel: this is a string, don't compute it.
# When Excel opens the CSV, the cell displays as +254712345678 correctly.
# When you re-export from Excel, the format is preserved.

If you're importing the CSV into a tool that doesn't understand the ="" wrapper (some older imports, some custom scripts), strip the wrapping characters first — the phone is the substring between the quotes.

Opening in Excel.

Best path: Data → From Text/CSV rather than double-clicking the file. The Data import wizard gives you per-column type control, which prevents Excel from "helpfully" reformatting dates and IDs.

  1. Open a new Excel workbook.
  2. Go to Data → From Text/CSV in the ribbon.
  3. Select your downloaded sal-leads-*.csv file.
  4. In the preview, set File origin to 65001: Unicode (UTF-8) so accented characters in names render correctly.
  5. Click Load.

The phone column will display as +254712345678 (no computation). Date columns retain their ISO format. Names with accents and non-Latin characters render properly.

Opening in Google Sheets.

  1. Open a new Google Sheet.
  2. File → Import → Upload, pick the CSV.
  3. In the dialog: Separator type: Comma, Convert text to numbers, dates, and formulas: No.
  4. Click Import data.

The "Convert text to numbers" setting is the key one — if you let Sheets convert, it'll do the same trim-the-plus behavior as Excel did before.

Opening in Numbers (Mac).

Numbers handles the SAL CSV out of the box without any conversion settings — double-click the file and it imports correctly, including the + on phone numbers. (Numbers is more conservative than Excel about type inference.)

Common workflows.

  • Monday morning follow-up list. Filter: last 7 days, with lead, not handled. Export. Hand to sales. They mark-as-handled in SAL after each call so the next Monday's list is clean.
  • Failed-dispatch recovery. Filter: has a failed dispatch. Export. Manually import into the destination CRM. Once done, the underlying issue is usually fixed (renewed key, etc.) — set the conversations as handled.
  • Annual archive. Filter: last year, all leads. Export. Save to your accounting/audit folder. Useful when tax season needs a contact-source breakdown.
  • Marketing performance. Filter: specific landing pages over a date range. Use the pages_viewed column to see typical journeys before lead capture.

Export limits.

A single export can contain up to 10,000 rows. If your filtered selection exceeds this, SAL paginates — you'll get the most recent 10,000 and a notice that older rows weren't included. Narrow the date range to get a complete export.

File size is typically 200 bytes per row, so 10,000 leads is roughly 2 MB — well under email attachment limits.

Docs / Admin guide / Dispatch audit log

Dispatch audit log.

Every integration dispatch SAL fires — successful, failed, retrying — is logged with full context. When a lead doesn't arrive where it should, this is where you find out why.

Where the log lives.

Two views, same underlying data:

  • Per-conversation. Open any conversation in the Conversations dashboard. Scroll to the dispatch panel on the right side. Each integration shows its current status with a badge; click the badge to see the full attempt history for that lead.
  • Global view. SAL → Conversations → Dispatch log (top-right link). Shows every attempt across all conversations, filterable. Best place to spot system-wide patterns ("HubSpot has been failing all afternoon").

What's logged.

Each attempt row contains:

  • Integration. Which connector — Brevo, HubSpot, Generic Webhook (with the webhook's name if you've given it one).
  • Conversation. Link back to the source conversation in the dashboard.
  • Attempt number. 1 of up to 3 (3 retries total per failure).
  • Started at. ISO timestamp with timezone.
  • Duration. How long the attempt took, in milliseconds. SAL times out at 10,000 ms.
  • HTTP status. The response code from the destination — 200 (OK), 401 (auth), 422 (validation), 500 (server error), etc.
  • Response body. Up to the first 2 KB of the response (truncated if longer). Most APIs return JSON with an error message — this is where you read it.
  • Error message. If the request didn't complete at all (connection refused, DNS failure, timeout), the underlying error.
  • Outcome. success, retrying, failed, or gave-up (after smart-retry classification said don't bother).

Reading the log.

The most useful patterns:

  • Single green row. First attempt succeeded. The destination has the lead.
  • Amber row → green row. First attempt failed, retry succeeded. Common with transient network issues. No action needed.
  • Red row, no retries. Smart retry classified the failure as non-retryable (usually 401/403/422) and gave up. Read the response body for the specific issue.
  • Three red rows. All three retries failed. The lead is permanently in failed state. Use Resend dispatch from the conversation detail view after fixing the underlying problem.

Smart retry classification.

SAL classifies failures into "worth retrying" and "won't help" buckets. The "won't help" failures get marked as gave-up immediately without scheduling retries.

  • Retryable: Connection timeouts, DNS failures, HTTP 408 (request timeout), 429 (rate limited), 500–599 (server errors). Backoff: 5min → 30min → 4hr.
  • Not retryable: HTTP 400 (bad request), 401 (unauthorized — wrong key), 403 (forbidden — insufficient scope), 404 (not found), 422 (validation error). These won't succeed on retry, so SAL gives up immediately and surfaces the error.

This stops the dispatch log from filling up with 12 identical attempts to a destination with the wrong API key.

Manual retry.

When a dispatch has permanently failed (or you've fixed an upstream issue), you can manually re-fire it:

  1. Open the conversation in SAL → Conversations.
  2. In the dispatch panel on the right, click the failed integration's badge.
  3. Click Resend dispatch.
  4. SAL re-runs the full dispatch through normal retry behavior (up to 3 fresh attempts).

For bulk manual retries across many conversations, use the Bulk → Resend dispatch action in the conversations list. Useful after fixing a key that broke for everyone.

Common patterns and what they mean.

  • HTTP 401 across all attempts. Your API key or token is wrong, missing scope, or revoked. Go to the integration's settings page and re-enter the key. Then bulk-retry the failed dispatches.
  • HTTP 429 with retry-after header. You're hitting the destination's rate limit. SAL respects the retry-after header automatically and waits that long before the next attempt. If it's a recurring issue, slow down by reducing your per-IP rate limit in settings to lower SAL's overall throughput.
  • HTTP 422 with property error. The destination rejected a specific field (most common with HubSpot — a property name doesn't exist, or a value violates a validation rule). Response body usually names the offending property. Fix the field in your destination's schema or exclude it from SAL's payload via integration settings.
  • Timeout after 10s. The destination took longer than 10 seconds to respond. SAL gives up and retries. If it's a custom webhook handler you control, optimize the handler to respond fast (acknowledge quickly, queue the heavy work) rather than synchronously processing inside the request.
  • Connection refused / DNS error. Either the destination is down, or the URL is wrong. Test the URL with curl from a terminal to confirm it's reachable, then check the integration's settings.

The log is also a security signal.

Repeated unexplained 401s on an integration that was working yesterday usually means someone rotated or revoked the credentials on the destination side. Worth investigating who and why — could be routine (annual rotation policy) or could be an indicator (compromised account being locked down).

Filtering the log.

The global dispatch log view supports the same filters as the conversations list, plus integration-specific ones:

  • Integration. Show only Brevo, only HubSpot, only Webhook(s).
  • Outcome. Success / retrying / failed / gave-up.
  • HTTP status. Specific code or range (e.g. "all 4xx", "all 5xx").
  • Date range. Last 24 hours (good for triage), last 7 days, last 30 days, custom.

Log retention.

Dispatch log entries are kept for the same retention period as the conversation they belong to (configurable in Settings → Targeting & limits). When a conversation is deleted, its dispatch log entries are deleted too.

For compliance archives, export the log periodically — SAL's dispatch log export is available from the global view as sal-dispatch-log-YYYY-MM-DD.csv.

Docs / Reference / Lead payload schema

Lead payload schema.

Every captured lead becomes a structured JSON payload — sent to your integrations, surfaced in the Conversations dashboard, and exported in your CSVs. This page documents every field: what it contains, when it's present, what format it takes, and how to handle edge cases.

The payload at a glance.

The payload is a single JSON object with five top-level keys. The Integrations overview page shows it in context; this page documents each field individually.

Payload top-level structure
{
  "lead_id":      // string — unique per lead
  "captured_at":  // ISO 8601 timestamp with timezone
  "contact":      { // who the visitor is },
  "context":      { // where they came from on your site },
  "conversation": { // what they discussed with SAL },
  "site":         { // which SAL site sent this }
}

Top-level fields.

  • lead_id — String. Always present. Format: lead_ followed by 8 hex characters (e.g. lead_a8f3c2b1). Unique across all leads on your site. Useful as an idempotency key on the receiving end — if your handler is hit twice with the same lead_id, you can safely treat the second one as a duplicate.
  • captured_at — String. Always present. ISO 8601 timestamp with timezone offset (e.g. 2026-06-05T14:32:18+03:00). The timezone reflects your WordPress site's configured timezone, not the visitor's. The "captured" moment is when the visitor submitted the lead form, not when the conversation started.

The contact object.

What the visitor told SAL about themselves. Field presence depends on what fields you've enabled in Settings → Leads.

  • name — String. Present if Name field is enabled (default). The full name as the visitor typed it. SAL doesn't validate format — you might receive "Amina Otieno", "Mr. John Doe", or just "Amina".
  • email — String. Present if Email field is enabled (default). Validated against basic email format on submission. Lowercased before storage.
  • phone — String. Present if Phone field is enabled (default). Always in E.164 format with the leading + (e.g. +254712345678). The country picker produces this format natively, so you never receive a malformed phone.
  • phone_country — String. Present if Phone field is enabled. ISO 3166-1 alpha-2 country code (KE, NG, UG, etc.) — the country the visitor selected in the country picker. Useful for regional routing or formatting.
  • company — String. Present only if Company field is enabled (off by default). Company name as the visitor typed it. May be empty string if visitor skipped an optional field.

The context object.

Where the visitor came from and what they were looking at. Always present; individual fields may be null if the data wasn't available.

  • landed_on — String. The path of the first page the visitor viewed in this session (e.g. "/", "/pricing"). Always relative to your site root; never includes the domain.
  • captured_on — String. The path of the page where the visitor submitted the lead form. May or may not match landed_on depending on the visitor's journey.
  • pages_viewed — Array of strings. Ordered list of every page the visitor viewed before submitting the lead. Includes the landed-on page first and the captured-on page last. Same site-relative path format. Useful for understanding visitor journeys — repeated pages indicate hesitation or comparison shopping.
  • referrer — String or null. The HTTP referrer of the first page view in this session (e.g. "https://google.com/", "https://facebook.com/"). Null when the visitor arrived via direct URL, bookmark, or with a referrer-stripping browser configuration.
  • user_agent — String. The browser's User-Agent string. Useful for device-class analytics; don't use as a unique identifier.

The conversation object.

What was said between the visitor and SAL.

  • message_count — Integer. Total number of messages exchanged in the conversation up to the point of lead capture (visitor messages + SAL responses combined). Minimum of 2 in practice (one visitor question, one SAL response that triggered the capture).
  • summary — String. A one-sentence AI-generated summary of what the conversation was about. Generated at the moment of capture using the same provider you've configured. Useful for prioritizing follow-ups — your sales team can see "Visitor asked about enterprise pricing for 20+ seats" before opening the full transcript.
  • transcript_url — String. A direct link to the full conversation in your WordPress admin. Requires admin login on your site. Format: https://yoursite.com/wp-admin/admin.php?page=sal-conversations&id=....

The site object.

Which SAL deployment produced this lead. Useful when multiple WordPress sites under the same license are sending leads into the same destination.

  • name — String. The Site Name from WordPress settings (Settings → General → Site Title).
  • url — String. Your WordPress site's full URL with protocol (e.g. "https://yoursite.com"). Use this to route or filter leads when one webhook endpoint receives leads from multiple sites.

Formatting rules.

  • All strings are UTF-8. Visitor names in any script (Latin, Cyrillic, Arabic, CJK) come through intact. Make sure your destination accepts UTF-8 — most modern systems do.
  • Phone numbers are always E.164 with leading +. No spaces, no dashes, no parentheses. +254712345678, never +254 712 345 678 or (254) 712-345-678.
  • Timestamps are ISO 8601 with timezone. Always include the offset (+03:00 for EAT, +00:00 or Z for UTC). Parse using your language's standard ISO 8601 parser; never string-manipulate the date.
  • Paths in landed_on / captured_on / pages_viewed are site-relative. Always start with /; never include the domain. The query string is included if present; the fragment (#anchor) is stripped.

Always-present vs optional fields.

Top-level fields (lead_id, captured_at, contact, context, conversation, site) are always present. Within the nested objects, some fields are conditional:

  • contact.* fields are present based on which lead-capture fields you've enabled in Settings.
  • context.referrer can be null (browser didn't send a referrer).
  • If your destination is strict about schema validation, treat optional fields as nullable and validate against the documented format only when the field is non-null.

Per-integration mapping.

Different integrations consume the same payload differently:

  • Brevo maps to: NAME (from contact.name first word), SURNAME (rest), EMAIL, SMS (from contact.phone), COMPANY. See Brevo for details.
  • HubSpot maps to: firstname, lastname, email, phone, company, plus the site URL into the website property. See HubSpot.
  • Generic Webhook receives the entire payload as the request body, untransformed. Map it however you want on the receiving end. See Generic Webhook.
Docs / Reference / Security & privacy

Security & privacy.

SAL is built on the principle that your conversations and your visitors' data belong to you, not to us. This page covers what's encrypted, what's signed, where data actually lives, and what Smith Aegis never sees.

What Smith Aegis doesn't see.

SAL's architecture intentionally minimizes what we know about your operations. Specifically:

  • Conversation contents. When a visitor chats with SAL on your site, the chat traffic goes directly from your visitor's browser, to your WordPress site, to your chosen AI provider, and back. Smith Aegis servers are not in that path. We don't have, and can't read, what your visitors are asking or what SAL is answering.
  • Your AI provider keys. Your API keys for Anthropic, OpenAI, or Google are stored encrypted in your own WordPress database. They never leave your site. We don't have a copy.
  • Your CRM credentials. Brevo API keys, HubSpot access tokens, webhook secrets — all encrypted in your WordPress database, never transmitted to Smith Aegis.
  • Your captured leads. Lead data flows from your WordPress site directly to your CRM integrations. Smith Aegis isn't a hop on that route.
  • Your visitor IPs or identifying info beyond what you collect. SAL only stores what visitors explicitly type (name, email, phone — fields you configured). It doesn't fingerprint, doesn't track across sites, doesn't sell data, doesn't have data to sell.

What Smith Aegis does see.

We see account and licensing data. Specifically: your account email (the one you use at app.smithaegis.co.ke), the WordPress site URLs you've registered under your license, your subscription state (trial, active, expired), and your billing history if you've signed up for a paid plan. That's the data needed to operate the business relationship — nothing more.

Where your data lives.

Four places, each with its own security boundary:

  • Your WordPress database. Conversations, lead records, dispatch log entries, encrypted credentials. Your hosting environment's security applies — backups, access control, SSL all your responsibility (and within your control).
  • Your chosen AI provider's servers. When SAL sends a question + page context to Anthropic, OpenAI, or Google, that provider processes the request per its own policies. Review your AI provider's privacy and data-retention policy for what they retain.
  • Your CRM's servers. When a lead syncs to Brevo, HubSpot, or your webhook destination, the data follows your CRM's policies after that point.
  • Smith Aegis's licensing servers. Account info, subscription state, license activation records. Located at app.smithaegis.co.ke, hosted on Supabase, encrypted at rest by the platform.

How credentials are protected.

Every credential SAL stores — AI provider API keys, CRM tokens, webhook signing secrets, license keys — is encrypted at rest before being written to your WordPress database. The encryption uses a per-site secret derived from your WordPress installation; if someone exports your database to take it elsewhere, the credentials stay unreadable without the original site's encryption context.

This protects against the most common database exposure scenarios: a backup file shared with the wrong person, a development copy used in production, a stolen export. It doesn't protect against an attacker with full server access to your live WordPress site — at that point, they have everything the running site has access to. Standard WordPress security hygiene (strong admin passwords, updated WordPress core, secure hosting) is still your responsibility.

Webhook signing.

Every webhook SAL sends — to your generic webhook destination, to Brevo, to HubSpot — is cryptographically signed using a secret you control. The signature lets your receiving handler verify that the request actually came from your SAL site and wasn't sent by someone else who happened to discover your URL.

For generic webhooks, the signature is in the X-SAL-Signature header. For the technical details on how to verify it on your end, see the Generic Webhook page — there's a working Node.js example with a warning about the most common verification mistake.

Data retention.

Conversations are kept in your WordPress database for the retention period you configure in Settings. After that period elapses, they're automatically deleted along with their lead records and dispatch log entries.

You can delete any conversation manually at any time from the Conversations dashboard. Deletion is permanent — both the conversation and its lead-payload sent to integrations are removed. (Note: this only removes the data from your WordPress site; data already sent to Brevo, HubSpot, or your webhook is governed by those services' deletion policies, not SAL's.)

Handling visitor data requests.

Under GDPR, CCPA, and equivalent regulations, visitors can request access to or deletion of their data. SAL is designed to make this straightforward:

  • Access requests: Search the Conversations dashboard by email or phone, export the matching conversations as CSV, send to the visitor.
  • Deletion requests: Same dashboard, locate the conversation(s), delete. Also contact your downstream CRMs to remove the contact there (those are separate systems with their own deletion paths).

You are the data controller for your visitors' data. Smith Aegis is not a sub-processor for that data — your AI provider and your CRM are.

Reporting a vulnerability.

Found a security issue? Email support@smithaegis.co.ke. We respond within 48 hours and work with reporters in good faith. Critical issues are patched within 7 days; lower-severity issues are scheduled into the next release. We credit reporters in the changelog unless you'd rather stay anonymous.

Docs / Reference / Troubleshooting

Troubleshooting.

Most issues fall into a few well-known categories. This page walks through the most common ones — from "the chat isn't showing up" to "leads aren't reaching my CRM" — and what usually fixes them.

The chat launcher isn't appearing.

The most common first-day issue. Check in this order:

  • Plugin activated? WordPress admin → Plugins → confirm SAL® - AI Chat is active (not just installed).
  • License activated? Settings → SAL → License tab → should show status as Trial or Active. If it shows Unconfigured or Expired, the launcher doesn't render.
  • Cache. If you use Cloudflare, WP Rocket, W3 Total Cache, LiteSpeed, or your host has its own caching layer (Kinsta, WP Engine, SiteGround), the launcher script may not be in the cached version yet. Clear all cache layers and hard-refresh (Cmd+Shift+R / Ctrl+Shift+R).
  • Page targeting. Settings → SAL → Targeting & limits → check the "Show on these pages" and "Exclude on these pages" settings. Defaults to show everywhere, but if you've narrowed it, the page you're testing on may be excluded.
  • Maintenance mode plugins. A "Coming soon" or maintenance-mode plugin can block third-party scripts including SAL. Temporarily deactivate to test.
  • JavaScript console errors. Open browser DevTools → Console. If you see red errors mentioning sal, copy them and email support.

The chat opens but doesn't respond.

The launcher renders, the chat panel opens, but nothing comes back when you type. Usually an AI key issue:

  • Test connection. Settings → SAL → Connection → click Send test ping next to your provider's key field. If it fails, the key is wrong, expired, or the account has zero credits.
  • Re-paste the key. Most "key not working" issues turn out to be invisible whitespace from a copy-paste. Re-copy from your provider's dashboard and re-paste fresh.
  • Provider credit balance. Anthropic, OpenAI, and Google all require pre-paid credit or active billing. Check your account on the provider's side — if balance is zero, top up.
  • Hosting environment blocking outbound requests. Some locked-down corporate hosts block outbound HTTPS. Ask hosting to allowlist api.anthropic.com (Anthropic), api.openai.com (OpenAI), or generativelanguage.googleapis.com (Google).
  • Rate limiting on your side. Settings → SAL → Targeting & limits → check "Per-IP rate limit" and "Daily site cap". If you've set them aggressively low, real visitors might be getting blocked. The defaults are generous for most sites.

The AI is giving wrong or vague answers about your business.

SAL is only as smart as the information you give it. Check:

  • Page content is HTML-rendered. SAL reads the HTML of the page. Some page builders (certain Elementor templates, custom Gutenberg blocks) render content via JavaScript after page load. View the page source — if your actual copy isn't there, SAL can't see it. Solution: switch to a static-render configuration in your page builder.
  • Site context is configured. Settings → SAL → Site context → confirm "Always include these pages" lists your key pages (Pricing, About, FAQ, Contact). The default is generous but if you've narrowed it, SAL may be missing key context.
  • Custom facts are populated. If you offer something not on any page (delivery zones, certifications, founder bio details), add them as custom facts. Each fact gets injected into every conversation.
  • System prompt isn't overriding everything. Settings → SAL → Behavior → System prompt → check whether your customization is conflicting with site context. A system prompt that says "only discuss pricing" will make SAL ignore other context.
  • Try a different model. If you're on the cheapest tier of your provider (Haiku, GPT Mini, Gemini Flash), some questions may exceed what the model can reason through. Switch to the mid-tier (Sonnet, GPT 5.4, Gemini Pro) and test the same question.

Leads aren't reaching your CRM.

SAL captures the lead but it never lands in Brevo/HubSpot/your webhook. Check:

  • The dispatch log. Settings → SAL → Conversations → open the relevant conversation → look at the dispatch panel. Red badge = failed. Click for details.
  • HTTP 401 / "Invalid credentials". API key expired, revoked, or wrong. Re-generate in your CRM's dashboard, paste fresh into SAL.
  • HTTP 422 / "Validation error". Your destination rejected the payload — usually a property name doesn't exist or a value violates a validation rule. Response body in the dispatch log names the problem. Fix it on the destination side or exclude the field in SAL.
  • HTTP 429 / "Rate limited". You've hit your CRM's request rate limit. SAL retries automatically. If it's recurring, slow your inbound by lowering "Per-IP rate limit" in SAL settings.
  • Connection timeout. Your destination took longer than 10 seconds. If it's your own webhook, optimize the handler — respond fast and queue the heavy work.
  • "Mark as handled" but no follow-up. Make sure your sales team isn't marking the conversation as handled before the dispatch has actually fired (rare race condition; doesn't lose data, just confuses tracking).

WhatsApp handoff isn't working.

  • WhatsApp number format. Settings → SAL → WhatsApp → number must be in E.164 format, no spaces, no dashes, no leading +. Kenya example: 254765941351. Don't include the +.
  • "Show button" toggle. Same settings page, confirm the toggle is on.
  • Auto-offer setting. If auto-offer is on but never triggers, your system prompt may not be hedging in a detectable way. Try a question SAL genuinely can't answer (e.g. "What's your refund policy?" on a site without that info) and see if the offer fires.
  • The number on WhatsApp. SAL just constructs a wa.me/<number> link. If the visitor's WhatsApp opens and shows "this number is not on WhatsApp", the number isn't registered with WhatsApp Business. Register it at business.whatsapp.com.

Your license shows as invalid.

  • License key + secret entered correctly. Settings → SAL → License → re-paste both fields from your dashboard at app.smithaegis.co.ke. Watch for invisible whitespace.
  • Site URL matches. The site URL registered in your dashboard must match your WordPress site's URL (Settings → General → WordPress Address). If you migrated from http:// to https://, or changed domain, update the registered URL in the dashboard.
  • Trial expired. Trials run 30 days from signup. After expiry, upgrade in the dashboard to a paid plan.
  • Subscription expired or payment failed. Check your dashboard's Billing section. Update payment method, re-attempt the charge, the license auto-reactivates within ~5 minutes after payment succeeds.
  • Site was deactivated in dashboard. If you (or a team member) deactivated this site from the customer dashboard, the plugin notices within ~5 minutes and stops the chat. Reactivate from the dashboard's Sites section.

Still stuck.

Two paths:

  • Search the docs. Use the search bar at the top of this page (⌘K / Ctrl+K). Most specific issues are documented under their feature page.
  • Contact support. chat.smithaegis.co.ke/support for email + WhatsApp + live chat. Include your site URL, your license key (first 4 + last 4 characters only), and a screenshot of the issue. We typically respond within a few hours during East African business hours, longer on weekends.
Docs / Reference / Changelog

Changelog.

A public timeline of what's shipped in SAL — features, major fixes, and what's next. Released as a customer-facing summary; not a technical-detail document.

2.3.x — Commercial licensing.

SAL moved from "free plugin you install" to "commercial product with a 30-day trial." Built the licensing layer, the customer dashboard, and the per-site activation model.

  • Customer dashboard live at app.smithaegis.co.ke. Sign up, see your sites, manage your subscription, pay invoices, access support.
  • 30-day free trial. No credit card required. Trial auto-issued on signup; converts to paid on first successful payment.
  • One license, many sites. Your subscription covers every WordPress site you run — yours, your clients', your side projects. Add and remove sites from the dashboard.
  • Per-site activation/deactivation. Deactivate any site from the dashboard and the chat stops there within minutes. Reactivate when you want it back. Useful for staging environments, sites you've handed off, or seasonal businesses.
  • License health visible in WordPress. SAL → License tab shows your license status, trial countdown, registered sites, and dashboard link.

2.2.x — Multi-provider AI.

SAL became provider-agnostic. Pick any of three AI engines, switch any time, pay the provider directly.

  • Anthropic (Claude) integration — original provider, default. Models: Claude Haiku 4.5, Claude Sonnet 4.6, Claude Opus 4.8.
  • OpenAI (GPT) integration added. Models: GPT 5.4 Mini, GPT 5.4, GPT 5.5.
  • Google (Gemini) integration added. Models: Gemini 2.5 Flash, Gemini 2.5 Pro, Gemini 3.1 Pro.
  • Per-provider quota detection. When your AI provider returns a rate-limit or credit-exhausted error, SAL surfaces the exact reason in the dispatch log so you know whether to top up, switch tier, or switch provider.
  • Per-provider Test Connection. Verify each provider independently before relying on it in production.

2.1.x — Integrations and dispatch infrastructure.

The CRM and webhook layer.

  • Brevo integration. Direct contacts API integration. Lead attribute mapping (NAME/SURNAME/EMAIL/SMS/COMPANY), list selection, E.164 phone handling, fallback when Brevo rejects the phone.
  • HubSpot integration. Uses HubSpot's Private App tokens (the modern auth method). Property mapping (firstname, lastname, email, phone, company, lifecyclestage). Required scopes documented in the HubSpot setup page.
  • Generic Webhook integration. Universal escape hatch — POST every lead as JSON to any URL. Cryptographically signed for verification. Works with Zapier, Make, n8n, Slack, custom backends.
  • Smart retry classification. Failed dispatches retry intelligently — transient failures (timeouts, 5xx, 429) retry with backoff; permanent failures (401, 422) give up immediately so the log isn't cluttered with hopeless attempts.
  • Dispatch audit log. Every dispatch attempt logged with HTTP status, response body, timestamp, duration. Surfaceable per-conversation or as a global view.
  • Filtered CSV export. Filter by date, lead status, source page, dispatch status, then export the exact slice. Excel-safe phone format included by default.

2.0.x — Foundation release.

The core SAL experience.

  • Lead capture with country-picker phone field. Every country in the world, E.164 output, no malformed phone numbers reaching your CRM.
  • Conversations dashboard. Read transcripts, follow up on leads, filter by status, mark as handled.
  • WhatsApp handoff. SAL detects when a conversation needs a human and quietly offers WhatsApp with the conversation summary pre-filled.
  • AI-grounded chat. Reads your actual pages, your menu, custom facts you write. Doesn't make things up.
  • Streaming responses. Words appear as they're written, ChatGPT-style. Doesn't make visitors wait on a spinner.

What's coming.

Forward-looking; not a commitment. Roughly the order we're working in:

  • Custom CRM property mapping. Today, SAL maps to the standard contact properties on Brevo and HubSpot. Custom properties (e.g. "lead source detail," "estimated deal size") will be mappable from the SAL admin in a future release.
  • More CRM integrations. Salesforce, Zoho, Pipedrive in order of customer demand. Tell support which one you'd want first — that input genuinely affects priorities.
  • Conversational analytics. Topic clustering ("what are visitors actually asking about most"), drop-off analysis, conversion attribution. Currently the dashboard shows individual conversations; we want aggregate insight.
  • Multi-language support. SAL's UI is currently English. Full localization (Swahili, French, Arabic, Spanish, Portuguese first) is on the roadmap.
  • Voice input. Visitors typing on mobile is friction. Voice-to-text is a 2027 candidate; we want to do it right rather than first.

For the full historical changelog with every patch release, log in to your account at app.smithaegis.co.ke and check the Release notes section.

Stuck on something? We're here.

These docs cover the common ground. If you hit a wall, run into a vendor-side quirk, or just want a second pair of eyes on your setup — get in touch.

Last updated June 5, 2026 Document version v1.0 Plugin version