# Create messaging ad

Creates a messaging ad. Works with Meta Ads.

```http
POST https://api.pozy.ai/v1/ads/messaging
```

- Area: Ads / Messaging Ads
- Auth: Authorization: Bearer pz_live_...

## Header parameters

- `Idempotency-Key` (string)

## Request body

Content type: `application/json`

- `creativeFeatures`, map of string
- `tracking`, object
  - `pixelId`, string
  - `urlTags`, array of object
    - `key`, string, required
    - `value`, string, required
  - `pozyTag`, boolean: Default `false`
- `accountId`, string, required
- `adAccountId`, string, required
- `name`, string, required
- `campaignName`, string: Up to 255 characters
- `adSetName`, string: Up to 255 characters
- `platformPostId`, string
- `existingPostId`, string
- `objectStoryId`, string: Matches `^\d+_\d+$`
- `pageId`, string
- `whatsappPhoneNumber`, string: Matches `^\+[1-9]\d{6,14}$`
- `headline`, string: 1 to 255 characters
- `body`, string
- `description`, string: 1 to 255 characters
- `imageUrl`, string (URL)
- `video`, object
  - `url`, string (URL)
  - `id`, string
  - `thumbnailUrl`, string (URL)
- `welcomeMessage`, object
  - `text`, string, required
  - `prefillText`, string
  - `quickReplies`, array of object: At least 1 item. Up to 13 items
    - `title`, string, required: 1 to 20 characters
    - `payload`, string, required: 1 to 1000 characters
- `carouselCards`, array of object: At least 2 items. Up to 10 items
  - `imageUrl`, string (URL), required
  - `headline`, string: Up to 255 characters
  - `description`, string: Up to 255 characters
  - `callToAction`, string
  - `linkUrl`, string
- `optimizeCardOrder`, boolean
- `creatives`, array of object: At least 1 item
  - `platformPostId`, string
  - `existingPostId`, string
  - `objectStoryId`, string: Matches `^\d+_\d+$`
  - `creativeFeatures`, map of string
  - `headline`, string: 1 to 255 characters
  - `body`, string
  - `imageUrl`, string (URL)
  - `video`, object
    - `url`, string (URL)
    - `id`, string
    - `thumbnailUrl`, string (URL)
  - `welcomeMessage`, object
    - `text`, string, required
    - `prefillText`, string
    - `quickReplies`, array of object: At least 1 item. Up to 13 items
      - `title`, string, required: 1 to 20 characters
      - `payload`, string, required: 1 to 1000 characters
  - `carouselCards`, array of object: At least 2 items. Up to 10 items
    - `imageUrl`, string (URL), required
    - `headline`, string: Up to 255 characters
    - `description`, string: Up to 255 characters
    - `callToAction`, string
    - `linkUrl`, string
- `adSetId`, string
- `existingCampaignId`, string: Matches `^\d+$`
- `budgetLevel`, string: One of `adset`, `campaign`
- `budgetAmount`, number
- `budgetType`, string: One of `daily`, `lifetime`
- `currency`, string: 3 to 3 characters
- `startDate`, string
- `endDate`, string
- `countries`, array of string: Each item: 2 to 2 characters
- `cities`, array of object
  - `key`, string, required
  - `radius`, number
  - `distance_unit`, string: One of `mile`, `kilometer`
- `regions`, array of object
  - `key`, string, required
- `zips`, array of object
  - `key`, string, required
  - `name`, string
- `metros`, array of object
  - `key`, string, required
  - `name`, string
- `countryGroups`, array of string: Each item: one of `africa`, `asia`, `europe`, `north_america`, `south_america`, `oceania`, `central_america`, `caribbean`, `eea`, `euro_area`, `nafta`, `mercosur`, `afta`, `apec`, `gcc`, `cisfta`, `emerging_markets`, `itunes_app_store`, `android_free_store`, `android_paid_store`
- `customLocations`, array of object
  - `latitude`, number, required: -90 to 90
  - `longitude`, number, required: -180 to 180
  - `radius`, number, required
  - `distanceUnit`, string, required: One of `mile`, `kilometer`
  - `name`, string
  - `address`, string
- `ageMin`, integer: 13 to 65
- `ageMax`, integer: 13 to 65
- `interests`, array of object
  - `id`, string, required
  - `name`, string
- `audienceId`, string
- `placements`, object
  - `publisherPlatforms`, array of string: Each item: one of `facebook`, `instagram`, `threads`, `messenger`, `audience_network`, `whatsapp`
  - `facebookPositions`, array of string: Each item: one of `feed`, `right_hand_column`, `marketplace`, `story`, `search`, `instream_video`, `facebook_reels`, `facebook_reels_overlay`, `profile_feed`, `notification`
  - `instagramPositions`, array of string: Each item: one of `stream`, `story`, `explore`, `explore_home`, `reels`, `profile_feed`, `ig_search`, `profile_reels`
  - `messengerPositions`, array of string: Each item: one of `messenger_home`, `sponsored_messages`, `story`
  - `audienceNetworkPositions`, array of string: Each item: one of `classic`, `rewarded_video`
  - `threadsPositions`, array of string: Each item: one of `threads_stream`
  - `whatsappPositions`, array of string: Each item: one of `status`
  - `devicePlatforms`, array of string: Each item: one of `mobile`, `desktop`
