# AI caller — Retell and Yunke parity

Part of the [AI Voice Agent](/docs/modules_handbook/shared/voice-agent/readMe.md). Added
2026-11-06, read against the code on `dev-shawn` at `587f3e19b`; updated 2026-11-11 (the brain
and the reading moved into the CRM for Yunke). This is the map of what each provider can do
today. Update it in the same change as the code.

## What it does

Keeps the two AI call providers level. The owner wants every Retell function available on
Yunke, so the module does not grow into two different products.

**The rule.** A new AI caller function is built for **both** providers in the same change:
placement, campaign settings, limits, results and after-call work. When one provider truly
cannot do it, the same change adds or updates its row here with the reason. A gap is allowed;
a silent gap is not.

**Owner decision, 2026-11-06.**

| Use | Provider |
| --- | --- |
| AI Rounds | Retell + Twilio for now. The end goal is to move them to Yunke too. |
| Landing-page registration calls | Yunke is the target. |
| Every other place that triggers an AI call | The admin can choose Retell or Yunke. |

**Owner decision, 2026-11-11.** A vendor only places the call and returns the transcript and
recording. The brain is configured in the CRM for both providers, and every reading (summary,
sentiment, extracted answers) is done by our own AI (`ReadAiVoiceCall`). A phone profile is
always on `analysis_mode = own`; a Retell profile is switched to it on AI Profiles.

Retell is not replaced until the owner says so. This table records the target; nothing here
switches a live campaign.

## How it works

Status words used below:

| Status | Meaning |
| --- | --- |
| Same | Works on both. |
| Shared, unproven | One shared code path, not yet exercised live on Yunke. |
| Different | Each side protects or works its own way, and that is accepted. |
| Build | Our code can close the gap. |
| Evidence | Needs real Yunke results before it can be mapped. |
| Vendor | Needs Yunke to provide it or confirm it. |
| Cannot | No equivalent on a phone line. |

### Where a call can start

`PlaceAiVoiceCall::outsideFunnel()` refuses Yunke for a payment item, a hand-placed call, an AI
round and the Appointment Engine, with `REFUSAL_PROVIDER_FUNNEL_ONLY`.

| Function | Retell | Yunke today | Status | Closes by |
| --- | --- | --- | --- | --- |
| Landing-page registration welcome | Yes | Rule can pick a Yunke profile, and market mode lets it reach real leads | Shared, unproven | One owner-number run through a real registration |
| Thank-you page promise | Countdown close to the real start | "Within minutes", no countdown; both wait for the profile's own window | Different | |
| Funnel reminders and VSL triggers | Yes | Same `SendFunnelAiCall` job | Shared, unproven | Live test after the allowlist |
| Funnel call-back button and link | Yes | Same `PlaceFunnelAiCallback`, provider frozen per send | Shared, unproven | Live test |
| WhatsApp "call me again" button | Yes | Not refused, uses the origin call's profile | Shared, unproven | Live test |
| Pilot split between two campaigns | Yes | Yes | Same | |
| Redial after a missed call | Yes | Shared `AiCallRedial`, but needs a verified missed result | Evidence | Collect missed and busy samples |
| AI Rounds | Yes | Refused | Build | Later, by owner decision |
| Payment item call | Yes | Refused at the form and at placement | Build | Open the guard, then test its own after-call rules |
| Hand-placed call | Yes | Refused | Build | Open the guard, then test `HandPlacedCallAftermath` |
| Appointment Engine | Yes | Refused | Build | Replace its Retell call lookup first |
| HR interview bridge | Yes | Reads Retell directly | Build | Only if HR moves off Retell |

### Real customers

| Function | Retell | Yunke today | Status | Closes by |
| --- | --- | --- | --- | --- |
| Call any lead | Yes | [Market mode](/docs/modules_handbook/shared/voice-agent/yunke-console.md), off by default: any number in the profile's market, keeping the block list, landing-page choice, cap and window | Shared, unproven | Live test, then turn it on |

### Setting up a campaign

Retell campaigns live in **AI Profiles**. Yunke phone profiles live in the **Yunke console**.
`AiProfilesController::requireRetell()` guards update, clone, pull, test call, delete, chat test,
browser audio and copilot.

| Function | Retell | Yunke today | Status | Closes by |
| --- | --- | --- | --- | --- |
| Name, market, window, cap | Yes | Yes | Same | |
| Prompt (the brain) | Full prompt in the CRM, pushed by Sync | Full brain in the CRM (phone profile, up to 4,000 characters), sent with every task as 客户备注 and read by one fixed shell script in the App | Same | The longest brain proven live goes in yunke-scenarios.md |
| Opening line, voice, speed, knowledge base, language | In the CRM | In the App, one set for the account; the shell's personalised opening greets the lead by name (客户名称) | Vendor | No vendor API is offered; the App's internal script endpoints are the next option |
| Voice clone | Yes, from the CRM | In the phone App only. Its strings say one clone per account, a new one overwrites it, and clone attempts are limited | Vendor | Confirm the vendor's voice API and consent |
| Extraction fields | Yes | Yes, on the phone profile, filled by our own reading | Same | |
| Test call from the page | Yes | CLI self-test only | Build | Add a guarded test button |
| Text chat test, browser audio test | Yes | None | Cannot | The brain and voice run on the vendor's side |
| Copilot editing | Yes | None | Build | Point it at the scenario instructions |
| Clone a profile | Yes, from AI Profiles and the AI Appointment System's AI Caller setting | Yes, from the Yunke console. Copies the extra instructions, market, cap, window, Retell backup and redial settings, and starts paused | Same | |
| Sync, pull, import | Yes | Not needed | Different | Yunke has nothing to publish |

