---

name: add-dial description: Add Dial channel integration — a real phone number for SMS and AI voice calls via the Dial platform (getdial.ai). Native adapter — no Chat SDK bridge.

Add Dial Channel

Adds Dial — a real phone number for SMS and AI voice calls. Native adapter (no Chat SDK bridge): both directions go through the dial CLI — outbound via dial message, inbound via its command-target daemon. NanoClaw doesn't ship channels in trunk — this skill copies the Dial adapter, its pairing helper, and their tests in from the channels branch. The pair-dial setup step is maintained in trunk, so it is not copied here.

The mechanical steps under Apply carry nc: directive fences: an agent reads the prose and applies them, and a parser can apply them deterministically from the same document. Every directive is idempotent, so the whole skill is safe to re-run; anything a parser can't apply falls back to the prose beside it.

Apply

1. Copy the adapter, pairing helper, and tests

Fetch the channels branch and copy the Dial adapter, its pairing store and user-agent helper (each with its test), and the registration test into place (overwrite — the branch is canonical):

src/channels/dial.ts
src/channels/dial-pairing.ts
src/channels/dial-pairing.test.ts
src/channels/dial-user-agent.ts
src/channels/dial-user-agent.test.ts
src/channels/dial-registration.test.ts
src/channels/dial-grant.test.ts
src/channels/dial-status.test.ts

The dial-cli container skill is deliberately not copied here. container/skills/ is mounted read-only into every agent container (src/container-runner.ts), and a group with skills:'all' picks up whatever it finds there — so shipping the skill with the adapter would hand it to agents on installs that never configured Dial. It is installed only by /add-dial-tool, offered under Add phone superpowers below, which is the skill that actually provisions the CLI the skill documents.

dial.ts imports dial-user-agent.js at module scope, so omitting that helper breaks the build and every test that loads the channel barrel.

2. Register the adapter

Append the self-registration import to the channel barrel (skipped if present). This one line is the skill's only reach-in into the channel core:

import './dial.js';

3. Register the pairing setup step

Add the pair-dial loader to the STEPS map in setup/index.ts, inside the dormant marker region (skipped if already present — pair-dial ships in core, so this idempotent-skips on a normal install, but is expressed for a clean-upstream rebuild). The pairing handshake below spawns this step:

'pair-dial': () => import('./pair-dial.js'),

4. Install the packages

Pinned to exact versions — the supply-chain policy rejects ranges and latest. qrcode renders the scannable pairing card:

qrcode@1.5.4

The adapter needs no Dial client library: it shells out to the dial CLI, which this skill already requires for inbound. @getdial/sdk was dropped because it depends on pubnub, which pulls react-native, Metro and Hermes into the lockfile for what is a single send — and the CLI ships in lockstep with the Dial API, so a contract change arrives as a CLI release rather than breaking a request pinned in the adapter.

5. Build

Build first: it guards the adapter's typed core calls and proves the dependency is installed.

pnpm run build

6. Validate

Then run the one integration test.

pnpm exec vitest run src/channels/dial-registration.test.ts

dial-registration.test.ts imports the real channel barrel and asserts the registry contains dial — it goes red if the import line drifts. End-to-end SMS/voice is verified manually once the service runs.

Sign in to Dial

Install the CLI

Dial's CLI owns the account credential (an auth file it writes on sign-in), so the setup uses the dial CLI here. Ensure it's installed — this installs it if it's missing (for the full onboarding/auth reference, see the dial-cli skill or curl -fsSL https://getdial.ai/skills.md):

command -v dial || curl -fsSL https://getdial.ai/install | bash

Identify this install

Calls this setup makes to Dial identify the install. The dial CLI prepends DIAL_USER_AGENT to its own token, so the account's requests stay attributable to this NanoClaw install in Dial's server-side logs. Resolve the token once (nanoclaw/<version>; an unreadable package.json degrades to nanoclaw/unknown rather than blocking the install) and prefix every dial command below with it:

node -p "'nanoclaw/'+(require('./package.json').version||'unknown')" 2>/dev/null || echo nanoclaw/unknown

Pin the CLI path