- `gender`, string: One of `all`, `male`, `female`
- `languages`, array of string
- `places`, array of object
  - `key`, string, required
- `neighborhoods`, array of object
  - `key`, string, required
- `excludedLocations`, object
- `behaviors`, array of object
  - `id`, string, required
  - `name`, string
- `workPositions`, array of object
  - `id`, string, required
  - `name`, string
- `workEmployers`, array of object
  - `id`, string, required
  - `name`, string
- `workIndustries`, array of object
  - `id`, string, required
  - `name`, string
- `incomeTier`, string: One of `top_5`, `top_10`, `top_10_25`, `top_25_50`
- `userOs`, array of string: At least 1 item
- `userDevice`, array of string: At least 1 item
- `audienceInclude`, array of string: At least 1 item
- `audienceExclude`, array of string: At least 1 item
- `savedTargetingId`, string
- `targeting`, object
  - `userOs`, array of string: At least 1 item
  - `userDevice`, array of string: At least 1 item
  - `countries`, array of string
  - `regions`, array of string or object
    - one of: string
    - one of: Option 2
      - `key`, string, required
      - `name`, string
  - `cities`, array of string or object
    - one of: string
    - one of: Option 2
      - `key`, string, required
      - `name`, string
      - `radius`, number
      - `distanceUnit`, string: One of `mile`, `kilometer`
  - `zips`, array of object
    - `key`, string, required
    - `name`, string
  - `metros`, array of object
    - `key`, string, required
    - `name`, string
  - `countryGroups`, array of string: Each item: one of `africa`, `asia`, `europe`, `north_america`, `south_america`, `oceania`, `central_america`, `caribbean`, `eea`, `euro_area`, `nafta`, `mercosur`, `afta`, `apec`, `gcc`, `cisfta`, `emerging_markets`, `itunes_app_store`, `android_free_store`, `android_paid_store`
  - `customLocations`, array of object
    - `latitude`, number, required: -90 to 90
    - `longitude`, number, required: -180 to 180
    - `radius`, number, required
    - `distanceUnit`, string, required: One of `mile`, `kilometer`
    - `name`, string
    - `address`, string
  - `excludedLocations`, object
    - `countries`, array of string
    - `countryGroups`, array of string: Each item: one of `africa`, `asia`, `europe`, `north_america`, `south_america`, `oceania`, `central_america`, `caribbean`, `eea`, `euro_area`, `nafta`, `mercosur`, `afta`, `apec`, `gcc`, `cisfta`, `emerging_markets`, `itunes_app_store`, `android_free_store`, `android_paid_store`
    - `regions`, array of object
      - `key`, string, required
      - `name`, string
    - `cities`, array of object
      - `key`, string, required
      - `radius`, number
      - `distanceUnit`, string: One of `mile`, `kilometer`
    - `zips`, array of object
      - `key`, string, required
      - `name`, string
    - `places`, array of object
      - `key`, string, required
    - `neighborhoods`, array of object
      - `key`, string, required
    - `customLocations`, array of object
      - `latitude`, number, required: -90 to 90
      - `longitude`, number, required: -180 to 180
      - `radius`, number, required
      - `distanceUnit`, string, required: One of `mile`, `kilometer`
      - `name`, string
      - `address`, string
  - `ageMin`, integer: 13 to 100
  - `ageMax`, integer: 13 to 100
  - `gender`, string: One of `all`, `male`, `female`
  - `incomeTier`, string: One of `top_5`, `top_10`, `top_10_25`, `top_25_50`
  - `languages`, array of string
  - `interests`, array of object
    - `id`, string, required
    - `name`, string
  - `behaviors`, array of object
    - `id`, string, required
    - `name`, string
  - `workPositions`, array of object
    - `id`, string, required
    - `name`, string
  - `workEmployers`, array of object
    - `id`, string, required
    - `name`, string
  - `workIndustries`, array of object
    - `id`, string, required
    - `name`, string
  - `industries`, array of string
  - `companySizes`, array of string
  - `seniorities`, array of string
  - `jobFunctions`, array of string
  - `skills`, array of string
  - `audienceInclude`, array of string
  - `audienceExclude`, array of string
  - `communities`, array of string
  - `excludedCommunities`, array of string
  - `conversationKeywords`, array of string
  - `excludedConversationKeywords`, array of string
