--- name: customer-onboarding-call description: Place a one-off welcome and onboarding call to a customer who just signed up, capture a structured result such as business type, goal, pain points, sentiment, and activation status, then write that result back to a CRM and queue a human follow-up task when the customer asks for one. license: MIT ---

# Customer Onboarding Call

Use this skill when a new signup should receive a short welcome call and the business wants the conversation to end as structured data rather than as an unread recording.

`customer-onboarding-call` turns one signup event into at most one **conversation**, one structured result, and at most one follow-up task. Obtaining that conversation may take up to three attempts on an unreliable corridor, with only one attempt in flight at a time; see *Attempts, Retries, and Cancellation*. It does not create recurring schedules, call campaigns, or contact lists. Recurrence, if the business wants it, belongs to the host scheduler; see [`call-reminder`](../call-reminder/).

The workflow is deliberately narrow: welcome, consent, discovery, next-step offer, wrap-up. A call that tries to sell, negotiate, collect payment, or resolve a support ticket is out of scope.

## When To Use

Use this skill for:

- welcoming a customer who just signed up and confirming they can get started - collecting first-party onboarding context: business type, goal, prior tooling, blockers - detecting whether a customer wants a human to follow up - turning a spoken answer into a CRM field and an assigned task - measuring activation coverage when a team cannot call every signup manually

## When Not To Use

Do not use this skill to:

- call people who did not sign up or otherwise ask to be contacted - run sales, collections, renewal, or win-back calls - deliver medical, legal, financial, or emergency instructions - read pricing, delivery windows, contractual terms, or policy from memory - retry indefinitely after a customer declines or asks not to be called - re-call a customer who has already completed an onboarding call, unless the user explicitly asks

## Required Fields

For each call, require:

- `customerName` - `phoneNumber` in E.164 - `companyName` for the agent to introduce itself as - `companyDescription`, one sentence the agent may state as fact

Optional:

- `businessName` - `locale` and `region` hints for the conversation

Ask for any missing required field. Do not infer a phone number, country code, or region from a locale, an IP address, an email domain, or unrelated prior context.

## Core Workflow

1. Confirm the signup is real and recent, and that this customer has not already been called. 2. Build the call task from the required fields. Keep the script to roughly two minutes. 3. Attach a structured result schema so the provider returns fields, not just a transcript. See [`references/structured-result.md`](references/structured-result.md). 4. Persist an attempt record under a uniqueness constraint on `(signup_id, attempt_no)` **before** dialing, and derive the provider idempotency key from it. Refuse to start a new attempt while another is in flight for the same signup. 5. Place the call for that attempt. 6. Receive the terminal result on a webhook. Treat delivery as at-least-once and key ingestion on the provider event id. 7. Classify the outcome before writing anything: Stage A decides whether a human took part, and only then does Stage B read consent. See *Outcome Classification* below. 8. Write only what the outcome permits, then queue a follow-up task only when the outcome is `onboarded` and the customer asked for one. 9. Schedule or cancel a retry according to *Attempts, Retries, and Cancellation*.

Use this shape:

```text signup -> attempt record -> call task + result schema -> attempt -> terminal webhook -> classify -> permitted CRM write -> follow-up or retry or suppress ```

## Conversation Shape

Keep the call in this order. Allow interruption at any point.

1. **Greet and identify.** Name the customer, name the company, state that the call may be recorded if that is true in your jurisdiction. 2. **Ask consent.** Ask whether now is a good time for a short call. If the answer is no, offer to call back later and end. Do not continue discovery after a soft refusal. 3. **Discovery.** Ask what kind of business they run, why they signed up, what problem they want solved, and whether they have used something similar before. One question at a time. 4. **Offer the next step.** Invite the concrete first action, and offer a human if they prefer. 5. **Wrap up.** Summarize what will happen next, thank them, end.

The agent may answer only from `companyDescription` and any knowledge base you explicitly supply. For anything else — price, delivery time, policy, availability — it must say it will have a human follow up. Inventing these is the most common failure mode of onboarding-call agents.

## State Machine

The full contract in one view. Every arrow that ends in a call is guarded; every terminal state says what it permits.

