@getlatedev/node 0.2.388 → 0.2.389

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1372,6 +1372,313 @@ export type ConversionEvent = {
1372
1372
  */
1373
1373
  export type actionSource = 'web' | 'app' | 'offline' | 'crm' | 'phone_call' | 'system_generated';
1374
1374
 
1375
+ /**
1376
+ * In addition to the `required` list, the request must use
1377
+ * EXACTLY ONE of the two shapes:
1378
+ *
1379
+ * - Single-creative: `headline`, `body`, and one of
1380
+ * `imageUrl` / `video` (mutually exclusive).
1381
+ * - Multi-creative: a non-empty `creatives[]` array. Top-level
1382
+ * `headline` / `body` / `imageUrl` / `video` must NOT be set
1383
+ * on this shape.
1384
+ *
1385
+ * The route enforces this at the Zod boundary; OpenAPI's
1386
+ * `required` cannot express the OR cleanly.
1387
+ *
1388
+ */
1389
+ export type CtwaAdRequestBody = {
1390
+ /**
1391
+ * Facebook or Instagram SocialAccount ID.
1392
+ */
1393
+ accountId: string;
1394
+ /**
1395
+ * Meta ad account ID, e.g. `act_123456789`.
1396
+ */
1397
+ adAccountId: string;
1398
+ /**
1399
+ * Ad display name. Used to derive campaign / ad set names.
1400
+ * On the multi-creative shape, each ad's Meta name gets a
1401
+ * " #N" suffix (1-indexed) so Ads Manager shows them as a
1402
+ * numbered batch.
1403
+ *
1404
+ */
1405
+ name: string;
1406
+ /**
1407
+ * Single-creative shape only. Mutually exclusive with
1408
+ * `creatives[]`.
1409
+ *
1410
+ */
1411
+ headline?: string;
1412
+ /**
1413
+ * Primary text shown above the image / video. Single-creative
1414
+ * shape only. Mutually exclusive with `creatives[]`.
1415
+ *
1416
+ */
1417
+ body?: string;
1418
+ /**
1419
+ * Image asset for single-creative shape. Mutually exclusive
1420
+ * with `video` and with `creatives[]`. Required on the
1421
+ * single-creative shape if `video` is not supplied.
1422
+ *
1423
+ */
1424
+ imageUrl?: string;
1425
+ /**
1426
+ * Video creative for single-creative shape. Mutually
1427
+ * exclusive with `imageUrl` and with `creatives[]`. Required
1428
+ * on the single-creative shape if `imageUrl` is not supplied.
1429
+ *
1430
+ */
1431
+ video?: {
1432
+ url: string;
1433
+ /**
1434
+ * Required by Meta for every video creative. Used as the
1435
+ * ad thumbnail.
1436
+ *
1437
+ */
1438
+ thumbnailUrl: string;
1439
+ };
1440
+ /**
1441
+ * Multi-creative shape: N CTWA ads under one campaign + one
1442
+ * ad set, sharing budget and targeting. Mutually exclusive
1443
+ * with the top-level single-creative fields (`headline` /
1444
+ * `body` / `imageUrl` / `video`). Each entry must supply its
1445
+ * own headline, body, and exactly one of `imageUrl` /
1446
+ * `video`.
1447
+ *
1448
+ */
1449
+ creatives?: Array<{
1450
+ headline: string;
1451
+ /**
1452
+ * Primary text shown above the image / video.
1453
+ */
1454
+ body: string;
1455
+ /**
1456
+ * Image asset. Mutually exclusive with this entry's
1457
+ * `video`. Required if `video` is not supplied.
1458
+ *
1459
+ */
1460
+ imageUrl?: string;
1461
+ /**
1462
+ * Video creative. Mutually exclusive with this entry's
1463
+ * `imageUrl`. Required if `imageUrl` is not supplied.
1464
+ *
1465
+ */
1466
+ video?: {
1467
+ url: string;
1468
+ /**
1469
+ * Required by Meta for every video creative. Used
1470
+ * as the ad thumbnail.
1471
+ *
1472
+ */
1473
+ thumbnailUrl: string;
1474
+ };
1475
+ }>;
1476
+ /**
1477
+ * Budget amount in the ad account's currency major units
1478
+ * (e.g. dollars for USD, not cents). Must be > 0.
1479
+ *
1480
+ */
1481
+ budgetAmount: number;
1482
+ budgetType: 'daily' | 'lifetime';
1483
+ /**
1484
+ * ISO 4217 currency code matching the ad account's currency
1485
+ * (e.g. `USD`). Optional; Meta infers from the ad account
1486
+ * when omitted.
1487
+ *
1488
+ */
1489
+ currency?: string;
1490
+ /**
1491
+ * ISO 8601 datetime. Required when `budgetType` is `lifetime`.
1492
+ *
1493
+ */
1494
+ endDate?: string;
1495
+ /**
1496
+ * ISO 3166-1 alpha-2 country codes. Defaults to `["US"]` only
1497
+ * when no other geo (`cities`, `regions`, `zips`, `metros`,
1498
+ * `customLocations`) is supplied.
1499
+ *
1500
+ */
1501
+ countries?: Array<(string)>;
1502
+ /**
1503
+ * City-level geo targeting for local CTWA campaigns. Each entry maps to Meta's
1504
+ * TargetingGeoLocationCity. `key` is Meta's city ID. `radius`
1505
+ * and `distance_unit` are coupled: set both or neither.
1506
+ * Meta enforces a minimum city radius (~17 km / 10 mi);
1507
+ * smaller values resolve to a 0-size audience and the ad
1508
+ * fails at launch. For a tighter catchment use customLocations
1509
+ * (lat/lng).
1510
+ *
1511
+ */
1512
+ cities?: Array<{
1513
+ key: string;
1514
+ radius?: number;
1515
+ distance_unit?: 'mile' | 'kilometer';
1516
+ }>;
1517
+ /**
1518
+ * Region / state-level geo targeting. `key` is Meta's region
1519
+ * ID (lookupable via GET /v1/ads/targeting/search?type=region).
1520
+ *
1521
+ */
1522
+ regions?: Array<{
1523
+ key: string;
1524
+ }>;
1525
+ /**
1526
+ * ZIP / postal-code geo targeting. `key` is the platform's
1527
+ * postal id resolved via /v1/ads/targeting/search.
1528
+ *
1529
+ */
1530
+ zips?: Array<{
1531
+ key: string;
1532
+ name?: string;
1533
+ }>;
1534
+ /**
1535
+ * DMA / metro-area geo targeting. `key` is Meta's metro id
1536
+ * (e.g. `DMA:807`).
1537
+ *
1538
+ */
1539
+ metros?: Array<{
1540
+ key: string;
1541
+ name?: string;
1542
+ }>;
1543
+ /**
1544
+ * Point-radius geo (Meta `geo_locations.custom_locations`).
1545
+ * Use for targeting a radius around a specific lat/long when
1546
+ * no Meta city/region key fits. `distanceUnit` is required.
1547
+ *
1548
+ */
1549
+ customLocations?: Array<{
1550
+ latitude: number;
1551
+ longitude: number;
1552
+ radius: number;
1553
+ distanceUnit: 'mile' | 'kilometer';
1554
+ name?: string;
1555
+ address?: string;
1556
+ }>;
1557
+ ageMin?: number;
1558
+ ageMax?: number;
1559
+ interests?: Array<{
1560
+ id: string;
1561
+ name?: string;
1562
+ }>;
1563
+ /**
1564
+ * Custom audience ID to target.
1565
+ */
1566
+ audienceId?: string;
1567
+ /**
1568
+ * Manual ad placements on the shared ad set. Omit
1569
+ * for automatic placements. When set, restricts delivery to the chosen surfaces,
1570
+ * mapped onto the ad set's `targeting.{publisher_platforms, facebook_positions, instagram_positions,
1571
+ * messenger_positions, audience_network_positions, threads_positions,
1572
+ * whatsapp_positions, device_platforms}`. Enum membership is validated here; Meta
1573
+ * additionally enforces co-selection rules and restricts which
1574
+ * placements are eligible for click-to-WhatsApp ads, returning an actionable
1575
+ * error which we surface.
1576
+ *
1577
+ */
1578
+ placements?: {
1579
+ /**
1580
+ * Top-level platforms to deliver on. A position field below is only honoured when its parent platform is included here.
1581
+ */
1582
+ publisherPlatforms?: Array<('facebook' | 'instagram' | 'threads' | 'messenger' | 'audience_network' | 'whatsapp')>;
1583
+ facebookPositions?: Array<('feed' | 'right_hand_column' | 'marketplace' | 'video_feeds' | 'story' | 'search' | 'instream_video' | 'facebook_reels' | 'facebook_reels_overlay' | 'profile_feed' | 'notification')>;
1584
+ instagramPositions?: Array<('stream' | 'story' | 'explore' | 'explore_home' | 'reels' | 'profile_feed' | 'ig_search' | 'profile_reels')>;
1585
+ messengerPositions?: Array<('messenger_home' | 'sponsored_messages' | 'story')>;
1586
+ audienceNetworkPositions?: Array<('classic' | 'rewarded_video')>;
1587
+ threadsPositions?: Array<('threads_stream')>;
1588
+ whatsappPositions?: Array<('status')>;
1589
+ /**
1590
+ * Restrict by device. Omit to deliver on both mobile and desktop.
1591
+ */
1592
+ devicePlatforms?: Array<('mobile' | 'desktop')>;
1593
+ };
1594
+ /**
1595
+ * Meta's Advantage+ audience expansion. `0` (default) keeps
1596
+ * targeting strict; `1` lets Meta expand beyond the supplied
1597
+ * targeting when its delivery system finds better matches.
1598
+ * Always sent on CREATE (Meta requires it).
1599
+ *
1600
+ */
1601
+ advantageAudience?: 0 | 1;
1602
+ /**
1603
+ * Defaults to `OUTCOME_ENGAGEMENT`. `OUTCOME_SALES` and `OUTCOME_LEADS` require
1604
+ * additional account configuration (Dataset linked to the WABA
1605
+ * for sales) and may be rejected by Meta if missing.
1606
+ *
1607
+ */
1608
+ objective?: 'OUTCOME_ENGAGEMENT' | 'OUTCOME_SALES' | 'OUTCOME_LEADS';
1609
+ /**
1610
+ * Meta bid strategy applied to the shared ad set. Defaults to
1611
+ * `LOWEST_COST_WITHOUT_CAP` (auto-bid) when omitted.
1612
+ * `LOWEST_COST_WITH_BID_CAP` and `COST_CAP` require
1613
+ * `bidAmount`. `LOWEST_COST_WITH_MIN_ROAS` requires
1614
+ * `roasAverageFloor`. CTWA's `optimization_goal` is fixed to
1615
+ * `CONVERSATIONS`, but the bid strategy is independent.
1616
+ *
1617
+ */
1618
+ bidStrategy?: 'LOWEST_COST_WITHOUT_CAP' | 'LOWEST_COST_WITH_BID_CAP' | 'COST_CAP' | 'LOWEST_COST_WITH_MIN_ROAS';
1619
+ /**
1620
+ * Whole currency units (e.g. `5` = $5.00 on a USD account).
1621
+ * Required when `bidStrategy` is `LOWEST_COST_WITH_BID_CAP`
1622
+ * or `COST_CAP`; rejected otherwise.
1623
+ *
1624
+ */
1625
+ bidAmount?: number;
1626
+ /**
1627
+ * Decimal ROAS multiplier (e.g. `2.0` = 2.0× ROAS floor).
1628
+ * Required when `bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`;
1629
+ * rejected otherwise. Meta enforces its own upper bound
1630
+ * server-side.
1631
+ *
1632
+ */
1633
+ roasAverageFloor?: number;
1634
+ /**
1635
+ * Legal entity that benefits from the ad. Required when targeting EU users
1636
+ * (EU DSA, Article 26). Optional if the ad account has a default beneficiary:
1637
+ * set it once via `PATCH /v1/ads/accounts` or in Meta Ads Manager, and Meta
1638
+ * fills it in whenever the field is omitted.
1639
+ *
1640
+ */
1641
+ dsaBeneficiary?: string;
1642
+ /**
1643
+ * Legal entity that pays for the ad. Can differ from `dsaBeneficiary`
1644
+ * (for example, an agency paying for a client's ads). Same rules as
1645
+ * `dsaBeneficiary`: required for EU targeting unless the ad account has
1646
+ * a default payor.
1647
+ *
1648
+ */
1649
+ dsaPayor?: string;
1650
+ };
1651
+
1652
+ export type budgetType = 'daily' | 'lifetime';
1653
+
1654
+ /**
1655
+ * Meta's Advantage+ audience expansion. `0` (default) keeps
1656
+ * targeting strict; `1` lets Meta expand beyond the supplied
1657
+ * targeting when its delivery system finds better matches.
1658
+ * Always sent on CREATE (Meta requires it).
1659
+ *
1660
+ */
1661
+ export type advantageAudience = 0 | 1;
1662
+
1663
+ /**
1664
+ * Defaults to `OUTCOME_ENGAGEMENT`. `OUTCOME_SALES` and `OUTCOME_LEADS` require
1665
+ * additional account configuration (Dataset linked to the WABA
1666
+ * for sales) and may be rejected by Meta if missing.
1667
+ *
1668
+ */
1669
+ export type objective = 'OUTCOME_ENGAGEMENT' | 'OUTCOME_SALES' | 'OUTCOME_LEADS';
1670
+
1671
+ /**
1672
+ * Meta bid strategy applied to the shared ad set. Defaults to
1673
+ * `LOWEST_COST_WITHOUT_CAP` (auto-bid) when omitted.
1674
+ * `LOWEST_COST_WITH_BID_CAP` and `COST_CAP` require
1675
+ * `bidAmount`. `LOWEST_COST_WITH_MIN_ROAS` requires
1676
+ * `roasAverageFloor`. CTWA's `optimization_goal` is fixed to
1677
+ * `CONVERSATIONS`, but the bid strategy is independent.
1678
+ *
1679
+ */
1680
+ export type bidStrategy = 'LOWEST_COST_WITHOUT_CAP' | 'LOWEST_COST_WITH_BID_CAP' | 'COST_CAP' | 'LOWEST_COST_WITH_MIN_ROAS';
1681
+
1375
1682
  /**
1376
1683
  * Response returned by `POST /v1/ads/ctwa` when the request used the
1377
1684
  * multi-creative shape (`creatives[]`). N persisted Ad documents share
@@ -23886,6 +24193,77 @@ export type GetCampaignAnalyticsError = (ErrorResponse | {
23886
24193
  error?: string;
23887
24194
  } | unknown);
23888
24195
 
24196
+ export type GenerateAdPreviewsData = {
24197
+ body: {
24198
+ /**
24199
+ * Zernio SocialAccount id used to resolve the Meta token.
24200
+ */
24201
+ accountId: string;
24202
+ /**
24203
+ * Meta ad account id (act_<n>).
24204
+ */
24205
+ adAccountId: string;
24206
+ /**
24207
+ * Meta ad_format values, one preview per format. Defaults to [DESKTOP_FEED_STANDARD].
24208
+ */
24209
+ formats?: Array<(string)>;
24210
+ /**
24211
+ * Preview an existing ad-account creative by id. Mutually exclusive with creativeSpec.
24212
+ */
24213
+ existingCreativeId?: string;
24214
+ /**
24215
+ * Raw Meta creative spec forwarded verbatim to /generatepreviews. Mutually exclusive with existingCreativeId.
24216
+ */
24217
+ creativeSpec?: {
24218
+ [key: string]: unknown;
24219
+ };
24220
+ };
24221
+ };
24222
+
24223
+ export type GenerateAdPreviewsResponse = ({
24224
+ previews?: Array<{
24225
+ format?: string;
24226
+ /**
24227
+ * Meta's <iframe> snippet; null when Meta returned no preview for the format.
24228
+ */
24229
+ html?: (string) | null;
24230
+ }>;
24231
+ });
24232
+
24233
+ export type GenerateAdPreviewsError = (unknown | {
24234
+ error?: string;
24235
+ });
24236
+
24237
+ export type GetAdPreviewsData = {
24238
+ path: {
24239
+ /**
24240
+ * Zernio ad id (24-char hex).
24241
+ */
24242
+ adId: string;
24243
+ };
24244
+ query?: {
24245
+ /**
24246
+ * Comma-separated Meta ad_format values (max 10), one preview per format. Defaults to DESKTOP_FEED_STANDARD.
24247
+ */
24248
+ formats?: string;
24249
+ };
24250
+ };
24251
+
24252
+ export type GetAdPreviewsResponse = ({
24253
+ adId?: string;
24254
+ previews?: Array<{
24255
+ format?: string;
24256
+ /**
24257
+ * Meta's <iframe> snippet; null when Meta returned no preview for the format.
24258
+ */
24259
+ html?: (string) | null;
24260
+ }>;
24261
+ });
24262
+
24263
+ export type GetAdPreviewsError = (unknown | {
24264
+ error?: string;
24265
+ });
24266
+
23889
24267
  export type QueryAdInsightsData = {
23890
24268
  query: {
23891
24269
  /**
@@ -27015,272 +27393,42 @@ export type SendWhatsAppConversionError = (unknown | {
27015
27393
  error?: string;
27016
27394
  });
27017
27395
 
27396
+ export type CreateMessagingAdData = {
27397
+ body: (CtwaAdRequestBody & {
27398
+ /**
27399
+ * Where the conversation opens when the ad is tapped.
27400
+ */
27401
+ destination: 'whatsapp' | 'messenger' | 'instagram_direct';
27402
+ });
27403
+ };
27404
+
27405
+ export type CreateMessagingAdResponse = (unknown);
27406
+
27407
+ export type CreateMessagingAdError = (unknown | {
27408
+ error?: string;
27409
+ });
27410
+
27411
+ export type CreateCallAdData = {
27412
+ body: (CtwaAdRequestBody & {
27413
+ /**
27414
+ * E.164 number the CALL_NOW CTA dials (e.g. +34600111222).
27415
+ */
27416
+ phoneNumber: string;
27417
+ /**
27418
+ * Website shown as the creative's link. Required: Meta rejects tel: as link_data.link; the phone number rides only the CTA.
27419
+ */
27420
+ linkUrl: string;
27421
+ });
27422
+ };
27423
+
27424
+ export type CreateCallAdResponse = (unknown);
27425
+
27426
+ export type CreateCallAdError = (unknown | {
27427
+ error?: string;
27428
+ });
27429
+
27018
27430
  export type CreateCtwaAdData = {
27019
- body: {
27020
- /**
27021
- * Facebook or Instagram SocialAccount ID.
27022
- */
27023
- accountId: string;
27024
- /**
27025
- * Meta ad account ID, e.g. `act_123456789`.
27026
- */
27027
- adAccountId: string;
27028
- /**
27029
- * Ad display name. Used to derive campaign / ad set names.
27030
- * On the multi-creative shape, each ad's Meta name gets a
27031
- * " #N" suffix (1-indexed) so Ads Manager shows them as a
27032
- * numbered batch.
27033
- *
27034
- */
27035
- name: string;
27036
- /**
27037
- * Single-creative shape only. Mutually exclusive with
27038
- * `creatives[]`.
27039
- *
27040
- */
27041
- headline?: string;
27042
- /**
27043
- * Primary text shown above the image / video. Single-creative
27044
- * shape only. Mutually exclusive with `creatives[]`.
27045
- *
27046
- */
27047
- body?: string;
27048
- /**
27049
- * Image asset for single-creative shape. Mutually exclusive
27050
- * with `video` and with `creatives[]`. Required on the
27051
- * single-creative shape if `video` is not supplied.
27052
- *
27053
- */
27054
- imageUrl?: string;
27055
- /**
27056
- * Video creative for single-creative shape. Mutually
27057
- * exclusive with `imageUrl` and with `creatives[]`. Required
27058
- * on the single-creative shape if `imageUrl` is not supplied.
27059
- *
27060
- */
27061
- video?: {
27062
- url: string;
27063
- /**
27064
- * Required by Meta for every video creative. Used as the
27065
- * ad thumbnail.
27066
- *
27067
- */
27068
- thumbnailUrl: string;
27069
- };
27070
- /**
27071
- * Multi-creative shape: N CTWA ads under one campaign + one
27072
- * ad set, sharing budget and targeting. Mutually exclusive
27073
- * with the top-level single-creative fields (`headline` /
27074
- * `body` / `imageUrl` / `video`). Each entry must supply its
27075
- * own headline, body, and exactly one of `imageUrl` /
27076
- * `video`.
27077
- *
27078
- */
27079
- creatives?: Array<{
27080
- headline: string;
27081
- /**
27082
- * Primary text shown above the image / video.
27083
- */
27084
- body: string;
27085
- /**
27086
- * Image asset. Mutually exclusive with this entry's
27087
- * `video`. Required if `video` is not supplied.
27088
- *
27089
- */
27090
- imageUrl?: string;
27091
- /**
27092
- * Video creative. Mutually exclusive with this entry's
27093
- * `imageUrl`. Required if `imageUrl` is not supplied.
27094
- *
27095
- */
27096
- video?: {
27097
- url: string;
27098
- /**
27099
- * Required by Meta for every video creative. Used
27100
- * as the ad thumbnail.
27101
- *
27102
- */
27103
- thumbnailUrl: string;
27104
- };
27105
- }>;
27106
- /**
27107
- * Budget amount in the ad account's currency major units
27108
- * (e.g. dollars for USD, not cents). Must be > 0.
27109
- *
27110
- */
27111
- budgetAmount: number;
27112
- budgetType: 'daily' | 'lifetime';
27113
- /**
27114
- * ISO 4217 currency code matching the ad account's currency
27115
- * (e.g. `USD`). Optional; Meta infers from the ad account
27116
- * when omitted.
27117
- *
27118
- */
27119
- currency?: string;
27120
- /**
27121
- * ISO 8601 datetime. Required when `budgetType` is `lifetime`.
27122
- *
27123
- */
27124
- endDate?: string;
27125
- /**
27126
- * ISO 3166-1 alpha-2 country codes. Defaults to `["US"]` only
27127
- * when no other geo (`cities`, `regions`, `zips`, `metros`,
27128
- * `customLocations`) is supplied.
27129
- *
27130
- */
27131
- countries?: Array<(string)>;
27132
- /**
27133
- * City-level geo targeting for local CTWA campaigns (e.g.
27134
- * 25km radius around Milan). Each entry maps to Meta's
27135
- * TargetingGeoLocationCity. `key` is Meta's city ID
27136
- * (lookupable via GET /v1/ads/targeting/search). `radius`
27137
- * and `distance_unit` are coupled: set both or neither.
27138
- * Meta enforces a minimum city radius (~17 km / 10 mi);
27139
- * smaller values resolve to a 0-size audience and the ad
27140
- * fails at launch. For a tighter catchment use customLocations
27141
- * (lat/lng).
27142
- *
27143
- */
27144
- cities?: Array<{
27145
- key: string;
27146
- radius?: number;
27147
- distance_unit?: 'mile' | 'kilometer';
27148
- }>;
27149
- /**
27150
- * Region / state-level geo targeting. `key` is Meta's region
27151
- * ID (lookupable via GET /v1/ads/targeting/search?type=region).
27152
- *
27153
- */
27154
- regions?: Array<{
27155
- key: string;
27156
- }>;
27157
- /**
27158
- * ZIP / postal-code geo targeting. `key` is the platform's
27159
- * postal id resolved via /v1/ads/targeting/search.
27160
- *
27161
- */
27162
- zips?: Array<{
27163
- key: string;
27164
- name?: string;
27165
- }>;
27166
- /**
27167
- * DMA / metro-area geo targeting. `key` is Meta's metro id
27168
- * (e.g. `DMA:807`).
27169
- *
27170
- */
27171
- metros?: Array<{
27172
- key: string;
27173
- name?: string;
27174
- }>;
27175
- /**
27176
- * Point-radius geo (Meta `geo_locations.custom_locations`).
27177
- * Use for targeting a radius around a specific lat/long when
27178
- * no Meta city/region key fits. `distanceUnit` is required.
27179
- *
27180
- */
27181
- customLocations?: Array<{
27182
- latitude: number;
27183
- longitude: number;
27184
- radius: number;
27185
- distanceUnit: 'mile' | 'kilometer';
27186
- name?: string;
27187
- address?: string;
27188
- }>;
27189
- ageMin?: number;
27190
- ageMax?: number;
27191
- interests?: Array<{
27192
- id: string;
27193
- name?: string;
27194
- }>;
27195
- /**
27196
- * Custom audience ID to target.
27197
- */
27198
- audienceId?: string;
27199
- /**
27200
- * Manual ad placements on the shared ad set. Omit
27201
- * for automatic placements. When set, restricts delivery to the chosen surfaces,
27202
- * mapped onto the ad set's `targeting.{publisher_platforms, facebook_positions, instagram_positions,
27203
- * messenger_positions, audience_network_positions, threads_positions,
27204
- * whatsapp_positions, device_platforms}`. Enum membership is validated here; Meta
27205
- * additionally enforces co-selection rules and restricts which
27206
- * placements are eligible for click-to-WhatsApp ads, returning an actionable
27207
- * error which we surface.
27208
- *
27209
- */
27210
- placements?: {
27211
- /**
27212
- * Top-level platforms to deliver on. A position field below is only honoured when its parent platform is included here.
27213
- */
27214
- publisherPlatforms?: Array<('facebook' | 'instagram' | 'threads' | 'messenger' | 'audience_network' | 'whatsapp')>;
27215
- facebookPositions?: Array<('feed' | 'right_hand_column' | 'marketplace' | 'video_feeds' | 'story' | 'search' | 'instream_video' | 'facebook_reels' | 'facebook_reels_overlay' | 'profile_feed' | 'notification')>;
27216
- instagramPositions?: Array<('stream' | 'story' | 'explore' | 'explore_home' | 'reels' | 'profile_feed' | 'ig_search' | 'profile_reels')>;
27217
- messengerPositions?: Array<('messenger_home' | 'sponsored_messages' | 'story')>;
27218
- audienceNetworkPositions?: Array<('classic' | 'rewarded_video')>;
27219
- threadsPositions?: Array<('threads_stream')>;
27220
- whatsappPositions?: Array<('status')>;
27221
- /**
27222
- * Restrict by device. Omit to deliver on both mobile and desktop.
27223
- */
27224
- devicePlatforms?: Array<('mobile' | 'desktop')>;
27225
- };
27226
- /**
27227
- * Meta's Advantage+ audience expansion. `0` (default) keeps
27228
- * targeting strict; `1` lets Meta expand beyond the supplied
27229
- * targeting when its delivery system finds better matches.
27230
- * Always sent on CREATE (Meta requires it).
27231
- *
27232
- */
27233
- advantageAudience?: 0 | 1;
27234
- /**
27235
- * Defaults to `OUTCOME_ENGAGEMENT` (the broadly-supported CTWA
27236
- * objective). `OUTCOME_SALES` and `OUTCOME_LEADS` require
27237
- * additional account configuration (Dataset linked to the WABA
27238
- * for sales) and may be rejected by Meta if missing.
27239
- *
27240
- */
27241
- objective?: 'OUTCOME_ENGAGEMENT' | 'OUTCOME_SALES' | 'OUTCOME_LEADS';
27242
- /**
27243
- * Meta bid strategy applied to the shared ad set. Defaults to
27244
- * `LOWEST_COST_WITHOUT_CAP` (auto-bid) when omitted.
27245
- * `LOWEST_COST_WITH_BID_CAP` and `COST_CAP` require
27246
- * `bidAmount`. `LOWEST_COST_WITH_MIN_ROAS` requires
27247
- * `roasAverageFloor`. CTWA's `optimization_goal` is fixed to
27248
- * `CONVERSATIONS`, but the bid strategy is independent.
27249
- *
27250
- */
27251
- bidStrategy?: 'LOWEST_COST_WITHOUT_CAP' | 'LOWEST_COST_WITH_BID_CAP' | 'COST_CAP' | 'LOWEST_COST_WITH_MIN_ROAS';
27252
- /**
27253
- * Whole currency units (e.g. `5` = $5.00 on a USD account).
27254
- * Required when `bidStrategy` is `LOWEST_COST_WITH_BID_CAP`
27255
- * or `COST_CAP`; rejected otherwise.
27256
- *
27257
- */
27258
- bidAmount?: number;
27259
- /**
27260
- * Decimal ROAS multiplier (e.g. `2.0` = 2.0× ROAS floor).
27261
- * Required when `bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`;
27262
- * rejected otherwise. Meta enforces its own upper bound
27263
- * server-side.
27264
- *
27265
- */
27266
- roasAverageFloor?: number;
27267
- /**
27268
- * Legal entity that benefits from the ad. Required when targeting EU users
27269
- * (EU DSA, Article 26). Optional if the ad account has a default beneficiary:
27270
- * set it once via `PATCH /v1/ads/accounts` or in Meta Ads Manager, and Meta
27271
- * fills it in whenever the field is omitted.
27272
- *
27273
- */
27274
- dsaBeneficiary?: string;
27275
- /**
27276
- * Legal entity that pays for the ad. Can differ from `dsaBeneficiary`
27277
- * (for example, an agency paying for a client's ads). Same rules as
27278
- * `dsaBeneficiary`: required for EU targeting unless the ad account has
27279
- * a default payor.
27280
- *
27281
- */
27282
- dsaPayor?: string;
27283
- };
27431
+ body: CtwaAdRequestBody;
27284
27432
  };
27285
27433
 
27286
27434
  export type CreateCtwaAdResponse = ((CtwaSingleResponse | CtwaMultiResponse));