KAIA marketing

KAIA's marketing mode drafts; a person decides; consent decides whether anything can go out at all.

Proposals, not sends

Marketing mode is a second set of tools on the same KAIA. It is switched on per tenant under Engagement › KAIA Marketing › Settings (the page lives at /admin/engagement/marketing-ai; KAIA itself has to be on for the tenant first, and everything on the page needs the manage-marketing-ai permission). Once on, it is reached two ways: an admin switches KAIA's chat on its own page into marketing mode, or an external agent connects to the marketing MCP endpoint described below.

Whichever way it is reached, the mode has exactly three tools, and none of them has a side effect on a guest. Each one computes something over the tenant's own guest data, stores a proposal row, and returns the proposal's id together with a handful of masked sample usernames — never the full list, which only the tenant's administrators can see inside Kiwire. The three are:

• Suggest a campaign — drafts a display campaign for a segment.
• Tag a segment — proposes applying a tag (a row in Kiwire's own segment store) to the guests a rule matches. The rules are fixed: vip, dwelled_long, multiple_visits, birthday_this_month, lapsed, repeat_visitors, or tag:<name> for a tag applied earlier.
• Propose an engagement — proposes sending a message to a segment by email, SMS or WhatsApp, through one of the tenant's existing connectors, using a Message Template or an inline subject and body.

A proposal moves through a small state machine: pending → approved, rejected or expired; approved → executed, failed or expired. A pending proposal expires after 7 days; an approved send whose window has been over for a day expires too. Every transition is written to the marketing audit trail with who made it.

Each proposal carries a risk level, set by fixed rules rather than the model's judgement: tagging is low, a campaign draft is low, an email send is low, an SMS or WhatsApp send is medium, an SMS or WhatsApp send to more than 1,000 guests is always high, and any send whose estimated cost is above the tenant's per-proposal spend cap (default 50.00 in the tenant's currency, set on the settings page along with the per-message cost used for the estimate) is high whatever its size.

Risk decides who may run an approved proposal. Approve and Reject are one click on the proposals page. A low-risk proposal that has been approved is picked up by the kaia:marketing-execute job, which runs every minute for each tenant with marketing mode on. A medium- or high-risk proposal needs a second, separate Execute click from an administrator after its approval; the cron never touches it.

The one place a person can be left out entirely is tagging: if the tenant has switched on auto-execute low-risk actions and the tool call asked for it, a low-risk tagging proposal is approved by the cron and applied the next minute. Sends and campaign drafts are never auto-approved, whatever the settings say.

Executing a proposal means something different for each tool. A tag becomes rows in the tenant's marketing-tag table. A campaign becomes an inactive display campaign, named after the proposal, which an admin activates under Engagement › Campaigns once the creative is ready — nothing is ever shown to a guest from here. A send becomes a queued job delayed to the start of its send window, and that job checks consent again, guest by guest, at the moment it sends.

The consent gate

The only way a marketing message reaches a guest is through a consent record. The gate reads the tenant's kiwire_consent_records table and calls a guest reachable on a channel when they hold a record for the purpose marketing_<channel> (email, sms or whatsapp) that is granted, not withdrawn, and not expired, matched by their login username or their email address. Nothing else counts: a guest who gave an email for a one-time-password login has not consented to marketing, and the gate does not infer that they have.

The gate fails closed. On a tenant where the consent module has not been installed — where the table does not exist — every guest reads as blocked on every channel, with a reason that says so, and no send is possible. On this install the consent tables exist on a small number of tenant databases; on every other tenant marketing mode can compute segments, draft campaigns and tag guests, but a send proposal will report every guest as blocked. The tool says this plainly rather than working around it, and when nobody in a segment is reachable it files no proposal at all, because a proposal that would send to no one is noise on the approval page rather than a decision.

The check runs twice: once when the proposal is filed, so the reachable and blocked counts and the cost estimate on the approval page are real, and again inside the send job for each guest, so a withdrawal between approval and the send window is honoured. A guest without a granted record is skipped and counted, never sent.

What it will never do

No marketing tool takes a tenant parameter; the tenant is the one the request was authenticated for, and there is no way to name another. No tool sends, tags or shows anything by being called — every one of them files a proposal. No send goes to a guest without a consent record, and the module's absence blocks everything rather than allowing it. No SMS or WhatsApp send is proposed to more than 1,000 guests; the model is told to split the segment or choose email. No campaign is ever created active. No send and no campaign draft is ever approved without a person. Guest identifiers in tool results are masked the same way as everywhere else in Kiwire's AI, and the full audience is visible only to the tenant's own administrators on the proposal page. And, as with all of KAIA, nothing here deletes anything.

Reaching it from outside

The marketing tools have their own MCP endpoint, /mcp/kaia-marketing, separate from /mcp/kaia so that a client which only wants diagnostics never sees a tool that files marketing proposals. It uses the same authentication and the same switches as the KAIA server — the tenant's API key with MCP scope, the platform's MCP allowance for the tenant, the tenant's KAIA server switch, and KAIA switched on for the tenant — and each marketing tool additionally checks the tenant's marketing switch on every call. The endpoint also carries the read-only KAIA tools (tenant overview, schema description, guarded SQL) so a client can look before it proposes. A proposal filed over MCP lands on the same Engagement › KAIA Marketing page and waits for the same approval; an external client cannot approve, reject or execute anything. Connecting a client is described in MCP and external agents.