> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the TypeScript SDK

> Install @polymorfa/sdk, pin the version, and make your first request.

`@polymorfa/sdk` is the Polymorfa server SDK for TypeScript and JavaScript. It
has no runtime dependencies and ships its own type definitions.

## Requirements

* Node.js 20 or later, or a server-side Cloudflare Worker, Deno, or Bun. The
  runtime must provide `fetch` and `crypto.subtle`.
* A team key (`pmfa_…`) or project credential (`pmfa_pt_…`). Create one under
  [API keys](https://docs.polymorfa.com/console/api-keys.md).

Keep keys on your server. Browser and mobile code uses a
[client token](https://docs.polymorfa.com/sdks/typescript/client.md#give-a-browser-a-client-token) instead.

## Install

```bash npm theme={null}
npm install --save-exact @polymorfa/sdk@dev
```

```bash pnpm theme={null}
pnpm add --save-exact @polymorfa/sdk@dev
```

```bash yarn theme={null}
yarn add --exact @polymorfa/sdk@dev
```

```bash bun theme={null}
bun add --exact @polymorfa/sdk@dev
```

The SDK is published as 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 each time a new prerelease is published. Read the
[version notes](https://docs.polymorfa.com/sdks/typescript/version-notes.md) before you upgrade.

## Make your first request

Store your key in the `POLYMORFA_KEY` environment variable, then list your
Numbers:

```typescript theme={null}
import { Client } from "@polymorfa/sdk";

const platform = new Client({
  credential: { type: "organizationApiKey", value: process.env.POLYMORFA_KEY! },
  apiVersion: "2026-09-22",
});

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

This call needs the `sessions:read` permission.

## Send a message

```typescript theme={null}
import { MessagingClient } from "@polymorfa/sdk";

const messaging = new MessagingClient({
  credential: { type: "apiKey", value: process.env.POLYMORFA_KEY! },
  apiVersion: "2026-09-22",
});

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

This call needs `messages:write`. The Number must be connected. See
[Send and receive messages](https://docs.polymorfa.com/sdks/typescript/messages.md) for media, templates, and
replies.

## Use an edge runtime

Import from the package root, `@polymorfa/sdk`, in Cloudflare Workers, Deno, and
Bun. Keep keys in the runtime's secret store, not in source code.

`@polymorfa/sdk/node` contains file download helpers that need Node.js. Do not
import it in edge code.

See [Verify a webhook](https://docs.polymorfa.com/sdks/typescript/webhooks.md#verify-a-webhook) for a Worker
that receives webhooks.

## Next steps

* [Create a client](https://docs.polymorfa.com/sdks/typescript/client.md): pick the right client and set
  timeouts, retries, and the API version.
* [Errors and retries](https://docs.polymorfa.com/sdks/typescript/errors.md): handle failures and read every
  page of a list.
* [Connect and manage Numbers](https://docs.polymorfa.com/sdks/typescript/numbers.md): connect a WhatsApp
  account with QuickLink.
* [Analytics](https://docs.polymorfa.com/sdks/typescript/analytics.md): read engagement, call outcomes and
  activity intervals, or export collector metrics.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.