# Yunke management console

Part of the [AI Voice Agent](/docs/modules_handbook/shared/voice-agent/readMe.md).
Added 2026-10-26. Engineering verification uses synthetic sessions and an isolated test
database. Installation does not save credentials, enable Yunke or submit any task.

## What it does

Platform super administrators open **Phone Call → Yunke** (`/manage/calls/yunke`).
The console manages existing account sessions, five runtime controls, paused platform
phone profiles and recent local call evidence. Both `manage-calls` permission and the
platform super-admin check apply to every action. Agency and ordinary call managers
cannot read or edit this platform connection.

The page refreshes local database evidence every 15 seconds. It does not log in, query
the vendor, create a task, dial, ingest a result or download media on render/refresh.
Device online state stays **unverified**: the verified APIs do not supply a live phone
or USB signal. A last recorded completed call is historical evidence only.

## How it works

### Connection and session checks

`yunke_connections` contains one platform record. Company, user, existing App token,
existing Web Cookie and recipient allowlist are encrypted together using `APP_KEY`.
The browser receives company/user, the allowlist and secret-presence booleans, never
the token, Cookie or a token fragment. Password inputs start empty. Blank keeps the
previous secret; an explicit clear removes it. Validation, CSRF/server redirects and
Inspector parameters exclude the secret fields.

Saving connection settings pauses all five controls and invalidates the previous
check. No App login/password workflow exists here: concurrent App login can invalidate
the phone session. Obtain matching company/user sessions through the existing approved
account process. A Web check does not prove the App token is valid or the device online.

For a replacement Android phone on the **same account**, use **Replace phone** rather
than re-entering the whole connection. The [phone replacement flow](/docs/modules_handbook/shared/voice-agent/yunke-phone-pairing.md)
exports the existing phone session locally, checks company/user and changes only the
App token. It keeps the Cookie, allowlist and business settings, pauses all five
controls and requires a new Web check. It never logs in or certifies the device.

**Check read-only session** performs one bounded `taskPage` query (`page=1,pageSize=1`)
using the saved Web Cookie, even while automatic reads are paused. The fixed HTTPS
origin, no-redirect/no-retry behavior and explicit authentication errors are retained.
It discards vendor records and stores only check time, fixed reason and credential
fingerprint. It never creates a task, maps IDs or stores an outcome. A failed check
pauses automation; an older in-flight check cannot certify edited credentials.

### Runtime controls

| Console control | Existing service setting | Requirement when saving |
| --- | --- | --- |
| Web result queries | `yunke_web_read.enabled` | Successful check of current sessions within 30 minutes |
| Record verified results | `yunke_app_results.enabled` | Explicit operator choice |
| Automatic result watch | `yunke_watch.enabled` | Reads and result processing enabled |
| New phone task submissions | `yunke_app_write.enabled` | Current successful check, App token, a nonempty recipient allowlist or market mode, reads/results/watch enabled |
| New after-call follow-ups | `yunke_app_results.aftermath_enabled` | Result processing enabled |

The 30-minute check is an enable-time prerequisite, not automatic session renewal or
proof a still-enabled session never expires. Existing query errors remain explicit.

### Backup Retell profile

A phone profile can name a **Backup Retell profile** (owner, 2026-11-10), stored as
`provider_settings.fallback_profile_id` and read by `AiCallProfile::fallbackProfile()`. Only a
platform Retell profile qualifies. The backup rings instead, once, only when the line could not
take the call **before any phone task existed** (`AiVoiceCall::FALLBACK_REFUSALS`):

- The line cannot call right now: switched off, an incomplete or broken session. `SendFunnelAiCall`
  and the landing page read `callableOrFallback()`, so the welcome still goes out, and the
  thank-you page shows the Retell countdown.
- Placement refused it: over the daily cap, a number outside the line's market, a number missing
  from the listed numbers, a scenario that cannot render, or Yunke rejecting the task outright.

It never takes over a blocked number, a journey contact stop, quiet hours or the Retell daily
budget. It also never takes over an accepted or unconfirmed task, because that task may still
dial and the lead would be rung twice. The refused phone-line row stays as the record of why.
The Retell row carries `meta.fallback_from_profile_id` and none of the `yunke_*` keys, so the
funnel send's phone-line recovery check never mistakes it for a phone task. A backup call does not
fall back again. A line whose phone accepted the task but never dialled is not covered yet.

The landing-page lecture welcome's backup, **讲座报名欢迎（Retell 后备）** (slug
`lecture-welcome-retell-backup`), is created by migration `2026_11_10_190000`. It is unpublished
until an admin presses Sync on AI Profiles, and it says the same as the Yunke cloud script
`petaV3-30-讲座报名欢迎华语`, reading the lecture from the funnel variables. Voice and speed are
copied from the registration welcome (slug `call`).

### Who can be called

**Who can be called** on the connection form has two modes, `YunkeConnection::RECIPIENT_MODES`:

- **Only the numbers listed below** (`listed`) is the default. A task goes out only to an exact
  number on the allowlist, which holds 500 at most.
- **Real customers in each profile's market** (`market`) is for live funnels. The allowlist is
  no longer consulted, and the number must sit inside the call's own phone profile prefixes.

