wehub-resource-sync
426e9eeabd
@elizaos/plugin-phone
Phone integration for elizaOS — Android dialer overlay and iOS Phone Companion.
What it does
This plugin ships two independent surfaces:
Android Phone overlay
A full-screen dialer app (Dialer, Recent Calls tabs) that runs as an overlay inside the elizaOS Android shell. It reads call history from the native READ_CALL_LOG permission via @elizaos/capacitor-phone and exposes it to the agent runtime. Tapping a recent-call row places a call through Phone.placeCall. The address book lives in the separate Contacts view (@elizaos/plugin-contacts); the header "Contacts" button links to it through the eliza:navigate:view bus rather than embedding a duplicate contacts pane. When another surface (e.g. a Contacts "Call" control) navigates here with a number, the dialer is pre-seeded with it.
Phone Companion (iOS) A three-screen Capacitor surface (Chat, Pairing, Remote Session) that runs inside the main elizaOS iOS bundle. It pairs with a desktop Eliza agent via a QR code scan, mirrors the agent's chat stream, and can relay touch gestures to a remote VNC/noVNC session running on the paired Mac. APNs push notifications can trigger a Remote Session view automatically when enabled.
Capabilities added to the agent
| Surface | What the agent gains |
|---|---|
phoneCallLog provider |
Read-only Android call history injected into the agent's context for questions about recent calls. Fetches up to 50 entries. Requires ADMIN role. Available in contacts and messaging contexts. |
/phone view |
GUI dialer + transcript UI. Supports the phone-state, place-call, open-dialer, and save-call-transcript capabilities via interact(). |
/phone-companion nav tab |
iOS companion surface (pairing, chat-mirror, remote-session). |
Enabling the plugin
import { appPhonePlugin } from "@elizaos/plugin-phone";
// Pass to the elizaOS runtime plugin list:
const runtime = new AgentRuntime({
plugins: [appPhonePlugin],
// ...
});
The Android overlay registers automatically when the host is the elizaOS Android shell (isElizaOS() returns true). The Phone Companion page registers unconditionally for iOS and desktop hosts.
Required permissions (Android)
The native @elizaos/capacitor-phone plugin requires READ_CALL_LOG and CALL_PHONE permissions in the host APK's AndroidManifest.xml. The plugin surface renders correctly without these permissions, but call-log and call-placement features will fail at runtime.
Environment / config
All configuration variables are Vite build-time env vars for the companion surface. They do not affect the Android overlay or the agent-side provider.
| Variable | Default | Description |
|---|---|---|
VITE_ELIZA_AGENT_URL |
— | Pre-configured agent ingress URL shown in the companion Chat view before pairing |
VITE_ELIZA_APNS_ENABLED |
"0" |
Set to "1" to enable APNs push registration on iOS |
VITE_ELIZA_LOG_LEVEL |
— | Log level for the companion surface |
Building
bun run --cwd plugins/plugin-phone build
The build produces three outputs: dist/index.js (main ESM bundle), dist/views/bundle.js (plugin view bundle loaded by the elizaOS view registry), and dist/index.d.ts (type declarations).
Native dependencies
@elizaos/capacitor-phone— Android dialer and call-log native bridge (workspace package).@capacitor/push-notifications— APNs push registration for the iOS companion.@capacitor/haptics— Haptic feedback on companion navigation transitions.@capacitor/preferences— Navigation stack persistence for the companion.@capacitor/barcode-scanner— QR pairing scan in the companion Pairing view.