Migration from old API

This documentation describes how to migrate from previous API to Direct WhatsApp API.

Introduction

How to migrate from previous API to Direct Whatsapp API.

  1. Switch webhook (via API call).

  2. Switch API usage (in your system).

Points 2 and 3 should be done, more or less, at the same time.

Backup current webhook setting (via API call)

Send GET /v1/configs/webhook and store url address from response.

GET webhook documentation

Switch webhook

Send POST /v1/configs/webhook with your webhook endpoint:

{
"url": "https://www.example.com/webhook"
}

Set webhook documentation

Webooks will be sent as described in Whatsapp Business API

Webhooks & Callbacks mapping from Messaging & Conversations v1 API (old) to Whatsapp Direct API (new): Messaging & Conversations v1 API (old)Whatsapp Direct API (new)

Important: In new (Whatsapp Direct) API only 200 http code is allowed in webhook response. Any other code (including 201) will be interpreted as not delivered, and message will be sent again.

Switch API usage (in your system)

Switch to use new Whatsapp Direct API instead of current API.

Please remember that Whatsapp Direct API calls is compatibile with Whatsapp Business API

And is not backward compatibile with previous (not-direct) API version.

Messaging & Conversations v1 API (old) to WhatsApp Direct API (new) endpoints mapping:

Sending a WhatsApp free text message Messaging & Conversations v1 API (old)Whatsapp Direct API (new)

Sending a WhatsApp template-based message Messaging & Conversations v1 API (old)Whatsapp Direct API (new)

Sending a message with an image Messaging & Conversations v1 API (old)Whatsapp Direct API (new)

Sending a message with file attachments Messaging & Conversations v1 API (old)Whatsapp Direct API (new)

Sending a WhatsApp Contacts message Messaging & Conversations v1 API (old)Whatsapp Direct API (new)

Sending a WhatsApp static location message Messaging & Conversations v1 API (old)Whatsapp Direct API (new)

Retrieving file attachments Messaging & Conversations v1 API (old)Whatsapp Direct API (new)

Uploading file attachments Messaging & Conversations v1 API (old)Whatsapp Direct API (new)

Webhooks & Callbacks Messaging & Conversations v1 API (old)Whatsapp Direct API (new)

Configs Messaging & Conversations v1 API (old) → No longer valid.

How to revert?

In case if revert will be needed:

Just switch webhook to previously saved url via POST /v1/settings/webhook (Set webhook url). And revert your system to use old API version.