Market mode is stored with the encrypted credentials and can only be set here by a super
admin. `.env` cannot turn it on, and no row, an unreadable row or an unknown value all mean
`listed`. Saving either mode pauses all five controls like any other save, so a mode change
always needs a fresh check and a deliberate enable. Replacing the phone keeps the mode.

Every other guard stays on in both modes: the block list, contact suppression, the customer's
landing-page choice (`DispatchFunnelWelcomeAction` skips the call before any provider is
chosen), the profile's daily cap and time window, and the funnel-only guard. The owner CLI
self-test still needs its one exact listed number.
Credentials and flag prerequisites are validated under the same database row lock.
Pausing is always permitted, including when saved credentials are unreadable.

`YunkeRuntime` is a scoped snapshot refreshed at placement, submission, Web HTTP,
ingestion/effect and watch boundaries. Existing queue workers observe changes without
a restart. A pause prevents new passes; it cannot cancel already accepted phone tasks,
queued messages or work already in flight. Use the separate accepted-task stop runbook
where necessary. Recording-copy/download controls, legacy App reads/login and alert
subscription settings remain separate deployment configuration.

Before the first console save, existing environment configuration still applies. After
that save, the database record controls these five gates and managed credentials;
cleared values do not fall back to old environment secrets. Unavailable storage or an
unreadable encrypted session closes these runtime gates. Following an `APP_KEY` change,
restore the original key or replace/explicitly clear both unreadable session values.
Do not delete the record as a pause operation: that would restore environment fallback.

### Phone profiles and evidence

**New phone profile** creates an inactive platform `app_single_task` profile with
market prefixes, positive daily cap and any same-day window (00:00–23:59 calls at any hour; the fixed 10:00–21:00 bound from the original 外呼方案 PDF was removed by the owner on 2026-11-10, matching a Retell profile's own window), in the
configured business timezone. **Edit** changes only those local settings and pauses
the profile. **Clone** (`POST profiles/{id}/clone`) makes a paused "Name (copy)" with the
scenario instructions, market, cap, window, Retell backup and redial and follow-up settings, leaving the
pilot split with the original and submitting no task. **Allow locally / Pause** changes profile eligibility; it does not change
global gates or control a vendor task. Existing split, redial and webinar policies are
preserved and remain configurable through AI Profiles. Retell, agency-owned and legacy
static-task profiles cannot be edited through these phone actions.

Market/window/cap edits do not mint a conversation settings version: that hash describes
conversation content, not dialing settings. The profile's [brain](/docs/modules_handbook/shared/voice-agent/yunke-scenarios.md)
(up to 4,000 characters) and its extraction fields are versioned; the brain travels with each
recipient and our own AI fills the fields after the call (`analysis_mode` is always `own` for
a phone profile). Editing either pauses the profile. Only the opening audio, knowledge and
voice stay in Yunke, behind the fixed shell script. A profile cap is not a verified SIM-wide
or hardware-wide quota.

For a separately approved owner-number test outside business hours, use the dedicated
[bounded CLI test](/docs/modules_handbook/shared/voice-agent/yunke-self-test.md). It leaves
the profile's business window intact and supplies a temporary period to both local
guards and the vendor request. Changing `ignoreQuietHours` alone cannot do this.

The console shows latest local lead-call summaries, normalized intention, binding/review
evidence and links to the full AI Calls and AI Profiles screens. It exposes no vendor
IDs or recording source URLs. Counts mean local task acceptance, recorded completion,
awaiting outcome and review; acceptance is not proof a phone dialed. Unknown result
statuses, identity conflicts and unverified missed/busy reason codes remain held.

## Related files

- `app/Http/Controllers/Manage/Calls/YunkeController.php`, dedicated Yunke Form Requests,
  `routes/web.php`, `SectionTabs.vue` — guarded routes and navigation.
- `resources/js/Pages/Manage/Calls/Yunke/` — console, connection/runtime forms and profile editor.
- `scripts/yunke-pair-phone.py` — local read-only session export for the same-account
  [phone replacement flow](/docs/modules_handbook/shared/voice-agent/yunke-phone-pairing.md).
- `src/VoiceAgent/YunkeConnection.php`, its repository, migration and `YunkeRuntime` —
  encrypted settings and the runtime resolver.
- `YunkeWebReadClient`, `YunkeAppTaskSubmit`, `YunkeAppResultIngest`, `YunkeCallWatch`,
  `ConversationalCallerResolver` — effective controls at operation boundaries.
- `YunkeConsoleTest.php`, updated watch/presentation regressions and `console.test.js` —
  offline permissions, secret lifecycle, one-page probe, pause propagation and UI behavior.

## Reference usage

After an approved deployment runs migrations/builds, a platform super administrator can
save existing matching sessions, inspect the single-page read check, create a paused
phone profile and review its limits. Saving alone leaves automation paused. Enabling
calling/follow-ups remains a deliberate operational action after the required business
approvals. This delivery did not enable any runtime, perform a live check, deploy or
claim formal PDF/pilot acceptance. See the [live acceptance pack](/docs/modules_handbook/shared/voice-agent/yunke-live-acceptance.md).