Now pin the CLI's absolute path into .env. The adapter shells out to dial to register its inbound command target, and it runs inside the NanoClaw service, which does not inherit your interactive shell's PATH. The CLI usually lands in a version-manager bin directory (~/.nvm/versions/node/*/bin, ~/node/bin, …) that the service cannot see, so a bare dial fails with ENOENT, the command target is never registered, and the channel comes up connected but deaf — no inbound SMS or calls, with only a line in logs/nanoclaw.error.log to show for it. DIAL_CLI_PATH removes the guesswork; dial.ts already prefers it:

command -v dial

DIAL_CLI_PATH={{dial_cli_path}}

Check the sign-in

Check whether you're already signed in:

DIAL_USER_AGENT={{dial_ua}} dial doctor --json

Skip the reuse question when signed out

If you're not signed in, go straight to email verification — default the choice so the branch guard below stays single-valued:

echo switch

Read the account

If you are signed in, read which account (for the prompt below) and ask whether to reuse it or sign in as a different one (matches the old wizard's "Reuse this account?" prompt, with an explicit way to switch):

DIAL_USER_AGENT={{dial_ua}} dial doctor --json

You're already signed in to Dial as {{connected_email}}.

Reuse this Dial account, or sign in as a different one? (reuse/switch)

Reuse the account

Reuse — no verification needed; with no --code the command just (re)installs the NanoClaw agent skill:

DIAL_USER_AGENT={{dial_ua}} dial auth verify-otp --agent nanoclaw

Send the code

Switch (or not signed in) — verify an email with a one-time code. Collect the email:

What's your email? Dial sends a one-time code to verify it. By continuing you create a Dial account and agree to Dial's Terms of Service (https://getdial.ai/terms) and Privacy Policy (https://getdial.ai/privacy).

Send the code (--force re-sends even if a prior code is pending):

DIAL_USER_AGENT={{dial_ua}} dial auth login {{owner_email}} --force

Verify the code

Collect the code (resolves inline, right after the send above):

Enter the 6-digit code from your email

Verify it and provision your number (this also installs the NanoClaw agent skill):

DIAL_USER_AGENT={{dial_ua}} dial auth verify-otp --code {{otp}} --agent nanoclaw

Confirm the line

Confirm the account's number — this becomes the agent's public line (its platform_id):

DIAL_USER_AGENT={{dial_ua}} dial number list --json | jq -er '.numbers[0].number'

Your agent's Dial line is {{platform_id}}.

Set the inbound greeting

Set the line's inbound behavior — the system prompt the AI uses on calls into this number. Verification no longer takes an instruction, so a fresh number starts on Dial's default greeting until this runs:

DIAL_USER_AGENT={{dial_ua}} dial number set {{platform_id}} --inbound-instruction "You are a friendly AI receptionist answering calls to this number. Greet the caller, ask how you can help, and take a clear message — their name, number, and reason for calling — if you cannot help directly."

Pin the default sender

Make that line the CLI's default sender. Verification saves whichever number the account considers primary — the oldest one — while the line picked above is the newest (numbers[0]). On a single-number account those coincide, so nothing looks wrong; with two or more they diverge permanently, and every dial call / dial message that omits --from-number goes out from a number this install isn't listening on. Replies to it are dropped as no_agent_wired.

Rewriting phoneNumber/phoneNumberId in the auth file makes the no-flag path land on the wired line, so an agent that forgets the selector is still correct:

f="${XDG_DATA_HOME:-$HOME/.local/share}/dial/auth.v1.json"; i=$(DIAL_USER_AGENT={{dial_ua}} dial number list --json | jq -er --arg n '{{platform_id}}' '.numbers[]|select(.number==$n)|.id') && jq --arg n '{{platform_id}}' --arg i "$i" '.phoneNumber=$n|.phoneNumberId=$i' "$f" > "$f.new" && mv -f "$f.new" "$f" && chmod 600 "$f" && echo "default sender pinned to {{platform_id}}"

Choose who may text the line

A phone number is guessable, and whoever reaches the agent gets a turn with it — including its dial CLI, which is authenticated for the whole Dial account. An admitted stranger can ask the agent to list every SMS and call on the account, read call transcripts, or buy another number. Session isolation doesn't prevent this: the credential is the exposure, not the conversation.

So decide who gets in. owner is the safe default; pick public only if you want a line strangers can start conversations on (an inbound receptionist, or outbound sales where prospects text back):

Who may text this line — `owner` (only the phone you pair next; everyone else is refused) or `public` (anyone who knows the number reaches the agent)?

Your answer is written to the line's own unknown_sender_policy when the line is registered below, after the restart (ncl is socket-only, so it needs the service up). It lives in the database from then on — per line, so a second number added later carries its own answer — and the adapter never rewrites it.

Locked to you: only the phone you pair in a moment can reach the agent on {{platform_id}}. Anyone else who texts it is refused — including people your agent calls, so they can't reply by text. To open it later: `ncl messaging-groups update --id <id> --unknown-sender-policy public` (find the id with `ncl messaging-groups list`).

Open line: anyone who knows {{platform_id}} can text the agent and will get a reply. Each person gets their own conversation, but they all reach an agent holding your Dial account credentials — so don't hand out this number casually. To lock it to just you later: `ncl messaging-groups update --id <id> --unknown-sender-policy strict` (find the id with `ncl messaging-groups list`