@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.
- package/README.md +5 -1
- package/dist/index.d.mts +396 -261
- package/dist/index.d.ts +396 -261
- package/dist/index.js +29 -1
- package/dist/index.mjs +29 -1
- package/package.json +1 -1
- package/src/client.ts +8 -0
- package/src/generated/sdk.gen.ts +64 -2
- package/src/generated/types.gen.ts +413 -265
|
@@ -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));
|