Ads that Click to WhatsApp

This guide explains how to create and publish ads that Click to WhatsApp using the Marketing API.

Ads that click to WhatsApp send people that click on your ads directly into conversations with your business in WhatsApp. Use these ads to reach people at scale and deliver standout, individualized service.

Ads that click to WhatsApp support ads with an image, a video, a carousel, or a slideshow. You can also include call prompts in your ad.

If you’re interested in creating ads that send people to Messenger or Instagram chats, see Ads that Click to Messenger or Ads that Click to Instagram for guidance. You can also create ads that pick the destination the user is most likely to respond from, see Ads that Click to Multidestination for more information.

Ad Creation Overview

This document outlines the steps you need to follow to set up your integration for click to WhatsApp ads.

You will need to:

1. Create an ad campaign
2. Create an ad set that links your ads to your ad campaign
3. Create an ad creative for the WhatsApp ad type you want to serve
4. Create an ad by linking your ad creative to your ad set
5. Publish your ad to Facebook, Instagram, and Messenger

Before You Start

This guide assumes you have:

• An ad account with Meta
• Uploaded any assets, such as images or videos, to be used in your ads to Meta servers
• A Facebook page with WhatsApp number linked manually or via API

To make successful calls to all endpoints in this guide, you will need:

• A Page access token requested by a person who can perform the ADVERTISE task on the Page
• The following permissions must be granted a person using your app:
  • ads_management
  • pages_manage_ads
  • pages_read_engagement
  • pages_show_list

Step 1: Create an ad campaign

Start by creating your ad campaign. To do this, make a POST request to the /act_<AD_ACCOUNT_ID>/campaigns endpoint where <AD_ACCOUNT_ID> is the ID for your Meta ad account. Your request must include:

Parameters

Standard Request

curl -X POST \
  -F 'name=Click to WhatsApp Campaign' \
  -F 'objective=OUTCOME_ENGAGEMENT' \
  -F 'status=ACTIVE' \
  -F 'special_ad_categories=[]' \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/campaigns

Calling Campaign Request

curl -X POST \
  -F 'name=Click to WhatsApp Calling Campaign' \
  -F 'objective=OUTCOME_ENGAGEMENT' \
  -F 'status=PAUSED' \
  -F 'special_ad_categories=[]' \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/campaigns

Response

On success, your app receives a JSON response with the ID of your newly created campaign.

{
  "id": "<AD_CAMPAIGN_ID>"
}

Updating

You can update a campaign by making a POST request to /<AD_CAMPAIGN_ID>.

Reading

To verify that you have successfully created a click to WhatsApp campaign, you can make a GET request to /<AD_CAMPAIGN_ID>. See the Ad Campaign reference for the complete list of available parameters.

Request

curl -X GET -G \
  -d 'fields=name,status,objective' \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v19.0/<AD_CAMPAIGN_ID>

Response

{
  "name": "Click to WhatsApp Campaign",
  "status": "PAUSED",
  "objective": "OUTCOME_ENGAGEMENT",
  "id": "<AD_CAMPAIGN_ID>"
}

Step 2: Create an ad set

Once you have an ad campaign, create your ad set. To create an ad set, make a POST request to the /act_<AD_ACCOUNT_ID>/adsets endpoint where <AD_ACCOUNT_ID> is the ID for your Meta ad account. Your request must include:

Parameters

Visit the Ad Account Ad Set reference for the complete list of available parameters.

Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "access_token":"<ACCESS_TOKEN>",
    "bid_amount":"<BID_AMOUNT>",
    "billing_event":"IMPRESSIONS",
    "campaign_id":"<CAMPAIGN_ID>",
    "daily_budget":"<DAILY_BUDGET>",
    "destination_type":"WHATSAPP",
    "name": "<AD_SET_NAME>",
    "optimization_goal": "IMPRESSIONS",
    "promoted_object": {
      "page_id": "<PAGE_ID>"
    },
    "status": "PAUSED",
    "start_time": "<START_TIME>",
    "targeting": { 
      "geo_locations": { "countries":["US","CA"] },
      "device_platforms": ["mobile", "desktop"]
    } 
  }' \
"https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/adsets"

