Migrate from the older APIs to API v2.

Steps

• Create a test API key in Settings › API & Webhook (Pengaturan › API & Webhook), with the permissions you need and the channel of the number the old key used.
• Change your sending code following the mapping below, then test with a test number.
• Create a Live key, install it on your server, and make sure sends work.
• Revoke the old key in the menu where it was created.

Endpoint equivalents

• POST /api/v1/send-text → POST /api/v2/messages with channel: "whatsapp_qr", type: "text", text.body.
• POST /api/v1/send-media → POST /api/v2/messages with type image, video, audio, or document, and media (url or base64 + mime, filename, caption).
• GET /api/v1/messages/{requestId} → GET /api/v2/messages/{id} (id from the send response).
• POST /api/v1/waba/send-text and send-media → POST /api/v2/messages with channel: "whatsapp_official".
• POST /api/v1/waba/send-template → POST /api/v2/messages with type: "template"; OTP codes with type: "otp".
• Integration API: contacts and conversations → GET /api/v2/contacts, GET /api/v2/conversations, POST /api/v2/conversations/{id}/messages. Reports and draft replies stay in the Integration API.

Field changes

• phone → to; message → text.body.
• The old key's device → from (device id or number id from GET /api/v2/channels), or limit the API key to that number.
• template, variables, headerVariables, mediaUrl, buttonUrl, couponCode → a template object with name, variables, header_variables, media_url, button_url, coupon_code.
• code (OTP) → otp.code with otp.template.
• Header X-API-Key → Authorization: Bearer kf_live_….

Responses and errors

Successful API v2 responses are always { "data": … }; lists add next_cursor for the next page. Errors are always { "error": { "type", "code", "message", "param", "doc_url", "request_id" } } with lowercase codes, for example invalid_phone (formerly INVALID_PHONE). The full list is on the Errors page.

Webhooks

Webhooks of an old key keep being sent while the old key is active. Webhook v2 is set per business in Settings › API & Webhook › Webhook (Pengaturan › API & Webhook › Webhook), with more events, automatic retries, and logs. Once Webhook v2 is running, revoke the old key so events are not received twice.

• send.result → message.status (the status of every outgoing message).
• messages → message.received; statuses → message.status.
• The data contents differ: see the Webhook events guide.