Skip to content
Shortcut: /, ⌘K or Ctrl+K

Set up your development environment

Install the Polymorfa CLI and the TypeScript SDK, create a client, and set up Inspector and your coding agent.

View as Markdown

Set up the tools once, then use them across every project. You need a Polymorfa team and a credential: a project token for one project, or a team key for the whole team.

ToolUse it to
CLISend API requests, check your setup and forward events to a local handler
TypeScript SDKCall the API from your server code with typed methods
InspectorSee and act on your Numbers as a WhatsApp client
Agent toolsGive your coding agent the Polymorfa skills and docs

Install the CLI#

The CLI needs Node.js 22 or later.

Shell
npm install --global @polymorfa/cli@dev
polymorfa version

The CLI is a development prerelease. The dev tag installs the latest build, and commands, flags and output can change between builds. Pin an exact version, such as @polymorfa/cli@0.1.0-dev.0, in scripts.

Give the CLI a credential#

Store a team key or project token in your operating system's keyring:

Shell
polymorfa auth login

Or set it for one shell session:

Shell
export POLYMORFA_API_KEY="pmfa_pt_..."

Set only one credential variable at a time. See polymorfa auth for named profiles.

Check your setup#

polymorfa doctor checks your Node.js version, profile configuration, keyring access, API reachability and server API key authentication. The output never includes credential values.

Shell
polymorfa doctor

The command exits 0 when every required check passes and 1 when a check fails or is skipped. A project or client token is reported as present, but doctor can't validate it remotely, so the command exits 1. That doesn't mean the token is invalid; use a team key to check authentication. See Check your CLI setup.

Forward events to a local handler#

polymorfa listen receives your project's events and can forward each one to a handler on your machine, so you can develop webhook code without a public URL. See Forward events to a local handler.

Install the TypeScript SDK #

@polymorfa/sdk is the server SDK for TypeScript and JavaScript. It has no runtime dependencies and ships its own type definitions. It runs on Node.js 20 or later, and in server-side Cloudflare Workers, Deno and Bun. The runtime must provide fetch and crypto.subtle.

npm
npm install --save-exact @polymorfa/sdk@dev
pnpm
pnpm add --save-exact @polymorfa/sdk@dev
yarn
yarn add --exact @polymorfa/sdk@dev
bun
bun add --exact @polymorfa/sdk@dev

The SDK is a development prerelease under the dev tag; there is no stable release yet. The exact-version flag records the resolved version, such as 0.1.0-dev.20261001215108, so every install gets the same code. Commit your lockfile. The dev tag moves with each prerelease, so read the SDK version notes before you upgrade.

You are buildingInstall
Server code in Node.js 20+, Cloudflare Workers, Deno or Bun@polymorfa/sdk
A server process that speaks on calls, such as a voice agent@polymorfa/sdk, imported from @polymorfa/sdk/calls. See Speak on calls from your server
Calling in the browser@polymorfa/browser, with @polymorfa/react or @polymorfa/elements for the interface. See Calls in the browser
Inbox, chat and connect components in your web app@polymorfa/react or @polymorfa/elements. See UI Kit

Use the HTTP API when your language or operation is not covered by your installed package. Every method in the API reference shows its request in cURL. See Use another language.

Moving an integration written for Meta's Cloud API? Point it at the Graph API: change the base URL to https://api.polymorfa.com/graph/whatsapp/v26.0 and send a Polymorfa team key or project token in place of the Meta access token. Request bodies, responses and errors keep Meta's shape.

Create a client #

The SDK has two clients. Most integrations create both with the same key.

ClientUse it to
ClientManage your team and projects: Numbers, webhooks, events, operations, customers, campaigns, audiences, billing and call records
MessagingClientAct through a Number: send messages, connect Numbers with QuickLink, manage templates, run campaigns by project slug and control calls

Both clients accept a team key or a project token:

CredentialClientMessagingClient
Team key{ type: "organizationApiKey" }{ type: "apiKey" }
Project token{ type: "projectToken" } plus projectId{ type: "projectToken" }

A key reaches only what its permissions allow, and each method's reference page lists the permission it needs. Pass the whole credential from the Console; never parse it or assume a length. See API keys.

The SDK examples in these docs use three clients named platform, project and messaging:

TypeScript
import { Client, MessagingClient } from "@polymorfa/sdk";

// The whole team. Methods that act on one project take a `projectId`.
const platform = new Client({
  credential: { type: "organizationApiKey", value: process.env.POLYMORFA_KEY! },
  apiVersion: "2026-09-22",
});

// One project: events, webhooks, webhook deliveries, operations, flows,
// SIP trunks, calls, QuickLink settings, Number defaults, usage and call retention.
const project = platform.project("<project-id>");

// Act through a Number: every method takes the Number ID first.
const messaging = new MessagingClient({
  credential: { type: "apiKey", value: process.env.POLYMORFA_KEY! },
  apiVersion: "2026-09-22",
});

Team resources such as projects, members, billing, customers and campaigns stay on the team client. With a project token, create the project client directly; the API checks that the token belongs to that project:

