# 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](https://docs.polymorfa.com/development/api-keys) 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.

```bash
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:

```bash
polymorfa auth login
```

Or set it for one shell session:

```bash
export POLYMORFA_API_KEY="pmfa_pt_..."
```

Set only one credential variable at a time. See
[`polymorfa auth`](https://docs.polymorfa.com/cli) 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.

```bash
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](https://docs.polymorfa.com/development/cli#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](https://docs.polymorfa.com/development/cli#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`.

```bash npm
npm install --save-exact @polymorfa/sdk@dev
```

```bash pnpm
pnpm add --save-exact @polymorfa/sdk@dev
```

```bash yarn
yarn add --exact @polymorfa/sdk@dev
```

```bash 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](https://docs.polymorfa.com/development/upgrades#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](https://docs.polymorfa.com/calls/server) |
| Calling in the browser | `@polymorfa/browser`, with `@polymorfa/react` or `@polymorfa/elements` for the interface. See [Calls in the browser](https://docs.polymorfa.com/calls/web) |
| Inbox, chat and connect components in your web app | `@polymorfa/react` or `@polymorfa/elements`. See [UI Kit](https://docs.polymorfa.com/ui-kit) |

Use the HTTP API when your language or operation is not covered by your
installed package. Every method in the [API reference](https://docs.polymorfa.com/api) shows
its request in cURL. See [Use another language](#other-languages).

Moving an integration written for Meta's Cloud API? Point it at the
[Graph API](https://docs.polymorfa.com/api/graph): 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](https://docs.polymorfa.com/development/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](https://docs.polymorfa.com/development/client-tokens) 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](https://docs.polymorfa.com/messaging/send) 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](https://docs.polymorfa.com/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](https://docs.polymorfa.com/development/error-handling#sdk-retries) |
| `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:

```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" },
  },
);
```

| Option | Effect |
| --- | --- |
| `idempotencyKey` | Sent as `Idempotency-Key`, so the SDK can retry a write without running it twice. See [Idempotency](https://docs.polymorfa.com/development/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 }`:

```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](https://docs.polymorfa.com/api/pagination#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`.

| 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](https://docs.polymorfa.com/development/webhooks#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](https://docs.polymorfa.com/development/webhooks#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](https://www.polymorfa.com/inspector/install),
then see [Install Inspector](https://docs.polymorfa.com/testing/inspector/install) to verify the download
and authorize the app.

> **Warning**
>
> Inspector acts as the real WhatsApp account when you open a real Number.
> Messages you send from it reach real people.

## 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:

```bash
polymorfa agent setup
```

See [Install the agent tools](https://docs.polymorfa.com/agent-setup/prompt#install-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](https://docs.polymorfa.com/development/mcp#docs-mcp).

## Next steps

- **[Send your first message](https://docs.polymorfa.com/get-started/quickstart)**
Connect a test number, send a message and receive its events.

- **[CLI reference](https://docs.polymorfa.com/cli)**
Browse every command, flag and example.

- **[Testing](https://docs.polymorfa.com/testing)**
Build against test numbers before you use real ones.

- **[Integration checklist](https://docs.polymorfa.com/get-started/checklist)**
Check your integration before you send real traffic.
