Skip to main content

Sales Agent

The Sales Agent turns your chatbot into a lead-capture assistant. It detects when a conversation has sales intent, collects configurable lead fields from the user, and delivers captured leads through one or more delivery channels (email or webhook).

Overview​

The Sales Agent has two independent controls:

  • Configuration — the prompt overlay, lead fields to collect, model override, guardrails, and trigger sensitivity. Configured via the dashboard or the Management API.
  • Enablement — whether the agent is live at runtime (salesAgentEnabled). Configuring the agent does not automatically enable it; enablement is a separate control.

Configuring the Sales Agent​

Via the dashboard​

Open the chatbot dashboard, then go to Agents → Sales Agent.

The Sales Agent detail view contains Overview, Configure, Hand-offs, Leads, and Analytics sections. Use the Enable/Pause control in the Sales Agent header to change the runtime salesAgentEnabled state.

Via the Management API​

Get current configuration

GET /api/v1/chatbots/{chatbotId}/sales-agent

Required scope: chatbots:read

Returns the public Sales Agent configuration plus salesAgentEnabled — whether the agent is live at runtime. When no Sales Agent configuration document exists yet, the response contains only the runtime enablement flag.

Update configuration

PATCH /api/v1/chatbots/{chatbotId}/sales-agent

Required scope: chatbots:write

Creates the Sales Agent document on first update (the response includes created: true when that happens). Only the fields you send are applied; omitted fields are unchanged.

Common writable configuration fields include:

FieldTypeDescription
enabledbooleanEnable or disable this Sales Agent configuration. This is not the runtime live/paused switch; runtime enablement is salesAgentEnabled.
promptOverlaystringCustom prompt text that overlays the base agent persona.
promptSlotsobjectStructured prompt fields such as persona, value propositions, qualifying questions, and forbidden topics.
promptEditorModestringPrompt editor mode: free-form or structured.
modelOverridestring | nullOverride the model in model@provider form, or null to clear.
componentModelsobject | nullPer-component model overrides.
fieldsToCapturearrayLead fields the agent should collect from the user.
guardrailEnabledbooleanEnable the built-in sales guardrail rules.
guardrailRulesarrayBuilt-in guardrail rule IDs.
guardrailCustomRulesarrayCustom guardrail rules.
triggerCategoriesarraySales-intent categories that can trigger the agent.
triggerCustomRulesarrayCustom trigger rules.
triggerExclusionsarraySituations that should not trigger the Sales Agent.
triggerSensitivitystringHow aggressively the agent triggers on sales intent.
scopeOverridesobjectPer-knowledge-scope overrides for supported prompt, capture, guardrail, and trigger fields.
evalEnabledbooleanEnable Sales Agent quality-evaluation calls.

Use PATCH /api/v1/chatbots/{chatbotId}/apply to update chatbot-level runtime configuration such as salesAgentEnabled through the config-as-code surface.

Lead Delivery Channels (Handoffs)​

Captured leads are delivered through handoff channels. Each channel sends lead data to a configured recipient via email (smtp or resend) or webhook.

Creating channels requires the dashboard

A channel can only be created from the dashboard — creating one is inseparable from storing its sending secret (email credentials or webhook HMAC). Once a channel exists, its routing and recipient settings can be managed via the API.

Listing channels​

GET /api/v1/chatbots/{chatbotId}/sales-agent/handoffs

Required scope: chatbots:read

Returns all handoff channels. Each channel includes:

  • channel — delivery type: smtp, resend, or webhook
  • routingMode — how recipients are selected: single, distribution, country, or scope
  • hasSecret / hasWebhookHmac — whether a sending secret is configured (the secret itself is never returned)
  • enabled — whether the channel is active

Updating a channel​

PATCH /api/v1/chatbots/{chatbotId}/sales-agent/handoffs/{handoffId}

Required scope: chatbots:write

Writable fields:

FieldTypeDescription
enabledbooleanActivate or deactivate the channel. Enabling requires a secret to already be configured.
routingModestringsingle | distribution | country | scope
routingConfigobjectRouting-mode-specific recipient configuration.
verifiedSenderstringVerified sender email address (email channels).
webhookUrlstringWebhook endpoint URL (webhook channels).
fieldsToIncludearrayWhich captured lead fields to include in the delivery payload.
templateVersionIdstringEmail template version to use.

Deleting a channel​

DELETE /api/v1/chatbots/{chatbotId}/sales-agent/handoffs/{handoffId}

Required scope: chatbots:write

Idempotent — deleting an unknown channel ID still returns success.

Viewing Captured Leads​

GET /api/v1/chatbots/{chatbotId}/sales-agent/leads

Required scope: analytics:read (owner/admin only)

Returns captured lead metadata — disposition, handoff status, country code, timestamps, and aggregates — without exposing PII. See the API reference for the full response schema.

Viewing a Single Lead (with PII)​

GET /api/v1/chatbots/{chatbotId}/sales-agent/leads/{leadId}

Required scope: security:read (owner/admin only)

Returns the same metadata as the list plus the decrypted contact PII (name, email, phone, company, any custom fields) and coarse geo detail (region, city, timezone). This path is audit-logged. A decryptError field is present if server-side decryption failed; the raw encrypted envelope and HMAC hashes are never returned.

Returns 404 for a missing, soft-deleted, or unauthorized lead (IDOR-safe).

Exporting Leads as CSV​

GET /api/v1/chatbots/{chatbotId}/sales-agent/leads/export

Required scope: security:read (owner/admin only)

Returns a CSV with decrypted contact fields (name, email, phone, company) and coarse geo columns. Each row includes a pii_decrypt_status column (ok / failed / erased / none). Cells are hardened against CSV injection. The export is capped at 5,000 rows — narrow the time window or filters if you receive a 413 response.

GDPR DSAR Lead Erasure​

POST /api/v1/chatbots/{chatbotId}/sales-agent/leads/{leadId}/dsar-erase

Required scope: security:write (owner/admin only)

Hard-erases a single lead's PII: scrubs the encrypted contact fields, HMAC hashes, and PII-adjacent geo (IP, region, city, timezone) while retaining the anonymous row (disposition, capturedAt, country code) so aggregate metrics remain intact. Idempotent — repeating the request on an already-erased lead returns 409 and preserves the original piiErasedAt timestamp (GDPR Article 17 audit-trail integrity).