Response

{
  "id": "<AD_SET_ID>"
}

Updating

You can update an ad set by making a POST request to /<AD_SET_ID>.

Reading

To verify that you have successfully created a click to WhatsApp ad set, you can make a GET request to /<AD_SET_ID>. See the Ad Set reference for the complete list of available parameters.

Request

curl -X GET -G \
  -d 'fields=name,destination_type,optimization_goal,bid_strategy,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<AD_SET_ID>

Response

{
  "name": "Click to WhatsApp Campaign",
  "status": "PAUSED",
  "objective": "OUTCOME_ENGAGEMENT",
  "id": "<AD_SET_ID>"
}

Step 3: Create an ad creative

The ad creative allows you to add assets to your ads. To create an ad creative, make a POST request to the /act_<AD_ACCOUNT_ID>/adcreatives endpoint where <AD_ACCOUNT_ID> is the ID for your Meta ad account. Your request must include:

Parameters

Visit th Ad Creative reference for the complete list of available parameters.

Filling out a Page welcome message

The default message that a customer sees is "Hello! Can I get more info on this?". You can create more tailored user experiences for your ads that click to WhatsApp by customizing your ads' greeting message in the page_welcome_message field under object_story_spec.

Note: If you are using the WhatsApp message to trigger any bot flows, please make sure to work with your BSP and agencies to update it so as to ensure flows aren't disrupted.

Example

Adding autofill message with a greeting message

"page_welcome_message": {
  "type": "VISUAL_EDITOR",
  "version": 2,
  "landing_screen_type": "welcome_message",
  "media_type": "text",
  "text_format": {
    "customer_action_type": "autofill_message",
    "message": {
      "autofill_message": {
        "content": "<AUTOFILL_MESSAGE>"
      },
      "text": "<GREETING_MESSAGE>"
    }
  }
}

Adding icebreakers with a greeting message

"page_welcome_message": {
  "type": "VISUAL_EDITOR",
  "version": 2,
  "landing_screen_type": "welcome_message",
    "media_type": "text",
    "text_format": {
      "customer_action_type": "ice_breakers",
      "message": {
        "text": "<GREETING_MESSAGE>",
        "ice_breakers": [
          {
            "title": "<ICEBREAKER>"
          },
          {
            "title": "<ICEBREAKER>"
          },
          {
            "title": "<ICEBREAKER>"
          }
        ]
      }
    }
  }
}

Adding message with a call prompt

curl \
  -F 'object_story_spec={
      "page_id": "<PAGE_ID>"
      "link_data": {
     "image_hash":<IMAGE_HASH>
            "call_to_action": {
              	"type": "WHATSAPP_MESSAGE",
              	"value": {
                  	"app_destination": "WHATSAPP"
             	 }
          },
          "link": "https://api.whatsapp.com/send",
          "name": <AD_HEADLINE>",
          "page_welcome_message":
       "type": "VISUAL_EDITOR",
        "version": 2,
        "landing_screen_type": "ctwa_call_prompt",
        "media_type": "text",
        "text_format": {
          "message": {
            "text": "<MESSAGE>"", 
            "call_prompt_data": {
              "call_prompt_message": "<CALL_PROMPT_MESSAGE>"
            }
          }
        },
        "user_edit": false
      },
  https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/adcreatives

Response

{
  "id": "<AD_CREATIVE_ID>"
}

