Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,15 @@

## Unreleased

- Rename WhatsApp account inputs, lookups and state triggers to Connections on
n8n, Make, Zapier and Pipedream, including recipes and generated interfaces.
- Use `connection` event envelopes, `connection.*` lifecycle events,
`connections:read` and `/platform/connections`. Retired account names have no aliases.
- Keep opaque IDs, destination phone numbers, write idempotency and owned webhook
cleanup unchanged. This source candidate is not provider publication or acceptance.

## Unreleased

- Separate webhook receiver secrets from public marker/idempotency metadata.
- Remove the Webhook Creation Key field from all triggers. Each activation uses
its own adapter-generated nonce, so off/on, n8n test listening and Pipedream
Expand Down
22 changes: 22 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,12 @@ has been published, approved or listed in a provider's marketplace. Provider
release evidence is recorded in `releases/`.

The integrations follow the same public API contract as the Polymorfa SDKs.
Actions select the WhatsApp account with `connection`. Connection lookup uses
`/platform/connections` and `connections:read`; state triggers receive
`connection.status`, `connection.connected` and `connection.logged_out` in a
`connection` envelope. IDs stay strings. Credential connections in each workflow
platform still hold that platform's authentication settings.

They use each platform's own request and credential APIs. No integration builds
a separate workflow engine or stores your third-party app connections.

Expand All @@ -31,3 +37,19 @@ record the remaining native acceptance and publication work.

License: MIT. Newly authored connector code only; no archived Titan adapter code
is included.


Connection names use the public 1-to-64-character selector format, including
names such as `sales.eu`. Messaging retries stop at 55 minutes, before the API's
one-hour receipt expires. Preserve the original write key and start time when
reconciling an uncertain result.

