call-center/docs/runbooks/ivr-local.md

IVR Local Runbook

Use this runbook to validate both the preview IVR runtime and the live Asterisk-backed IVR staging path.

What Track 5 adds

• ivr-service for IVR flow CRUD and DTMF runtime sessions
• one active IVR flow per voice queue
• routing-service support for ivr_session_id
• admin-side IVR preview flow in /admin

Preview baseline vs live IVR

• Preview baseline: use the /admin IVR block to create flows, start sessions, send DTMF, and preview route overrides without telephony.
• Live Asterisk IVR: call 7200 on the lab PBX after asterisk-bridge-service is configured with ASTERISK_IVR_FASTAGI_* and the flow nodes have valid prompt_audio_key values.

Create a flow

1. Open http://localhost:8080/admin
2. Go to the IVR block
3. Set:
   • queue_id
   • entry_node_id (root)
   • flow_json
4. Click Create flow

The flow JSON is validated before it is saved.

Start a session

1. In the same IVR block, set:
   • call_id
   • queue_id
   • optional interaction_id
2. Click Start session

The response returns:

• session_id
• current_node_id
• current node prompt metadata

Send DTMF

1. Enter a single digit (0-9)
2. Click Send DTMF

If the transition reaches a terminal node:

• the session becomes completed
• outcome_code is set
• resolved_queue_id is set
• resolved_queue_code is set
• a voice_event with event_type="ivr.completed" is written

Preview route override

1. Keep the completed session_id
2. Click Preview IVR route

This calls routing-service with ivr_session_id and shows:

• original_queue_id
• resolved_queue_id
• ivr_outcome_code

Demo seed

scripts/prepare_demo.ps1 now seeds:

• one demo IVR flow
• one completed demo IVR session
• one route preview stored in .local_stack/demo-seed-summary.json

Backstage fields:

• ivr_flow_id
• ivr_session_id
• ivr_outcome_code
• ivr_resolved_queue_id

Live Asterisk smoke

1. Enable:
   • ASTERISK_BRIDGE_ENABLED=1
   • ASTERISK_IVR_FASTAGI_ENABLED=1
   • IVR_RUNTIME_TRUSTED_SERVICE_SUBJECTS=svc:asterisk-bridge
2. Make sure ASTERISK_QUEUE_MAP_JSON contains voice_lab_ivr.
3. Provision the prompt_audio_key sound files in Asterisk.
4. Call 7200 and verify:
   • DTMF completes the IVR and transfers through mvpcc-transfer
   • silence triggers ivr.step.no_input
   • retry exhaustion abandons the IVR session and falls back to the human baseline

Troubleshooting

• 404 No active IVR flow for queue
  • create or activate a flow for the target queue first
• 400 Digit must be a single character 0-9
  • send exactly one DTMF digit
• 400 IVR session is not completed on route preview
  • finish the session with a terminal node before previewing routing