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

# Quickstart

> Create a Polymorfa organization key, pair a WhatsApp session, send a message, and register a signed webhook.

## 1. Create your account and project

Open [Polymorfa](https://polymorfa.com), 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.

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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](/api/webhooks).

<Columns cols={2}>
  <Card title="Messaging API" icon="terminal" href="/api/overview">Browse every current messaging endpoint and type.</Card>
  <Card title="Platform API" icon="gear" href="/api/platform-api">Automate organization and project workflows.</Card>
  <Card title="Meta-compatible requests" icon="share-nodes" href="/api/messaging-api-compatibility">Migrate a Meta Cloud API client to the Messaging API.</Card>
  <Card title="Sandbox" icon="flask" href="/sandbox/quickstart">Test without real WhatsApp traffic.</Card>
</Columns>