Trigger cleanup may remove an exactly owned pre-rename webhook. It does not
register or emit retired event names. Cleanup checks the saved marker against
the live project, callback and event filters, including after token rotation.
An unresolved activation keeps its nonce and start time. After its creation
receipt expires, activating again only looks for the existing owned webhook.
If found, it records that webhook without another POST; it can then be
deactivated normally. Missing, changed or ambiguous inventory stays blocked for
reconciliation. A changed target never starts another creation. These source
changes do not establish provider publication or installed-platform acceptance.
12 changes: 6 additions & 6 deletions contracts/coverage.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,15 @@
"sendMessage": {
"contract": "messaging",
"method": "POST",
"path": "/messaging/{session}/messages/send",
"path": "/messaging/{connection}/messages/send",
"scope": "messages:write",
"sdkOperation": "sendMessage",
"purpose": "action"
},
"sendReaction": {
"contract": "messaging",
"method": "POST",
"path": "/messaging/{session}/messages/react",
"path": "/messaging/{connection}/messages/react",
"scope": "messages:write",
"sdkOperation": "sendReaction",
"purpose": "action"
Expand All @@ -32,12 +32,12 @@
"sdkOperation": "getProjectTemplate",
"purpose": "action"
},
"listPlatformSessions": {
"listPlatformConnections": {
"contract": "platform",
"method": "GET",
"path": "/platform/sessions",
"scope": "sessions:read",
"sdkOperation": "listPlatformSessions",
"path": "/platform/connections",
"scope": "connections:read",
"sdkOperation": "listPlatformConnections",
"purpose": "action"
},
"listProjectWebhooks": {
Expand Down
4,391 changes: 2,871 additions & 1,520 deletions contracts/openapi.messaging.json

Large diffs are not rendered by default.

125 changes: 101 additions & 24 deletions contracts/openapi.platform.json
Original file line number Diff line number Diff line change
@@ -1,29 +1,30 @@
{
"openapi": "3.0.3",
"info": {
"title": "Polymorfa automation platform",
"version": "2026-09-22"
"title": "Polymorfa Platform API",
"version": "1.0.0",
"description": "Manage your team, projects, connections, and webhooks.\n\nAuthenticate with a team API key or a project token with the permissions required by the method."
},
"servers": [
{
"url": "https://api.polymorfa.com"
}
],
"paths": {
"/platform/sessions": {
"/platform/connections": {
"get": {
"operationId": "listPlatformSessions",
"operationId": "listPlatformConnections",
"tags": [
"sessions"
"connections"
],
"summary": "List sessions",
"description": "Lists sessions in the authenticated team or selected project, including disconnected sessions and their latest status reason. A Test key returns only test numbers in its project, or an empty list when there are none. Other project tokens return all sessions in their own project.\n\nRequires `sessions:read`. Project tokens only access resources in their own project.",
"summary": "List connections",
"description": "Lists connections in the authenticated team or selected project, including disconnected connections and their latest status reason. A Test key returns only test connections in its project, or an empty list when there are none. Other project tokens return all connections in their own project.\n\nRequires `connections:read`. Project tokens only access resources in their own project.",
"x-audience": "public",
"x-polymorfa-resource-boundary": "project",
"x-excluded-from-public": false,
"x-required-scope": "sessions:read",
"x-required-scope": "connections:read",
"x-merged-endpoints": [
"listSessionsByOrganization"
"listConnectionsByTeam"
],
"security": [
{
Expand Down Expand Up @@ -73,7 +74,7 @@
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PlatformSession"
"$ref": "#/components/schemas/PlatformConnection"
}
}
},
Expand Down Expand Up @@ -325,6 +326,9 @@
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/IdempotencyKeyReused"
}
}
}
Expand Down Expand Up @@ -522,14 +526,17 @@
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/IdempotencyKeyReused"
}
}
}
}
},
"components": {
"schemas": {
"PlatformSession": {
"PlatformConnection": {
"type": "object",
"additionalProperties": false,
"properties": {
Expand All @@ -544,8 +551,8 @@
"projectId": {
"$ref": "#/components/schemas/ProjectId"
},
"sessionId": {
"$ref": "#/components/schemas/SessionIdentifier"
"connectionId": {
"$ref": "#/components/schemas/ConnectionIdentifier"
},
"name": {
"type": "string",
Expand Down Expand Up @@ -578,12 +585,12 @@
},
"status": {
"type": "string",
"description": "Latest runtime connection status."
"description": "Latest runtime method status."
},
"statusReason": {
"type": "string",
"nullable": true,
"description": "Machine-readable reason for the latest connection status, when available."
"description": "Machine-readable reason for the latest method status, when available."
},
"messageCount": {
"type": "integer",
Expand Down Expand Up @@ -672,13 +679,25 @@
]
}
]
},
"inspector": {
"type": "object",
"additionalProperties": false,
"properties": {
"claim": {
"$ref": "#/components/schemas/InspectorClaimState"
}
},
"required": [
"claim"
]
}
},
"required": [
"_id",
"_creationTime",
"projectId",
"sessionId",
"connectionId",
"name",
"phone",
"platform",
Expand All @@ -691,19 +710,40 @@
"lastActiveAt",
"paidUntil",
"customer",
"claim"
"claim",
"inspector"
]
},
"ProjectId": {
"type": "string",
"format": "uuid",
"description": "Project UUID. Optional where an operation can infer or search team scope; required where the operation creates a project-owned resource."
},
"SessionIdentifier": {
"ConnectionIdentifier": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"description": "Database session UUID or stable session slug."
"description": "Database connection UUID or stable connection slug."
},
"InspectorClaimState": {
"type": "object",
"additionalProperties": false,
"description": "Whether a team member has claimed this Connection in Inspector. The claimant's identity is not included.",
"properties": {
"claimed": {
"type": "boolean"
},
"claimedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the current claim was made. Null when unclaimed."
}
},
"required": [
"claimed",
"claimedAt"
]
},
"ErrorEnvelope": {
"type": "object",
Expand Down Expand Up @@ -756,7 +796,7 @@
"request_log_url": {
"type": "string",
"format": "uri",
"description": "Console page that shows this request. Returned only to organization and project credentials whose request was logged."
"description": "Console page that shows this request. Returned only to team and project credentials whose request was logged."
}
}
},
Expand All @@ -783,7 +823,7 @@
"type": "string",
"format": "uuid"
},
"organizationId": {
"teamId": {
"type": "string",
"format": "uuid"
},
Expand Down Expand Up @@ -830,7 +870,7 @@
"type": "integer",
"minimum": 7,
"maximum": 13,
"description": "First day without the phone on which this endpoint receives session.phone_offline."
"description": "First day without the phone on which this endpoint receives connection.phone_offline."
},
"headers": {
"type": "array",
Expand All @@ -853,7 +893,7 @@
},
"required": [
"id",
"organizationId",
"teamId",
"owner",
"projectId",
"url",
Expand Down Expand Up @@ -994,7 +1034,7 @@
"minimum": 7,
"maximum": 13,
"default": 10,
"description": "First day without the phone on which this endpoint receives session.phone_offline. WhatsApp signs the linked device out on day 14. On PATCH, omission preserves the stored value. To stop the warning, remove session.phone_offline from eventTypes."
"description": "First day without the phone on which this endpoint receives connection.phone_offline. WhatsApp signs the linked device out on day 14. On PATCH, omission preserves the stored value. To stop the warning, remove connection.phone_offline from eventTypes."
},
"headers": {
"type": "array",
Expand Down Expand Up @@ -1324,6 +1364,43 @@
}
}
}
},
"IdempotencyKeyReused": {
"description": "The Idempotency-Key was already used for a different request (`idempotency_conflict`).",
"headers": {
"X-Request-Id": {
"schema": {
"type": "string"
},
"description": "Stable request correlation identifier."
},
"X-Trace-Id": {
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{32}$"
},
"description": "W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one."
},
"Polymorfa-Version": {
"schema": {
"type": "string"
},
"description": "API version applied to this response."
},
"Link": {
"description": "Documentation for this Idempotency-Key error (`rel=\"describedby\"`).",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
Expand Down
Loading
Loading