Engagement Ad

This page is used to create a engagement goal campaign. Engagement ads are designed to get more interactions on your content, such as likes, comments, shares, event responses, or post saves on Meta platforms.

Engagement Ad

cURL

curl --request POST \
  --url https://public.plai.io/meta/create_campaign \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "userId": "<string>",
  "campaignName": "<string>",
  "status": "<string>",
  "budget": 123,
  "startDate": "<string>",
  "endDate": "<string>",
  "url": "<string>",
  "specialAdCategories": [
    "<string>"
  ],
  "specialAdCountries": [
    "<string>"
  ],
  "utmParams": "<string>",
  "adSetName": "<string>",
  "gender": "<string>",
  "ages": {
    "minAge": 123,
    "maxAge": 123
  },
  "locations": [
    {
      "id": "<string>",
      "type": "<string>",
      "distance_unit": "<string>",
      "radius": 123,
      "countryCode": "<string>",
      "countryName": "<string>"
    }
  ],
  "excludedLocations": [
    {
      "id": "<string>",
      "type": "<string>",
      "distance_unit": "<string>",
      "radius": 123,
      "countryCode": "<string>",
      "countryName": "<string>"
    }
  ],
  "proximityTargeting": [
    {
      "countryName": "<string>",
      "distance_unit": "<string>",
      "latitude": "<string>",
      "longitude": "<string>",
      "radius": 123
    }
  ],
  "interests": [
    {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>"
    }
  ],
  "narrowInterests": [
    {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>"
    }
  ],
  "furtherInterests": [
    {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>"
    }
  ],
  "targetLocales": [
    123
  ],
  "audienceId": [
    "<string>"
  ],
  "excludedAudienceIds": [
    "<string>"
  ],
  "manualPlacements": true,
  "facebook_positions": [
    "<string>"
  ],
  "instagram_positions": [
    "<string>"
  ],
  "messenger_positions": [
    "<string>"
  ],
  "userDevices": [
    "<string>"
  ],
  "userOS": [
    "<string>"
  ],
  "campaignType": "<string>",
  "messagingApps": [
    "<string>"
  ],
  "multipleCreatives": [
    {
      "url": "<string>",
      "primaryText": "<string>",
      "headlines": "<string>",
      "phoneNumber": "<string>",
      "image": "<string>",
      "video": {
        "video_id": "<string>",
        "thumbnail_url": "<string>"
      },
      "greetingText": "<string>",
      "conversations": [
        {
          "title": "<string>"
        }
      ],
      "callToAction": "<string>"
    }
  ]
}
'

200

{
  "success": true,
  "results": {
    "success": true,
    "campaign": {
      "leadFormId": "<string>",
      "campaignId": "<string>",
      "adId": [
        "<string>"
      ],
      "adGroupId": "<string>"
    },
    "error": "<string>"
  }
}

Request Body

userId · string · required

User ID, If not already created, make a user on create user page first. If already created, retrieve the user ID from get profile page.

campaignName · string · required

Descriptive name for the campaign

status · string · default: "PAUSED"

Status of the campaign

Supported values are: ACTIVE, PAUSED

budget · number · required

Campaigns daily budget amount.

startDate · string

Start Date Format: YYYY-MM-DD, use to schedule the campaign to start at a specific date.

endDate · string

End Date Format: YYYY-MM-DD, use to schedule the campaign to end at a specific date.

url · string · required

Your Website URL

specialAdCategories · string[]

Special ad categories = HOUSING, FINANCIAL_PRODUCTS_SERVICES, EMPLOYMENT

• HOUSING: Ads related to property sales, rentals, or home-related services.
  
• FINANCIAL_PRODUCTS_SERVICES: Ads promoting credit cards, loans, insurance, or other financial services.
  - EMPLOYMENT: Ads offering job opportunities or recruitment-related services.

specialAdCountries · string[]

Special Ad Countries is required if specialAdCategories is provided.

ISO 3166-1 alpha-2 country codes e.g: US,UK

utmParams · string

UTM tracking parameters template, expected variables that can be used in it: {{campaign.id}},{{adset.id}},{{ad.id}},{{campaign.name}},{{adset.name}},{{ad.name}}

Targeting Parameters

adSetName · string

Name of the ad set audience

gender · string

If Special Ad Category is provided, then age targeting will be ignored.

Gender targeting , 1 for male, 2 for female, and if you want to target all genders skip this parameter

ages · object

If Special Ad Category is provided, then age targeting will be ignored.

Show Age Targeting Object

minAge · number · required

Minimum target age (inclusive)

maxAge · number · required

Maximum target age (inclusive)

locations · object[] · required

The locations parameter must include only locations within the country specified in the specialAdCountries field. For example, if you set specialAdCountries to US, then all locations added must be within the United States. Adding locations from other countries will result in an error.

Show Location Targeting Object

id · string · required

Facebook location ID

type · string · required

