135 lines
3.6 KiB
Markdown
135 lines
3.6 KiB
Markdown
# Human Handoff / Fallback
|
|
|
|
TZ-11 adds a safe Human Handoff and fallback layer. The default behavior is intentionally non-transferring.
|
|
|
|
## Purpose
|
|
|
|
Human handoff gives the AI operator a controlled way to react when the caller asks for a live operator or when automated service cannot safely continue.
|
|
|
|
## Default Behavior
|
|
|
|
Default configuration:
|
|
|
|
```env
|
|
HANDOFF_MODE=disabled_stub
|
|
HANDOFF_ENABLED=false
|
|
HANDOFF_ALLOW_IN_TEST_ROUTE_ONLY=true
|
|
```
|
|
|
|
With these defaults:
|
|
|
|
- no real transfer is attempted;
|
|
- `request_human_handoff` creates a structured request;
|
|
- conversation state moves to `HANDOFF`;
|
|
- the caller receives a safe message that direct transfer is not connected yet.
|
|
|
|
## Handoff Modes
|
|
|
|
- `disabled_stub`: records the request and returns a safe message. No ARI transfer.
|
|
- `ari_redirect`: uses ARI channel redirect when explicitly enabled and configured.
|
|
- `dialplan_continue`: returns the channel to dialplan when explicitly enabled and configured.
|
|
- `hangup_after_message`: returns a final message and moves toward closing without transfer.
|
|
|
|
Real transfer modes require `HANDOFF_ENABLED=true` and valid target fields. Production routes remain protected.
|
|
|
|
## Config Variables
|
|
|
|
- `HANDOFF_MODE`
|
|
- `HANDOFF_ENABLED`
|
|
- `HANDOFF_TARGET_ENDPOINT`
|
|
- `HANDOFF_DIALPLAN_CONTEXT`
|
|
- `HANDOFF_DIALPLAN_EXTENSION`
|
|
- `HANDOFF_DIALPLAN_PRIORITY`
|
|
- `HANDOFF_QUEUE_NAME`
|
|
- `HANDOFF_TIMEOUT`
|
|
- `HANDOFF_MAX_ATTEMPTS`
|
|
- `HANDOFF_PLAY_MESSAGE_BEFORE_TRANSFER`
|
|
- `HANDOFF_HANGUP_AFTER_STUB`
|
|
- `HANDOFF_ALLOW_IN_TEST_ROUTE_ONLY`
|
|
- `HANDOFF_MAX_SUMMARY_CHARS`
|
|
|
|
Fallback thresholds:
|
|
|
|
- `FALLBACK_MAX_LANGUAGE_FAILURES`
|
|
- `FALLBACK_MAX_REGION_FAILURES`
|
|
- `FALLBACK_MAX_NO_ANSWER`
|
|
- `FALLBACK_MAX_KB_UNAVAILABLE`
|
|
- `FALLBACK_MAX_AI_ERRORS`
|
|
- `FALLBACK_MAX_MEDIA_ERRORS`
|
|
- `FALLBACK_MAX_TOOL_ERRORS`
|
|
- `FALLBACK_CALL_TIMEOUT`
|
|
|
|
## Detector Phrases
|
|
|
|
The handoff detector supports Russian, Kazakh, and mixed/Latin phrases such as:
|
|
|
|
- `оператор`
|
|
- `соедините с оператором`
|
|
- `хочу поговорить с человеком`
|
|
- `операторға қосыңыз`
|
|
- `маман керек`
|
|
- `live agent`
|
|
- `speak to human`
|
|
|
|
Ambiguous business phrases such as `оператор связи` are not treated as confident handoff requests.
|
|
|
|
## Fallback Scenarios
|
|
|
|
Fallback manager can offer handoff or safe closing for:
|
|
|
|
- KB unavailable;
|
|
- repeated no-answer;
|
|
- repeated language failures;
|
|
- repeated region failures;
|
|
- AI provider error;
|
|
- media error;
|
|
- tool error;
|
|
- call timeout.
|
|
|
|
## ARI Redirect Mode
|
|
|
|
`ari_redirect` calls:
|
|
|
|
```text
|
|
POST /ari/channels/{channelId}/redirect?endpoint={endpoint}
|
|
```
|
|
|
|
It is only used when enabled and configured. Required tests use fake/httptest clients.
|
|
|
|
## Dialplan Continue Mode
|
|
|
|
`dialplan_continue` calls:
|
|
|
|
```text
|
|
POST /ari/channels/{channelId}/continue?context={context}&extension={extension}&priority={priority}
|
|
```
|
|
|
|
It is only used when enabled and configured.
|
|
|
|
## Production Route
|
|
|
|
Production routes remain disabled. `HANDOFF_ALLOW_IN_TEST_ROUTE_ONLY=true` prevents real transfer outside the test route.
|
|
|
|
## Safe Tests
|
|
|
|
```bash
|
|
./bin/ai-operator doctor --env /etc/ai-operator/ai-operator.env --check-handoff
|
|
./bin/ai-operator handoff-self-test --env /etc/ai-operator/ai-operator.env
|
|
./bin/ai-operator fallback-self-test --env /etc/ai-operator/ai-operator.env
|
|
```
|
|
|
|
These commands do not perform real transfer.
|
|
|
|
## Not Implemented Yet
|
|
|
|
- real operator queue/extension;
|
|
- production handoff enablement;
|
|
- call transcript persistence;
|
|
- CRM ticket creation;
|
|
- operator schedule/availability checks.
|
|
|
|
|
|
## Audit Integration
|
|
|
|
Handoff requests write `ai_handoff_audit` records with redacted summaries and transfer status. Default `disabled_stub` does not attempt real transfer.
|