Upgrade your integration
Pin the API version your code expects and move to a newer one safely.
Every Messaging and Platform request runs against a dated API version. Pin the version your code was written for, so a new version never changes a response under you, and move to a newer version on your own schedule.
| Version | |
|---|---|
| Current | 2026-09-22 |
| Minimum supported | 2026-09-22 |
2026-09-22 is the only supported version. 2026-03-20 was retired on October 19, 2026.
Pin the version#
Send the version in the Polymorfa-Version header on every request. Without the header, Polymorfa uses the current version, so your integration changes behavior when a new version becomes current.
API
curl https://api.polymorfa.com/platform/sessions \
-H "Authorization: Bearer $POLYMORFA_KEY" \
-H "Polymorfa-Version: 2026-09-22"import { Client } from "@polymorfa/sdk";
const platform = new Client({
credential: { type: "organizationApiKey", value: process.env.POLYMORFA_KEY! },
apiVersion: "2026-09-22",
});
// One request at another version; the response metadata has the version applied.
const numbers = await platform.sessions.list(undefined, { apiVersion: "2026-09-22" });
console.log(numbers.metadata.apiVersion);# The Graph API takes its version in the URL, not in Polymorfa-Version.
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/$WABA_ID/phone_numbers" \
-H "Authorization: Bearer $POLYMORFA_KEY"The response repeats the version it applied in its own Polymorfa-Version header. Log it to confirm what your integration runs against.
TypeScript:
Without apiVersion, the TypeScript SDK sends the version it was built for, 2026-09-22 in current releases. Set it explicitly so an SDK update does not change your API version. You can also pass apiVersion on a single request.
CLI
polymorfa api /platform/sessions --api-version 2026-09-22Every CLI command accepts --api-version to override the version for that command.
Graph requests do not use Polymorfa-Version. They take a Meta-style version in the URL, such as /graph/whatsapp/v26.0. See Graph API versions.
Watch for deprecation#
When you send a version that is still supported but older than the current one, the response can include:
Polymorfa-Deprecation-Warning, describing the change;Sunset, the date the version stops working; andLinkwithrel="sunset", pointing to upgrade guidance.
Log these headers and alert on them. After the sunset date, the version is below the minimum and requests return 400 invalid_parameter with error.param: Polymorfa-Version, Deprecation: true and a Link with rel="deprecation". See API versioning.
Upgrade to a newer version#
Read what changed
Read the changelog entries tagged API between your version and the target version. Each entry says who is affected and whether you need to act.
Update your SDK
Install the SDK release that supports the target version. Read its version notes for changes to methods and types.
Test with the new version
Send the new
Polymorfa-Versionfrom a test environment, against a test number where you can. Check the requests and event handlers that the changelog entries affect.Switch production
Change the pinned version in production. Watch your error rate and the request logs for
400and new error codes.
Roll back by sending the previous version, as long as it is still supported.
SDK version notes #
@polymorfa/sdk is a development prerelease, and a prerelease can change a method or a response shape. These are the changes that need action when you upgrade, newest first. Each version is named 0.1.0-dev.<timestamp>, so you can compare yours with the dates below. Check the installed version with npm ls @polymorfa/sdk, or read the SDK_VERSION export.
November 12, 2026#
Organization is now team#
Every SDK name that said organization now says team, with no aliases:
| Before | After |
|---|---|
{ type: "organizationApiKey" } | { type: "teamApiKey" } |
credentialKind: "organization_api_key" | credentialKind: "team_api_key" |
OrganizationClient | TeamClient |
client.organizations.* | client.teams.* |
orgId, organizationId fields | teamId |
Rename these in your code when you install a release from this date or later.
October 5, 2026#
Campaign content and sequences#
From 0.1.0-dev.20261005230914, campaign create and update requests accept variableMapping and trackedLinks, messaging.campaigns.update accepts templateId, platform.campaigns.create and update type messagesArray as CampaignMessage[], and LaunchCampaignRequest accepts skipMissingVariables. Campaign records include trackedLinks, and campaign recipients include messagesSent, nextMessageAt and sequenceError. The version also adds messaging.campaigns.update, reschedule and exportRecipients, and platform.audiences.createFromCampaign. If your code builds Campaign or CampaignRecipient objects, add the new fields. See Campaigns.
STOP confirmations#
From 0.1.0-dev.20261005233122, organization clients expose optOuts.getConfirmationSettings, updateConfirmationSettings and getConfirmationSummary.
October 1, 2026#
Flow drafts return the draft in response.data#
From 0.1.0-dev.20261001124422, flows.list and flows.retrieve return the drafts directly in response.data.
0.1.0-dev.20260926213449 through 0.1.0-dev.20260927174827 returned them in response.data.data. Replace response.data.data with response.data when you upgrade. See Flows.
Campaign send windows#
From 0.1.0-dev.20261001124422, messaging.campaigns.create, platform.campaigns.create, and platform.campaigns.update accept sendWindow, and campaign records include it. The SDK exports CampaignSendWindowRequest and CampaignSendWindow. See Campaigns.
September 26, 2026#
Flow draft reads#
0.1.0-dev.20260926213449 added flows.list and flows.retrieve on project clients.
September 22, 2026#
whatsapp_ids replaces whatsapp_id#
API version 2026-09-22 returns WhatsApp message references in whatsapp_ids, under linked_devices, official_api, or both. SDK message receipts and webhook types include it. The singular whatsapp_id field is deprecated and remains only while older API versions are supported. Read whatsapp_ids in new code. See Message IDs.
September 20, 2026#
Operations#
The SDK added operations.list, get, listTransitions, wait, and cancel. See Events and operations.
September 2026#
Number tier changes use a quote#
sessions.setTierOverride(sessionId, { tierOverride }) was replaced by a quote and a confirmation. Call sessions.quoteTierChange, show the quote, then pass its ID as setTierOverride(sessionId, { quoteId }). Read the result with sessions.retrieveTierChange. See Change a Number's tier.
Balance warning settings removed#
billing.updateReminderSettings was removed, and billing responses no longer include lowBalanceThresholdCents or reminderChannels. Configure balance warnings in the Console under My notifications.
Credit amounts in balances, usage, and BanSafe claims can have up to six decimal places, including fields whose names end in Cents. Do not parse them as integers.
QuickLink replaces direct Number creation#
sessions.create and sessions.createTesting were removed. Create Numbers with messaging.quickLinks.create. Number settings changes use sessions.update with a revision and configuration.set or configuration.reset. See Connect and manage Numbers.
The browser widget.start and widget.status helpers were also removed.
Webhooks and events#
Webhook endpoints and event streams do not have their own API version. Event payloads follow the current contract. When a field is replaced, Polymorfa sends the earlier field alongside the new one during the migration window: for example, native message events carry both whatsapp_ids and the earlier whatsapp_id. Read the new field, and make your handler ignore fields and event types it does not know.
Meta-format webhooks keep Meta's envelope and are not affected by Polymorfa-Version.