- `rawTargeting`, object
- `specialAdCategories`, array of string: Each item: one of `HOUSING`, `EMPLOYMENT`, `CREDIT`, `ISSUES_ELECTIONS_POLITICS`, `FINANCIAL_PRODUCTS_SERVICES`, `ONLINE_GAMBLING_AND_GAMING`
- `specialAdCategoryCountry`, array of string
- `advantageAudience`, integer: One of `0`, `1`
- `objective`, string: One of `OUTCOME_ENGAGEMENT`, `OUTCOME_SALES`, `OUTCOME_LEADS`
- `status`, string: One of `ACTIVE`, `PAUSED`
- `campaignStatus`, string: One of `ACTIVE`, `PAUSED`
- `adSetStatus`, string: One of `ACTIVE`, `PAUSED`
- `adStatus`, string: One of `ACTIVE`, `PAUSED`
- `bidStrategy`, string: One of `LOWEST_COST_WITHOUT_CAP`, `LOWEST_COST_WITH_BID_CAP`, `COST_CAP`, `LOWEST_COST_WITH_MIN_ROAS`
- `bidAmount`, number
- `roasAverageFloor`, number
- `dsaBeneficiary`, string: Up to 100 characters
- `dsaPayor`, string: Up to 100 characters
- `regionalRegulatedCategories`, array of string
- `regionalRegulationIdentities`, map of string or integer
- `destination`, string: One of `whatsapp`, `messenger`, `instagram_direct`
- `destinations`, array of string: At least 2 items. Up to 3 items. Each item: one of `whatsapp`, `messenger`, `instagram_direct`
- `placementAssets`, object
  - `defaultImageUrl`, string (URL)
  - `defaultVideoUrl`, string (URL)
  - `defaultThumbnailUrl`, string (URL)
  - `rules`, array of object, required: At least 1 item. Up to 10 items
    - `imageUrl`, string (URL)
    - `videoUrl`, string (URL)
    - `thumbnailUrl`, string (URL)
    - `headline`, string: 1 to 255 characters
    - `body`, string
    - `description`, string: 1 to 255 characters
    - `placements`, object, required
      - `publisherPlatforms`, array of string: Each item: one of `facebook`, `instagram`, `threads`, `messenger`, `audience_network`, `whatsapp`
      - `facebookPositions`, array of string: Each item: one of `feed`, `right_hand_column`, `marketplace`, `story`, `search`, `instream_video`, `facebook_reels`, `facebook_reels_overlay`, `profile_feed`, `notification`
      - `instagramPositions`, array of string: Each item: one of `stream`, `story`, `explore`, `explore_home`, `reels`, `profile_feed`, `ig_search`, `profile_reels`
      - `messengerPositions`, array of string: Each item: one of `messenger_home`, `sponsored_messages`, `story`
      - `audienceNetworkPositions`, array of string: Each item: one of `classic`, `rewarded_video`
      - `threadsPositions`, array of string: Each item: one of `threads_stream`
      - `whatsappPositions`, array of string: Each item: one of `status`
      - `devicePlatforms`, array of string: Each item: one of `mobile`, `desktop`
- `workflowId`, string: Matches `^[a-fA-F0-9]{24}$`
- `validateOnly`, boolean

## Example request

```bash
curl -X POST "https://api.pozy.ai/v1/ads/messaging" \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "696e0b682d0a31188e7a2ba9",
  "adAccountId": "666219aad7bab67ace411e4f",
  "name": "Acme",
  "destination": "whatsapp",
  "destinations": [
    "whatsapp"
  ],
  "placementAssets": {
    "rules": [
      {
        "placements": {}
      }
    ]
  }
}'
```

```ts
import { randomUUID } from "node:crypto";

const res = await fetch("https://api.pozy.ai/v1/ads/messaging", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    accountId: "696e0b682d0a31188e7a2ba9",
    adAccountId: "666219aad7bab67ace411e4f",
    name: "Acme",
    destination: "whatsapp",
    destinations: [
      "whatsapp"
    ],
    placementAssets: {
      rules: [
        {
          placements: {}
        }
      ]
    }
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error ?? `Request failed with status ${res.status}`);
console.log(data);
```

```python
import os
import requests

resp = requests.post(
    "https://api.pozy.ai/v1/ads/messaging",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "accountId": "696e0b682d0a31188e7a2ba9",
        "adAccountId": "666219aad7bab67ace411e4f",
        "name": "Acme",
        "destination": "whatsapp",
        "destinations": [
            "whatsapp",
        ],
        "placementAssets": {
            "rules": [
                {
                    "placements": {},
                },
            ],
        },
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())
```

## Response 200

- `validateOnly`, boolean, required
- `results`, array of object, required
  - `node`, string, required: One of `campaign`, `adSet`, `creative`, `ad`
  - `status`, string, required: One of `validated`, `skipped`, `unverified`
  - `reason`, string
- `message`, string, required

```json
{
  "validateOnly": true,
  "results": [
    {
      "node": "campaign",
      "status": "validated",
      "reason": "string"
    }
  ],
  "message": "Hello from Pozy"
}
```