TypeScript
const project = new Client({
  credential: { type: "projectToken", value: process.env.POLYMORFA_KEY! },
  projectId: "<project-id>",
  apiVersion: "2026-09-22",
});

Keep keys on your server. Browser and mobile code uses a short-lived client token instead.

Make your first request #

Store your key in the POLYMORFA_KEY environment variable, then list your Numbers. This needs the sessions:read permission:

TypeScript
const numbers = await platform.sessions.list();
for (const number of numbers.data.data) {
  console.log(number.sessionId, number.name, number.status);
}

Then send a message from a connected Number. This needs messages:write:

TypeScript
const sent = await messaging.messages.send("<number-id>", {
  conversation: { phoneNumber: "+15550001111" },
  content: { text: "Hello from Polymorfa" },
});
console.log(sent.data.data.id);

See Send messages for media, templates and replies.

Set client and request options #

Both clients accept these options:

OptionDefaultEffect
apiVersion2026-09-22The API contract date, sent as Polymorfa-Version. It is separate from the package version. See API versioning
timeoutMs30000Time limit for each attempt, in milliseconds
maxNetworkRetries2Automatic retries for requests that are safe to repeat. See Retries in the SDK
baseUrlhttps://api.polymorfa.comAPI host
fetchglobal fetchA custom fetch implementation

Every method takes an optional last argument with options for that request:

TypeScript
const controller = new AbortController();

const sent = await messaging.messages.send(
  "<number-id>",
  { conversation: { phoneNumber: "+15550001111" }, content: { text: "Your order shipped" } },
  {
    idempotencyKey: "order-1042-shipped",
    timeoutMs: 10_000,
    maxNetworkRetries: 3,
    signal: controller.signal,
    headers: { "x-correlation-id": "order-1042" },
  },
);
OptionEffect
idempotencyKeySent as Idempotency-Key, so the SDK can retry a write without running it twice. See Idempotency
timeoutMsOverrides the client timeout for this request
maxNetworkRetriesOverrides the client retry count for this request
signalCancels the request. The SDK throws PolymorfaCancelledError
headersAdds request headers
apiVersionOverrides the client API version for this request

Read a response #

Methods that return one result resolve to { data, metadata }:

TypeScript
const response = await messaging.sessions.retrieve("<number-id>");

console.log(response.data.data.status);
console.log(response.metadata.status, response.metadata.requestId);
  • data is the parsed response body. Most bodies wrap the result in their own data field, so you read response.data.data. The return type gives each method's shape.
  • metadata holds the HTTP status, the requestId, the resolved apiVersion, the number of attempts and the response headers. Include requestId when you contact support.

Lists of events, webhooks, deliveries, operations, call records and call opt-outs return a page object. See Read every page in the SDK.

Call an endpoint without an SDK method #

raw.request sends an authenticated request to any API path with the client's credential, API version, timeout and retry settings. A project client confines it to its own project. Use it for routes your installed package has no typed method for yet:

TypeScript
const updated = await platform.raw.request<{ data: unknown }>({
  method: "PATCH",
  path: "/messaging/projects/<project-slug>/campaigns/<campaign-id>",
  body: { name: "October launch" },
});
console.log(updated.metadata.status, updated.data);

Use another language #

TypeScript is the only language with a published Polymorfa SDK. The API reference shows every request in cURL.

In a guide, a code example with a cURL request also offers these languages in its language selector. Each shows the same HTTP request, written with the language's usual HTTP client, and reads your credential and IDs from environment variables such as POLYMORFA_KEY.

LanguageHTTP client in the examples
Node.jsBuilt-in fetch, Node.js 20 or later
RubyNet::HTTP
Javajava.net.http, Java 17 or later

Each of these is a complete program that prints the response status and body.

For Python, Go, PHP, C# and Rust, a guide shows a written example where it has one. Otherwise it says that no checked program exists and links to the cURL request, which you can send with your language's HTTP client. To check webhook signatures, see Verify a webhook.

Use an edge runtime#

Import from the package root, @polymorfa/sdk, in Cloudflare Workers, Deno and Bun, and keep keys in the runtime's secret store. @polymorfa/sdk/node holds file download helpers that need Node.js; do not import it in edge code. See Verify a webhook for a Worker that receives webhooks.

Check API status#

SystemClient needs no credential, so you can use it in health checks. It also has status(), health() and ping():

TypeScript
import { SystemClient } from "@polymorfa/sdk";

const system = new SystemClient();
const version = await system.version();
console.log(version.data.apiVersion, version.data.minSupportedVersion);

Install Inspector#

Polymorfa Inspector is a desktop app for macOS, Windows and Linux. It opens your real and test Numbers so you can watch messages arrive and reply by hand. Inspector requires access. Download it from polymorfa.com/inspector/install, then see Install Inspector to verify the download and authorize the app.

Set up your coding agent#

Install the Polymorfa skills and the docs MCP server for your coding agent. With the CLI installed, one command detects your agents:

Shell
polymorfa agent setup

See Install the agent tools for Claude Code, Codex, Cursor, Gemini and skills-only installs.

The docs MCP server at https://docs.polymorfa.com/mcp gives any MCP client read-only search over these docs. It needs no credential. See Docs MCP server.

Next steps#