### Limits and safety

| Function | Retell | Yunke today | Status | Closes by |
| --- | --- | --- | --- | --- |
| Block list and contact suppression | Yes | Yes | Same | |
| Call window | Per profile, or global quiet hours | Per profile, any same-day hours (bound removed 2026-11-10) | Same | |
| Daily limit | Spend cap in USD | Call cap per profile | Different | |
| Market check | Optional prefixes | Required prefixes, one SIM per market | Different | |
| Caller ID per campaign | `from_number` | Fixed by the phone's SIM | Different | One phone per caller ID |
| Stop one accepted call | Not built in the CRM | No remote stop; phone-side only | Vendor | Ask for a stop endpoint |
| Backup when a call cannot go out | Is the backup | Hands the call once to a chosen Retell profile, only when refused before any task exists | Different | An accepted task that never dials still has no backup |

### During the call

| Function | Retell | Yunke today | Status | Closes by |
| --- | --- | --- | --- | --- |
| Start speed | 14 s on average, 26 s at most (379 connected calls) | 24 s to 16 min 44 s (5 timed tests, not steady) | Vendor | Measure a run of calls, then ask the vendor |
| Calls at once | 14 started in one minute, 353 in one hour | One per phone | Vendor | More phones, and confirm one account per phone |
| Length limit, silence hang-up, voicemail hang-up | Set by `RetellAgentSync` | Decided by the vendor, not read or set by us | Vendor | Confirm the behaviour |

### After the call

| Function | Retell | Yunke today | Status | Closes by |
| --- | --- | --- | --- | --- |
| How results arrive | Webhook, then a reconcile sweep | `voice-agent:yunke-watch` reads the Web console | Different | |
| Transcript | Yes | Yes; the 2026-11-10 prod call (Mandarin with an English switch) was transcribed accurately | Same | |
| Summary, sentiment and extracted answers | `ReadAiVoiceCall` on `analysis_mode = own` | Always `ReadAiVoiceCall`, queued when the transcript settles; Yunke's summary is kept in `meta.yunke_vendor_analysis` for reference and as the fallback if our reading fails | Same | |
| No answer, busy, voicemail | Yes | Reason dictionary is empty, so these stay held | Evidence | Collect real samples |
| Discussion comment, thanks and missed WhatsApp, alerts | `AiCallAftermath` | Same class, behind the `aftermath` control | Shared, unproven | Live test with the control on |
| Recording | URL from Retell | Yunke uploads it minutes after the call: the watch reads the call again for a day until the link appears, then the copy to private storage runs when `YUNKE_RECORDING_COPY_ENABLED` is on with `yunke-pcfile.oss-cn-beijing.aliyuncs.com` allowed | Shared, unproven | First copied recording on prod |
| Cost per call | `cost_usd` | None | Vendor | Confirm the price |
| AI Calls list, filters, pilot report | Yes | Yes | Same | |

### Running it

| Function | Retell | Yunke today | Status | Closes by |
| --- | --- | --- | --- | --- |
| Login | API key | App token and Web Cookie, replaced by hand when they expire | Vendor | Confirm their lifetime |
| Line health | Provider service | No live phone or box signal | Vendor | Ask for a device status |
| Interface | Official API | The App's and Web console's internal APIs | Vendor | Agree a supported route |
| Uptime | Cloud | One phone and box that must stay on and charged | Evidence | Run charging, lock-screen and reconnect tests |

## Related files

- `app/Actions/PlaceAiVoiceCall.php` — the funnel-only guard, limits and provider choice.
- `src/Common/VoiceAgent/ConversationalCallerResolver.php` — provider per campaign, never a fallback.
- `src/VoiceAgent/AiCallProfile.php` — `usesRetell()`, `usesYunkeApp()`, `canAssignToFunnel()`.
- `app/Http/Controllers/Manage/Calls/AiProfilesController.php` — Retell campaign actions.
- `app/Http/Controllers/Manage/Calls/YunkeController.php` — Yunke console and phone profiles.
- `app/Jobs/Automation/SendFunnelAiCall.php`, `app/Actions/PlaceFunnelAiCallback.php` — funnel calls.
- `app/Http/Requests/Manage/Payment/PaymentLinks/AiProfileRequest.php` — the payment form's refusal.
- `src/VoiceAgent/Services/YunkeAppTaskSubmit.php` — the allowlist check at submission.
- `app/Jobs/Calls/ReadAiVoiceCall.php`, `src/VoiceAgent/Services/YunkeAppResultIngest.php`,
  `src/VoiceAgent/Services/AiCallAftermath.php` — after the call.
- [Pilot routing](/docs/modules_handbook/shared/voice-agent/pilot-routing.md) and the
  [progress ledger](/docs/modules_handbook/shared/voice-agent/yunke-pdf-progress.md).
