Get started

Using Dial from an agent

View as Markdown

Dial is built for AI agents. There are a few ways to wire it in, and you can mix them in the same project.

CLI shell-out

If your agent can run shell commands (for example, a coding agent), call the dial CLI. Every command accepts --json, so the agent gets structured output it can parse instead of prose.

$dial message --to +14155550123 --body "Your code is 123456" --json
1{ "ok": true, "message": { "id": "msg_...", "status": "queued" } }

Why this works well for agents:

  • --json on every command — machine-readable results, no scraping.
  • Stable exit codes — non-zero means failure, so the agent can branch on success.
  • Blocking waits — dial wait-for <event-type> blocks until a matching event arrives (see Receive an SMS).
  • Background capture — the listen service records events to a local log the agent can tail.

In-process SDK

If your agent is written in code, import an SDK and call it directly.

1import { DialClient } from "@getdial/sdk";
2
3const dial = new DialClient({ apiKey: process.env.DIAL_API_KEY! });
4await dial.sendMessage({ to: "+14155550123", fromNumberId, body: "Hi" });

Remote MCP

If your agent speaks the Model Context Protocol, it can skip the CLI and the SDK entirely. Point it at Dial’s Remote MCP server at https://getdial.ai/mcp and authorize once in the browser — no API key handling, no local install. The agent then calls Dial’s capabilities as MCP tools (send_message, place_call, wait_for_event, …) that mirror the CLI commands.

Which should I use?

CLIRemote MCPSDK
Best whenYour agent runs shell commandsYour agent speaks MCP (Claude.ai, Claude Desktop, Cursor, ChatGPT)Your agent is written in Node or Python
SetupInstall dial, onboard onceAdd one URL, authorize in the browserInstall a package, set an API key
AuthLocal API key (auth.v1.json)OAuth 2.1 in the browser — no key handlingAPI key in code
Install footprintLocal binary on the machineZero install (hosted)Package dependency
Output shape--json + stable exit codesMCP tool resultsTyped return values
Waiting for eventsdial wait-for + the listen servicewait_for_event tool (long-poll)Async generators
Runs off the machineNo — local to the machineYes — hostedYes — wherever your code runs

On a machine that already has the CLI, dial mcp also exposes every command as a local MCP server (stdio, reusing the saved key) — see MCP. It’s the same tool surface as the Remote MCP plus enhanced inbound capabilities (a persistent listener, local event fan-out) and onboarding.

All of these call the same REST API and use the same API key.