Location types: country, region, zip, country_group, neighborhood, city

distance_unit · string

radius · number

countryCode · string

ISO 3166-1 alpha-2 country codes e.g: US,UK

countryName · string

Country Name

excludedLocations · object[]

Areas where you don’t want your ads to appear. Get excluded locations data from here

Show Location Targeting Object

id · string · required

Facebook location ID

type · string · required

Location type (city, etc.)

distance_unit · string

radius · number

countryCode · string

ISO 3166-1 alpha-2 country codes e.g: US,UK

countryName · string

Country Name

proximityTargeting · object[]

Targets people within a specific radius of a location. You have to get the proximity targeting data on your own.

Show Proximity Targeting Object

countryName · string

Country Name

distance_unit · string · required

Distance Unit, values: mile, kilometer

latitude · string · required

Latitude of the location

longitude · string · required

Longitude of the location

radius · number · required

Radius value

interests · object[]

Broad audience based on general interests (e.g., fitness, travel). Get interests data from here

Show Interests Object

id · string · required

Interest Id

name · string · required

Interest Name

type · string · required

Interest Type = interests

narrowInterests · object[]

Refines audience by requiring an additional interest match. Get narrow interests data from here

Show Narrow Interests Object

id · string · required

Interest Id

name · string · required

Interest Name

type · string · required

Interest Type = interests

furtherInterests · object[]

Adds another layer of filtering—users must match all levels. Get further narrow interests data from here

Show Further Interests Object

id · string · required

Interest Id

name · string · required

Interest Name

type · string · required

Interest Type = interests

targetLocales · number[]

Use to target specific languages. You can get the list of locales here

audienceId · string[]

Array of audience IDs, you can get the audienceId from list of audiences here

excludedAudienceIds · string[]

Audience IDs to exclude, you can get the audienceId from list of audiences here

manualPlacements · boolean · default: false

Set to false to use Advantage+ placements (recommended).

If you set to true, you have to provide facebook_positions, instagram_positions, messenger_positions

Whether placements are manually selected

facebook_positions · string[]

Facebook ad placements = feed, right_hand_column, marketplace, video_feeds, story, search, instream_video, facebook_reels, facebook_reels_overlay, profile_feed, notification

instagram_positions · string[]

Instagram ad placements = stream, story, explore, explore_home, reels, profile_feed, ig_search, profile_reels

messenger_positions · string[]

Messenger ad placements = messenger_home, story

userDevices · string[]

Device targeting, you have to send the device name in string array, you can get the list of devices from here

Make sure to choose right operating system for the device.

• for eg. If the user device is iphone, then you have to send ios in user operating system.

userOS · string[]

Operating system targeting, you have to send the os platform in string array, you can get the list of operating systems from here

Engagement Ads Parameters

campaignType · string · required

For Engagement Goal, campaignType is OUTCOME_ENGAGEMENT

messagingApps · string[] · required

Messaging apps = MESSENGER, INSTAGRAM, WHATSAPP

multipleCreatives · object[]

• Atleast 1 creative is required.
• Maximum 10 creatives are allowed.

Show Multiple Creative Configuration

url · string · required

Destination URL

primaryText · string · required

Primary Text

headlines · string

Headline

phoneNumber · string

Phone Number, e.g: [phone]

image · string

Image URL is required if video is not provided

• Minimum Image Size: 400x400px
• Supported Aspect Ratios: 1:1, 16:9, 9:16

Image URL

video · object

Video ID is required if image is not provided

• You have to first upload the video here and then use the video id in the request body or get it from here.
• You can get the thumbnail url from the here

Show Video Data

video_id · string · required

Video ID

thumbnail_url · string · required

Thumbnail URL

greetingText · string · required

Greeting Text

• You can use placeholders like {{user_first_name}}, {{user_last_name}}, {{user_full_name}}, and {{page_name}} to make your greeting more personal.
• These will automatically fill in with the user’s or page’s name.
• For example: Hi, {{user_first_name}}! Please let us know how we can help you.

conversations · object[] · required

Show Conversations Array

title · string · required

Conversation Title

callToAction · string · required

Supported call to action types are: SEND_MESSAGE, BOOK_NOW, CONTACT_US, GET_PROMOTIONS, GET_QUOTE, INQUIRE_NOW, LEARN_MORE, SHOP_NOW, SIGN_UP, SUBSCRIBE, ORDER_NOW, APPLY_NOW

Response

success · boolean

Indicates that the HTTP response was successful (status code 200 OK).

results · object

Show Results Object

success · boolean

Indicates whether the specific operation or API action was successful.

campaign · object

Show Campaign Object

leadFormId · string

The unique identifier for the lead form associated with this campaign.

campaignId · string

The unique identifier for the campaign.

adId · string[]

Ad IDs Array

adGroupId · string

The unique identifier for the ad group associated with this campaign.

error · string

Error string if something went wrong