Ad creative create examples

Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Sample ad creative",
        "object_story_spec": {
          "page_id": "<PAGE_ID>",
          "link_data": {
            "name": "<AD_HEADLINE>",
            "message": "<AD_PRIMARY_TEXT>",
            "description": "<AD_DESCRIPTION>",
            "image_hash": "<IMAGE_HASH>",
            "link": "https://api.whatsapp.com/send",
            "page_welcome_message": "<PAGE_WELCOME_MESSAGE>",
            "call_to_action": {
              "type": "WHATSAPP_MESSAGE",
              "value": {
                "app_destination": "WHATSAPP"
              }
            }
          }
        },
        "degrees_of_freedom_spec": {
          "creative_features_spec": {
            "standard_enhancements": {
              "enroll_status": "OPT_IN"
            }
          }
        }
      }' \
"https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/adcreatives"

Response

On success, your app receives a JSON response with the ID of your newly created ad creative.

{
  "id": "<AD_CREATIVE_ID>"
}

Creating ad creatives using Instagram content

You can also use your existing Instagram content for your ad creatives.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "source_instagram_media_id": "<INSTAGRAM_MEDIA_ID>",
        "instagram_user_id": "<INSTAGRAM_USER_ID>",
        "object_id": "<PAGE_ID>",
        "call_to_action": {
          "type": "WHATSAPP_MESSAGE",
            "value": {
              "link": "https://api.whatsapp.com/send",
              "app_destination": "WHATSAPP"
            }
          }
        },
        "degrees_of_freedom_spec": {
          "creative_features_spec": {
            "standard_enhancements": {
              "enroll_status": "OPT_IN"
            }
          }
        }
      }' \
  https://graph.facebook.com/latest-api-version />/act_<AD_ACCOUNT_ID>/adcreatives

Updating

You can update an ad creative by making a POST request to /<AD_CREATIVE_ID>.

Reading

To verify that you have successfully created a click to WhatsApp ad creative, you can make a GET request to /<AD_CREATIVE_ID>. See Ad Creative for the complete list of available parameters.

Request

curl -X GET -G \
  -d 'fields=name,object_story_spec{link_data{call_to_action,page_welcome_message}}' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<AD_CREATIVE_ID>

Response

{
  "name": "Sample ad creative",
  "object_story_spec" {
    "page_welcome_message": {
      "type": "VISUAL_EDITOR",
      "version": 2,
      "landing_screen_type": "welcome_message",
      "media_type": "text",
      "text_format": {
        "customer_action_type": "autofill_message",
        "message": {
          "autofill_message": {
            "content": "Sample autofill message"
          },
        "text": "Sample greeting message"
        }
      }
    }
  },
  "id": "<AD_CREATIVE_ID>"
}

Step 4: Create an ad

Ads allow you to associate ad creative information with your ad sets. To create an ad, make a POST request to the /act_<AD_ACCOUNT_ID>/ads endpoint where <AD_ACCOUNT_ID> is the ID for your Meta ad account. Your request must include:

Parameters

Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Sample ad",
        "adset_id": "<AD_SET_ID>",
        "creative": {
          "creative_id": "<AD_CREATIVE_ID>"
        },
        "status": "PAUSED"
     }' \
  "https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/ads"

Response

{
  "id": "<AD_ID>"
}

Updating

You can update an ad by making a POST request to /<AD_ID>.

Reading

To verify that you have successfully created a click to WhatsApp ad, you can make a GET request to /<AD_ID>. See the ad reference for the complete list of available parameters.

Request

curl -X GET -G \
  -d 'fields=status,adset_id,campaign_id \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v19.0/<AD_ID>

Response

{
  "status": "PAUSED",
  "adset_id": "<AD_SET_ID>",
  "campaign_id": "<AD_CAMPAIGN_ID>",
  "id": "<AD_ID>"
}

Step 5: Publish your Ad

Verify your ad exists in Ads Manager. When you are ready to publish your changes, select your campaign, the ad set for the campaign, and the ad, and click the Publish button.

You can also publish your ad using the API. Simply send a POST request to /<AD_ID> with the status parameter set to ACTIVE where <AD_ID> is the ad you want to publish.

Your ad will be reviewed by Meta, and the status will be PENDING_REVIEW. Once approved, the status will automatically update to ACTIVE, and your ad will be delivered.