Forward live calls to any WebSocket

Take a real inbound call on a voice agent that has no public answer URL yet (on your laptop, a staging box or a teammate’s tunnel) with one command.

Route real incoming calls through a tunnel to your voice agent over its WebSocket connection while developing. First log in, start your voice agent, and attach a number to a dedicated test application. Use that number and application ID:

plivo voice streams forward --number [phone] \
  --app "<app_id>" --to ws://localhost:7860/ws

Replace the example values, approve the routing change, then call the number from a phone. Calls use your normal Plivo billing. Keep the command running; Ctrl-C restores the saved answer URL unless you pass --keep.

​

How it works

--to accepts a ws:// or wss:// URL on your laptop, a staging server or a colleague’s tunnel. The tunnel runs on the CLI’s machine.

forward saves the application’s answer_url, starts a tunnel and local HTTP/WebSocket server, and updates the application to use that tunnel. It forwards call audio to your voice agent. On Ctrl-C or a tunnel failure, it restores the saved URL; a tunnel failure exits 3. See the recovery behavior below for a process that is killed outright.

Every phone number attached to the application is redirected for as long as forward runs: the confirmation step tells you how many. Use a dedicated test application.

​

The tunnel

The localhost.run tunnel needs an SSH client on PATH and no tunnel account. macOS and Linux commonly include SSH; install it if the CLI reports ssh not found. If ngrok is already on your PATH (or at ~/.plivo/bin/ngrok) the CLI uses that instead, since a warmed-up ngrok is usually faster. --tunnel forces the choice: auto (the default) prefers ngrok when it is present and falls back to localhost.run, also when ngrok can’t start; ngrok and localhost.run pin one provider.

The confirmation prompt and the --dry-run preview print a placeholder answer URL of the form https://<ngrok-tunnel>/answer whichever provider is chosen. The real tunnel URL is printed once the tunnel is up.

​

Command and flags

Usage

plivo voice streams forward [flags]

Flags

Flag	Description
--app <string>	application ID returned when you create the app; its answer URL is temporarily redirected (required)
--bidirectional	allow your voice agent to send audio back to the caller (default true)
--codec <string>	audio codec advertised to Plivo: mulaw | l16 (default “mulaw”)
--insecure-skip-signature	accept unsigned tunnel requests. Anyone with the tunnel URL can then drive your handler; leave signature checks enabled for real calls.
--keep	leave the application pointing to the tunnel on exit (advanced)
--number <string>	international number with country code, such as [phone], attached to --app (required)
--print-payload	dump full webhook bodies to terminal (verbose)
--rate <int>	sample rate in Hz (mulaw: 8000; l16: 8000 or 16000) (default 8000)
--to <string>	local WebSocket URL to forward call audio to, e.g. ws://localhost:7860/ws (required)
--tunnel <string>	tunnel provider: auto | ngrok | localhost.run (default “auto”)
-y, --yes	skip the confirmation prompt

Examples

  plivo voice streams forward \
    --number [phone] \
    --app "<app_id>" \
    --to ws://localhost:7860/ws
  # Don't restore answer_url on exit (advanced):
  plivo voice streams forward --number [phone] --app "<app_id>" --to ws://localhost:7860/ws --keep

--codec and --rate follow the same rules here as they do for streams test, and an unsupported pair is rejected before anything is redirected: see The audio contract.

Nothing is purchased, created, or deleted: the only change is one field on one application, restored on exit unless you pass --keep. forward saves the original answer URL in ~/.plivo first. If it is killed outright (kill -9), the next forward on that application restores the real answer URL and, on macOS and Linux, stops the tunnel the killed run left behind. A second forward on the same application is refused while one is running.

A localhost.run or trycloudflare.com URL is not saved as the original answer URL. An ngrok URL can be saved, with a warning, because ngrok also supports fixed domains.