```text signup | v [ allocate attempt no > cap? ]---- yes -->( manual handling ) | ^ no | v | [ attempt live (leased) ] | | | +-------------------+--------------------+ | | | | | terminal result lease expires create failed | | | | | | v | | | [ reconcile with provider ] | | | | | | | | | terminal still live unknown | | | | | | | | +<------------+ v | | | | ( ambiguous )-+-------+ | | | (late result re-enters) | v | | == STAGE A: was a human reached? == | reachability from CALL EVIDENCE, not from "is there a result" | | | +-- refusal evidence present? --> ( declined ) | | | no-human — CLOSED evidence set only: voicemail / carrier msg / ring-out / no-answer / silence / provider machine signal | +--> ( not-reached ) ------------------ retry allowed ---+ | | +--> ( failed ) provider positively says NO CALL PLACED --+ | +--> ( needs-review ) indeterminate: provider unreachable, | unknown attempt, expired lease, extractor-only NotReached, | billing charge with no obtainable outcome. NO RETRY. | human v == STAGE B: consent governs == | +--> ( declined ) terminal. suppress per scope. no follow-up, no retry, ever. +--> ( needs-review ) no result at all, unusable consent fields, or indeterminate | reachability. terminal until a human decides. NO auto retry. +--> ( partial ) write captured fields only. retry ONLY with callback consent | or human authorisation, and only under the cap. +--> ( onboarded ) write insight. follow-up only if requested. ```

Invariants the diagram encodes:

- **A redial requires positive no-human evidence from a closed set.** A missing result, an extractor-claimed `NotReached`, an unreachable provider, an expired lease, and a billing charge are all *unknown* — they route to `needs-review`, never to a retry. - **Releasing a stuck attempt and authorising a redial are separate decisions.** Unblocking the slot is bookkeeping; dialling again needs evidence. - **Refusal evidence dominates.** It routes to `declined` from anywhere, with or without a result. - **Only Stage B can suppress a number**, and only via `declined`. - **Only Stage A outcomes retry automatically.** Every Stage B redial needs consent or a human, and anything uncertain lands in `needs-review`, which never retries. - **No state is permanent-by-accident.** A live attempt is leased, and `ambiguous` is provisional — a late result re-enters classification from the top. - **The cap bounds every path**, including callback-consented redials.

## Outcome Classification

A call that reaches a terminal state has not necessarily reached a consenting human. Providers commonly return a completed call with an empty structured result when the agent talked to a carrier message, voicemail, or silence. A call can also produce a perfectly well-formed structured result while the customer was refusing to take part.

**The presence of a structured result is not evidence of consent.** Classification is therefore driven by an evidence-backed `disposition` field, not by whether a result exists. See [`references/structured-result.md`](references/structured-result.md).

Classify in **two stages, in this order**. Stage A decides whether a human took part at all. Only if one did does Stage B read consent.

The staging is the contract, not a presentation choice. Consent fields are meaningless when nobody answered — a voicemail grants no consent, so `consent_granted` is `false` there. Reading consent before establishing that a human was reached turns every no-answer into a refusal.

### Stage A — was a human reached?

**Reachability is decided on call evidence, never on whether a structured result exists.** A real conversation can return no result at all: extraction failed, the result failed validation, or the customer refused and rang off before the model emitted anything. Inferring "nobody answered" from a missing result would auto-retry those calls and redial a person who may have just refused.

#### The no-human evidence set

Exactly one thing authorises an automatic redial: **observed evidence from the call itself that no person took part.** This is a closed list.

| Counts as no-human evidence | | | --- | --- | | voicemail or answering-machine greeting | carrier or network announcement | | ring-out with no answer | the provider's own answered-by-machine / no-answer signal | | silence throughout after the agent spoke | |

**Nothing else qualifies.** In particular these are *not* no-human evidence, however tempting:

- a missing or empty structured result - the extractor's own `disposition: NotReached` — that is a model claim about the call, not an observation of it, and the same extractor mislabels refusals - a provider that is unreachable, times out, or has no record of the attempt - an expired lease - a billing charge or usage record — that shows a call *was placed*, which if anything makes a conversation more likely, not less

Every one of those means **we do not know**. Unknown is `needs-review`, never a retry. The asymmetry is deliberate: a needless manual check costs a minute, and a wrong redial reaches someone who may have already refused.

#### Establishing reachability

| Reachability | Evidence | | --- | --- | | `human` | the provider reports a human answered, **or** the transcript contains customer speech that is not carrier or IVR audio | | `no-human` | at least one item from the no-human evidence set above, and no contradicting customer speech | | `indeterminate` | anything else, including every "not evidence" item listed above |

#### Then