Quickstart

1. Create your account and project

Open Polymorfa, sign up with email OTP, passkey, or an enabled social provider, then complete team and project setup. Save the project ID shown in the Console.

export POLYMORFA_BASE_URL="https://api.polymorfa.com"
export POLYMORFA_PROJECT_ID="replace-with-project-id"

2. Create an organization key

In Console → Team → API keys, create an organization key with the narrowest scopes for the task. This quickstart needs sessions:manage, sessions:read, messages:write, and webhooks:manage. A project token can call Messaging API operations allowed by its scopes and owning project, but public /v1/* Platform API operations reject project tokens.

export TITAN_KEY="titan_REPLACE_ME"

Organization keys retain the titan_ prefix. The secret is shown once.

3. Create and pair a session

You can create a session in the Console or through the Messaging API:

curl -X POST "$POLYMORFA_BASE_URL/api/sessions" \
  -H "Authorization: Bearer $TITAN_KEY" \
  -H "Titan-Version: 2026-03-20" \
  -H "Content-Type: application/json" \
  -d "{\"projectId\":\"$POLYMORFA_PROJECT_ID\",\"name\":\"Sales line\",\"start\":true}"

Save the returned canonical sessionId. It is the {session} value in all session-scoped paths.

export POLYMORFA_SESSION="sess_replace_me"

curl "$POLYMORFA_BASE_URL/api/$POLYMORFA_SESSION/pair/qr" \
  -H "Authorization: Bearer $TITAN_KEY"

The response contains a qr string. Encode that string as a QR image and scan it in WhatsApp under Linked devices. Alternatively, request a pairing code with POST /api/{session}/pair/code and a JSON body containing the E.164 phone value.

4. Send a message

curl -X POST "$POLYMORFA_BASE_URL/api/$POLYMORFA_SESSION/messages/send" \
  -H "Authorization: Bearer $TITAN_KEY" \
  -H "Titan-Version: 2026-03-20" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999@s.whatsapp.net",
    "type": "text",
    "text": "Hello from Polymorfa"
  }'

The request schema also supports image, file, voice, video, poll, location, and contact messages. See the generated sendMessage endpoint for the exact required fields per type.

5. Register a signed webhook

curl -X POST "$POLYMORFA_BASE_URL/api/webhooks" \
  -H "Authorization: Bearer $TITAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/polymorfa/webhook",
    "events": ["message.received", "message.ack", "session.status"],
    "hmacKey": "replace-with-a-random-secret",
    "format": "native"
  }'

Verify X-Webhook-Signature over the raw body before processing. For a Meta-compatible consumer, set format to meta and verify X-Hub-Signature-256 instead. See Webhooks.

Messaging API

Browse every current messaging endpoint and type.

Platform API

Automate organization and project workflows.

Meta-compatible requests

Migrate a Meta Cloud API client to the Messaging API.

Sandbox

Test without real WhatsApp traffic.

Get started

Console

Inspector

Sandbox

Integrations

1. Create your account and project

2. Create an organization key

3. Create and pair a session

4. Send a message

5. Register a signed webhook

Messaging API

Platform API

Meta-compatible requests

Sandbox

​1. Create your account and project

​2. Create an organization key

​3. Create and pair a session

​4. Send a message

​5. Register a signed webhook

Messaging API

Platform API

Meta-compatible requests

Sandbox

1. Create your account and project

2. Create an organization key

3. Create and pair a session

4. Send a message

5. Register a signed webhook