AI widgets (headless protocol)

Partners can ship modules that return presentation Cards for Airlead AI surfaces. Airlead calls your HTTPS endpoint with a signed JSON request; you respond with Widget Protocol v1 payloads. This is not the same as lead ingest or Connect delivery. Modules enrich the UI; they do not mutate workspace data.

Concepts

Term	Meaning
Module	Catalog entry (`WidgetApp`) with a `dataEndpoint` and signing secret
Card	One renderable payload (`trendMetric`, `insight`, …)
Surface	Where the module may appear
Scope	Which record fields Airlead includes in the request

Surfaces

Surface	Typical use	Partner kinds allowed
`record.person.command-deck`	Lead sidebar Command Deck	`trendMetric`, `insight`, `entityProfile`, `actionRow`
`record.interest.command-deck`	Interest sidebar Command Deck	`trendMetric`, `insight`, `entityProfile`, `actionRow`
`ai.chat.empty`	Work / empty-home dashboard	`trendMetric`, `insight` (plus `clarify` for first-party only)

ai.chat.inline is reserved for Airlead AI tool results (drafts, delivery repair, …). Partners must not return workflow cards such as draft, deliveryRepair, or confirmDraft actions.

Registration

Airlead registers your module server-side (slug, publisher, HTTPS endpoint, surfaces, scopes). After registration, a workspace admin enables it under Settings → Apps & Module → Partner-Widgets. Local / staging helper (Airlead operators):

node --require ./scripts/stub-server-only.cjs --import tsx scripts/register-partner-widget.ts \
  --slug acme.enrichment \
  --name "Acme Enrichment" \
  --publisher "Acme" \
  --endpoint https://widgets.acme.example/v1/airlead \
  --surfaces record.person.command-deck,record.interest.command-deck,ai.chat.empty \
  --scopes record.id,record.type,record.displayName,record.city,record.postalCode

The script prints a signingSecret. Store it with the partner; it is never exposed to browsers. Endpoint rules:

Public https:// URL, or
Same-origin mock only: /api/widgets/partner-mock (development)

Request (Airlead → partner)

POST your dataEndpoint with:

Header	Value
`content-type`	`application/json`
`accept`	`application/json`
`x-airlead-widget-protocol`	`1`
`x-airlead-widget-timestamp`	Unix seconds
`x-airlead-widget-signature`	`v1=<hex>` HMAC-SHA256

Signature

Canonical string:

${unixSeconds}.${rawBody}

HMAC-SHA256 with the shared secret, hex-encoded, prefixed with v1=. Reject requests when:

Signature missing or mismatch
Timestamp skew greater than 5 minutes

Body

{
  "version": "1",
  "slug": "acme.enrichment",
  "surface": "record.person.command-deck",
  "workspace": { "id": "ws_…", "slug": "acme" },
  "locale": "de",
  "scopes": ["record.id", "record.type", "record.displayName", "record.city"],
  "record": {
    "type": "person",
    "id": "lead_…",
    "displayName": "Max Mustermann",
    "city": "Berlin",
    "postalCode": "10115"
  }
}

record only contains fields granted by scopes. Default partner scopes exclude email and phone unless explicitly granted at registration. For ai.chat.empty, Airlead may send a workspace-level placeholder record (id like workspace:…). Prefer workspace-level metrics in that case; do not assume a real lead id.

Response (partner → Airlead)

{
  "version": "1",
  "slug": "acme.enrichment",
  "widgets": [
    {
      "kind": "trendMetric",
      "title": "Partner Score",
      "value": 82,
      "valueFormat": "number",
      "unitLabel": "pts",
      "appSlug": "acme",
      "actions": [
        {
          "id": "ask-score",
          "type": "followUp",
          "label": "Details",
          "prompt": "Wie setzt sich der Partner Score zusammen?"
        }
      ]
    }
  ]
}

Rules:

version must be "1"
slug must match the request
widgets is an array of Card payloads
Airlead filters kinds to the partner allowlist ∩ surface matrix
Actions may only be link or followUp (confirmDraft is stripped)

Respond quickly. Airlead aborts partner fetches around 800 ms; timeouts soft-fail and hide the module for that paint.

Allowed Card kinds (partner)

`trendMetric`

Large number with optional delta, period, footnote, and actions.

`insight`

Headline + body + optional evidence prompts (good for alerts).

`entityProfile`

Compact entity summary (Command Deck).

`actionRow`

Action buttons only — link / followUp.

Scopes

Scope	Field
`record.id`	Always included
`record.type`	`person` \| `interest`
`record.displayName`	Display name
`record.email`	Email (opt-in)
`record.phone`	Phone (opt-in)
`record.city`	City
`record.postalCode`	Postal code
`record.country`	Country
`record.companyHint`	Company hint
`record.productName`	Product
`record.sourceName`	Source label
`record.interestRequestId`	Interest id when applicable

Errors

Return HTTP 2xx only with a valid Protocol v1 body. Non-2xx responses are treated as partner errors. Airlead maps failures to soft UI errors (timeout, unauthorized, invalid_response, partner_error, unavailable) and does not block the rest of the deck.

Enablement

Module registered and published
Workspace enables it under Apps & Module
Surfaces include the target surface
Endpoint reachable from Airlead servers with a valid signature

Core Airlead modules default to enabled; partner modules default to disabled until toggled on.

Security checklist

Use TLS and rotate the signing secret if leaked
Verify signature + timestamp on every request
Do not log full record payloads with PII
Never return Airlead workflow cards or draft confirmations
Keep responses under the timeout budget

Developers introduction
Connect integration (workspace-to-workspace delivery — separate from widgets)
Product: Settings → Apps & Module

Start integrating

Send leads to Airlead

Receive leads from Airlead

Connect Airlead workspaces

Airlead AI modules

AI widgets (headless protocol)

AI widgets (headless protocol)

Concepts

Surfaces

Registration

Request (Airlead → partner)

Signature

Body

Response (partner → Airlead)

Allowed Card kinds (partner)

`trendMetric`

`insight`

`entityProfile`

`actionRow`

Scopes

Errors

Enablement

Security checklist

​AI widgets (headless protocol)

​Concepts

​Surfaces

​Registration

​Request (Airlead → partner)

​Signature

​Body

​Response (partner → Airlead)

​Allowed Card kinds (partner)

​trendMetric

​insight

​entityProfile

​actionRow

​Scopes

​Errors

​Enablement

​Security checklist

​Related

AI widgets (headless protocol)

Concepts

Surfaces

Registration

Request (Airlead → partner)

Signature

Body

Response (partner → Airlead)

Allowed Card kinds (partner)

`trendMetric`

`insight`

`entityProfile`

`actionRow`

Scopes

Errors

Enablement

Security checklist

Related