Skip to content

    Arabic or English · ↑↓ to move · Enter to open · Esc to close

    العربية
    On this page

    Migrating from v1 to v2

    Move from per-number v1 keys and endpoints to v2 account keys, one REST surface and signed v2 webhooks — step by step.

    v1 keeps working, so you can move one call at a time. The message model is the same: the body you send to v1 POST /whatsapp/public/messages works on v2 POST /v2/messages once you add numberId.

    Authentication

    v1v2
    Keyv1One x-api-key per numberv2Account keys: Authorization: Bearer wsl_live_…
    Permissionsv1Fixed per numberv2Scopes, number restriction, IP allowlist, expiry, rotation
    Choosing the numberv1Implied by the keyv2numberId in the body / path

    Your v1 number key also works on the v2 message endpoints of its own number, so you can switch URLs first and keys later.

    Endpoints

    v1 (/api/v1/whatsapp/public/…)v2 (/api/v2/…)
    POST messages, message/send, media/send, interactive/sendv2 (/api/v2/…)POST /v2/messages
    POST media/uploadv2 (/api/v2/…)POST /v2/media
    POST messages/{id}/react · edit · deletev2 (/api/v2/…)POST /v2/messages/{id}/reactions · PATCH /v2/messages/{id} · DELETE /v2/messages/{id}
    GET interactions/{id}v2 (/api/v2/…)interactive.reply webhook · GET /v2/messages/{id}
    Dashboard onlyv2 (/api/v2/…)Numbers, campaigns, auto-replies, OTP, Number Shield, stats, groups, webhooks — all in v2

    Errors

    v1 answers { statusCode, code, message, … }; v2 answers { error: { code, message, details?, docsUrl, requestId } }. Codes keep their names where they exist in both. Read error.code.

    Webhooks

    v1 fieldv2
    messageIdv2data.messageId
    from / senderPhoneNumberv2data.from.phone (data.from.lid when WhatsApp hides the number)
    fromNamev2data.from.name
    messageTypev2data.type
    content / captionv2data.text / data.caption
    mediaUrlv2data.media.url (signed) / data.media.id
    latitude / longitudev2data.location.lat / .lng
    isGroup / groupIdv2data.chat.type / data.chat.groupId
    rawMessagev2removed

    Steps

    1. Create an account key with the scopes you need (Settings → API keys).
    2. Point your send calls to POST /v2/messages with numberId and an Idempotency-Key.
    3. Update your webhook handler to read the v2 envelope (verify the signature the same way), switch the number to webhook version 2, send a test event and watch the log.
    4. Replace polling with webhooks (message.status, campaign.status, number.status).
    5. Revoke the old number keys you no longer use.

    The v1 reference stays online.