Migrating v2 to v3

v3 is additive. It registers the same route inventory as v2 in the same order, and preserves the v2 request and response contract for every endpoint. In practice a migration is a base URL change plus optional adoption of the new capability.

Step 1: Change the Base URL

- https://graph.whats91.com/api/v2
+ https://graph.whats91.com/api/v3

Tokens, sender resolution, number scoping, rate limits, blacklist checks, billing checks, and response headers behave identically. No token needs to be regenerated.

Step 2: Expect the New apiVersion Value

Responses report metadata.apiVersion: "v3". If your code asserts on this value, update the assertion.

{
  "metadata": {
    "apiVersion": "v3",
    "requestId": "request-uuid",
    "processingTimeMs": 120
  }
}

Step 3: Tolerate Additive Response Fields

v3 adds read-only fields to existing responses. Strict schema validators that reject unknown properties must be relaxed before switching.

Step 4: Adopt New Capability (Optional)

One Behavioural Difference to Know

POST /api/v3/send rejects Direct Send fields with HTTP 400 and error code DIRECT_SEND_NOT_SUPPORTED_ON_TEMPLATE_SEND. This only affects requests that send Direct Send fields to the approved-template endpoint, which is not valid on v2 either.

What Does Not Change

• Authentication: the same bearer tokens and the same compatibility fallbacks.
• Route inventory: v3 has no endpoint that does not exist in v2.
• Webhook destinations, event keys, signing, and delivery behaviour.
• Rate limits, error envelope, error codes, and response headers.
• Billing, blacklist, reconnect-queue, and reporting behaviour for non-Direct-Send traffic.

Rollback

Because v3 is additive, rollback is the reverse base URL change. v1 and v2 are frozen and unaffected by v3 traffic. The only requests that cannot be rolled back are Direct Send requests, which have no v2 equivalent.