Lead Capture

What a lead is

A lead is a contact record that Alpheris creates from a chat when a visitor leaves their contact details — for example to request a quote, a consultation, or a callback. Each lead ends up as its own record and is additionally linked to the conversation it originated from.

A lead always stores the same fields:

In addition, Alpheris stores metadata about the conversation: among other things a lead probability (score) with a rating, a short summary of the request, the page where the lead originated, and — if collected — the company. More on this below under "Lead score".

When a lead is captured

Alpheris does not automatically create a lead for every casual question. A record is only created when there is a clear, confirmed intent to make contact — typically via a contact form submitted in the chat. This avoids dead records from pure support or pricing questions.

The trigger: the lead form in the chat

When the AI detects genuine buying or consultation interest (e.g. "Can you send me a quote?", "I'd like a consultation"), it offers to take down the contact details and displays a compact contact form right inside the chat window. The visitor enters their details and submits — only then is the lead saved.

Leads created manually or via API

Leads don't have to come from the chat. Your team can create a lead by hand in the Inbox, and leads can be generated programmatically via the API (see "Leads via API"). Manually created leads carry the source lead_form_manual.

Lead score

For every lead, Alpheris calculates a lead probability and a score from 0–100 derived from it. The scoring is heuristic and draws on signals from the conversation history:

• Quote or sales interest: explicit requests for a quote or a consultation raise the score significantly.
• Budget or timeline: signals about budget, rollout date, or go-live raise the score.
• Completeness of contact details: email, phone, and company each count toward the score.
• Dampeners: pure support requests and complaint signals (e.g. a complaint or a return) lower the score.

From the score, Alpheris derives a rating: high (≥ 75), medium (≥ 45), and low. A lead submitted via the chat form counts as a confirmed contact and is recorded with the maximum score (100, rating "high").

Leads in the dashboard

All leads come together in the Inbox. There you'll find a dedicated Leads view, newest first, with name, email, phone, source, status, score, and the associated conversation.

For each lead you can:

• Open / follow up: via the link to the conversation you can see the full chat history.
• Close: mark as done (status closed).
• Reopen: reactivate a closed lead.
• Delete: remove the record.

You can reach the Inbox via the Dashboard.

Email notification for new leads

Optionally, Alpheris sends you an internal notification email ("New lead received") for every new lead, with the key details — name, email, phone, source, page, and conversation reference. This notification must be enabled in the business/notification settings and requires a valid recipient address.

Exporting leads

Alpheris doesn't lock leads away in a silo — you can access them via the API and move them into your CRM.

Programmatically via API

Via the API you can retrieve or create leads. These endpoints are available on the Business and Enterprise plans (other plans receive 402 plan required).

Authentication uses your API key as a Bearer token (or the X-API-Key header). You manage keys in the dashboard:

curl https://console.alpheris.com/api/inbox/leads?limit=50 \
  -H "Authorization: Bearer YOUR_API_KEY"

The response contains the list of leads, including score and rating:

{
  "ok": true,
  "leads": [
    {
      "id": 1042,
      "source": "lead_form",
      "name": "John Example",
      "email": "[email protected]",
      "phone": "+44 7700 900123",
      "message": "Please send us a quote for 50 licenses.",
      "status": "new",
      "conversation_id": "conv_abc123",
      "lead_score": 100,
      "lead_probability": 1.0,
      "created_at": "2026-06-18T09:41:00Z"
    }
  ]
}

You create a lead from outside via POST. At least one of name, email, or phone is required; a provided email is checked for valid format:

curl -X POST https://console.alpheris.com/api/inbox/leads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Example",
    "email": "[email protected]",
    "phone": "+44 7700 900456",
    "message": "Please call me back"
  }'

Zendesk handoff

If you've connected Zendesk, a lead can be pushed to your Zendesk with a click or via the API. The Zendesk integration is reserved for the Business and Enterprise plans.

Form webhook — to your own API

Every request form (action Form or Ticket) can additionally send its data to a URL of your own — e.g. to your CRM, to Zapier/Make, or to a custom endpoint. You enable this in the menu builder: Menu item → Action "Form" → Advanced → "Send form data to this API", then enter the URL and (optionally) a secret.

For every new lead, Alpheris sends a POST to your URL server-side. The lead is always saved first — the webhook is purely additive; an outage of your API never loses a lead.

Payload

{
  "event": "lead.created",
  "lead_id": 12345,
  "shop_id": 42,
  "source": "lead_form",
  "name": "Jane Example",
  "email": "[email protected]",
  "phone": "+44 7700 900456",
  "company": "",
  "message": "Please call me back",
  "fields": { "preferred_time": "Monday morning" },
  "conversation_id": "email_thread_ab12…",
  "timestamp": 1760000000
}

fields contains your own form fields; the standard fields name / email / phone / message are additionally available directly in the payload.

Verify the signature

If you store a secret, Alpheris signs every call with HMAC-SHA256. Always verify the signature against the raw request body (not against re-serialized JSON):

import hmac, hashlib

def verify(raw_body: bytes, secret: str, ts: str, sig_header: str) -> bool:
    # ts        = Header X-Alpheris-Timestamp
    # sig_header = Header X-Alpheris-Signature  ("sha256=<hex>")
    expected = "sha256=" + hmac.new(
        secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, sig_header)

The headers X-Alpheris-Signature: sha256=<hex> and X-Alpheris-Timestamp: <unix> are sent. Reject the call if the signature doesn't match or the timestamp is too old.

What's not (yet) available

So you don't build on false expectations:

• No direct CSV download for leads in the dashboard — export runs via the API.
• No native Zapier connector — use the form webhook (above), the API, or the Zendesk handoff instead. Incoming platform webhooks (Stripe, Shopify) are covered under Webhooks.
• No freely definable additional fields in the lead record beyond those listed above.