Set up your development environment
Install the Polymorfa CLI and the TypeScript SDK, create a client, and set up Inspector and your coding agent.
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.
| Tool | Use it to |
|---|---|
| CLI | Send API requests, check your setup and forward events to a local handler |
| TypeScript SDK | Call the API from your server code with typed methods |
| Inspector | See and act on your Numbers as a WhatsApp client |
| Agent tools | Give your coding agent the Polymorfa skills and docs |
Install the CLI#
The CLI needs Node.js 22 or later.
npm install --global @polymorfa/cli@dev
polymorfa versionThe 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:
polymorfa auth loginOr set it for one shell session:
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.
polymorfa doctorThe 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 install --save-exact @polymorfa/sdk@devpnpm add --save-exact @polymorfa/sdk@devyarn add --exact @polymorfa/sdk@devbun add --exact @polymorfa/sdk@devThe 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 building | Install |
|---|---|
| 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.
| Client | Use it to |
|---|---|
Client | Manage your team and projects: Numbers, webhooks, events, operations, customers, campaigns, audiences, billing and call records |
MessagingClient | Act 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:
| Credential | Client | MessagingClient |
|---|---|---|
| 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:
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:
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:
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:
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:
| Option | Default | Effect |
|---|---|---|
apiVersion | 2026-09-22 | The API contract date, sent as Polymorfa-Version. It is separate from the package version. See API versioning |
timeoutMs | 30000 | Time limit for each attempt, in milliseconds |
maxNetworkRetries | 2 | Automatic retries for requests that are safe to repeat. See Retries in the SDK |
baseUrl | https://api.polymorfa.com | API host |
fetch | global fetch | A custom fetch implementation |
Every method takes an optional last argument with options for that request:
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" },
},
);| Option | Effect |
|---|---|
idempotencyKey | Sent as Idempotency-Key, so the SDK can retry a write without running it twice. See Idempotency |
timeoutMs | Overrides the client timeout for this request |
maxNetworkRetries | Overrides the client retry count for this request |
signal | Cancels the request. The SDK throws PolymorfaCancelledError |
headers | Adds request headers |
apiVersion | Overrides the client API version for this request |
Read a response #
Methods that return one result resolve to { data, metadata }:
const response = await messaging.sessions.retrieve("<number-id>");
console.log(response.data.data.status);
console.log(response.metadata.status, response.metadata.requestId);datais the parsed response body. Most bodies wrap the result in their owndatafield, so you readresponse.data.data. The return type gives each method's shape.metadataholds the HTTPstatus, therequestId, the resolvedapiVersion, the number ofattemptsand the responseheaders. IncluderequestIdwhen 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:
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.
| Language | HTTP client in the examples |
|---|---|
| Node.js | Built-in fetch, Node.js 20 or later |
| Ruby | Net::HTTP |
| Java | java.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():
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:
polymorfa agent setupSee 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.