Changelog

Facebook text background posts via textFormatPresetId no longer reject long captions.

Previously, requests were rejected with 400 when content exceeded ~130 characters. Now, length is not rejected; Facebook may publish and return a warning instead.

Use textFormatPresetId (numeric string, ^\d+$) for Pages + text-only feed posts. Requests are still rejected with 400 if mediaItems or carouselCards are present, if contentType is story or reel, or if content is empty.

WhatsApp Calling config now supports a call duration cap and forwarded caller ID control on calling endpoints.

You can limit forwarded call length (to prevent dead-air billing) and, for SIP forwards, choose whether the destination sees the business number or the end-caller.

New fields:
• maxCallDurationSeconds (request/response) — 30..14400 or null (no cap / clear cap)
• forwardCallerId (request/response) — business | caller

Available on:
• GET /v1/whatsapp/calling
• GET /v1/phone-numbers/{id}/whatsapp/calling
• POST/PATCH /v1/phone-numbers/{id}/whatsapp/calling (and the deprecated alias /v1/whatsapp/phone-numbers/{id}/calling)

Bulk contact import (POST /v1/contacts/bulk) now validates and normalizes phone identifiers for phone platforms.

When platform is whatsapp or sms, each contact’s platformIdentifier is normalized to digits; values that aren’t phone-shaped are rejected per contact and reported in errors[] (not imported).

Check your handling of errors[] in the 200 response (now returned as strings describing per-contact failures).

WhatsApp Calling now supports caller-ID verification for customer-brought (BYO) phone numbers, so tel: call forwards can present the business number as caller ID.

Start (or resend) a verification code via POST /v1/phone-numbers/{id}/whatsapp/caller-id-verification with optional method: sms | call.

Confirm the code via POST /v1/phone-numbers/{id}/whatsapp/caller-id-verification/verify with required code.

GET /v1/whatsapp/calling now returns:
• callerIdMode: business | platform
• callerIdVerified: true | false

WhatsApp Calling endpoints now return caller ID details for tel: forwards via callerIdMode (and verification status on GET).

This helps you understand whether the PSTN forward-leg will present the business number or a Zernio platform number when caller ID isn’t verified.

New response fields:
• POST /v1/phone-numbers/{id}/whatsapp/calling and POST /v1/whatsapp/phone-numbers/{id}/calling: callerIdMode = business | platform
• GET /v1/phone-numbers/{id}/whatsapp/calling: callerIdMode = business | platform, callerIdVerified (boolean)

Also clarified: 400 can be returned if forwardTo is set to the number itself.

Facebook posts now support large-text background presets via textFormatPresetId in FacebookPlatformData.

This lets you render a text-only feed post as large text on a colored background using Meta’s textformatpreset_id.

Use textFormatPresetId (numeric string, pattern ^\d+$). Constraints:
• Text-only feed posts only: request is rejected if mediaItems or carouselCards are present
• Not allowed with contentType story or reel
• content must be non-empty and ≤ 130 chars (otherwise rejected)
• If a URL is present in content, no link preview is attached while a preset is set

Rate limit guidance has been updated: the per-account velocity limit referenced in 429 responses is now 25 posts/hour per account (was 15) for:
• POST /v1/posts
• POST /v1/posts/{postId}/retry

If you throttle based on the error text for 429, update your assumptions to match the new 25 posts/hour limit.

Meta ad URL tags now preserve Meta dynamic macros in tracking parameters.

When setting Meta urlTags, macros like {{ad.id}}, {{campaign.id}}, {{placement}} are sent through unescaped so Meta can expand them; all other characters are percent-encoded.

Applies to:
• PATCH /v1/ads/{adId}/tracking-tags via urlTags
• POST /v1/ads/boost via tracking.urlTags
• POST /v1/ads/create via tracking.urlTags

Meta ads reporting now supports filtering by Facebook Page via pageId on ads, campaigns, and the campaign tree.

This lets you scope results and rolled-up metrics to ads whose creative is backed by a specific Page (useful when one Meta ad account serves multiple Pages).

New query param:
• pageId (Meta only)

Available on:
• GET /v1/ads
• GET /v1/ads/campaigns
• GET /v1/ads/tree

Matches against ad.creative.pageId (may be null for non-Meta ads and rare IG-only creatives).

Facebook analytics now supports per-post monetization earnings via GET /v1/analytics/facebook/post-earnings.

This returns lifetime cumulative earnings for a single post, read live from Meta on each request (no date range supported).

Required params:
• accountId
• postId (e.g. {pageId}_{postId} or bare Reels video ID)

Optional:
• metrics = contentmonetizationearnings, monetizationapproximateearnings (defaults to both)

Notes:
• since/until/period/metricType/breakdown are rejected with 400 (lifetime only).
• Money metrics include unit (micro_amount | unspecified) and currency (string | null), and are never rescaled.
• Metrics Meta can’t serve are omitted from metrics and listed in unavailableMetrics (HTTP 200).

Also: GET /v1/analytics/facebook/page-insights now accepts monetization metrics (contentmonetizationearnings, monetizationapproximateearnings) and may return unavailableMetrics with the same omit-vs-zero behavior.

POST /v1/media/presign now supports generating presigned upload URLs for audio files.

You can upload audio by setting contentType to one of: audio/mpeg, audio/mp4, audio/aac, audio/ogg, audio/wav, audio/webm, audio/x-m4a.

Phone number purchases can now be auto-assigned to a different profile when the requested profileId already has a number.

Send profileId as the preferred profile, but the API may assign the number to the next free profile (or create one) and will return the actual assignment.

Check the assigned profile in:
• phoneNumber.profileId (when a number is provisioned)
• profileId in the { status: "already_purchased" } response when using purchaseIntentId

Instagram user tagging behavior has changed for platformSpecificData.instagram.userTags.

userTags items now require only username (previously username + x + y were required). Tag handling now depends on media type:
• Photos: x/y are required; photo tags without valid coordinates are skipped
• Reels/videos: username-only tags; any x/y provided are ignored
• Stories: x/y are optional

Carousel targeting still uses mediaIndex (defaults to 0); out-of-range indices are ignored.

GET /v1/inbox/conversations/search now supports filtering by Slack via platform=slack.

This lets you search conversations and restrict results to Slack accounts the same way as other stored-message platforms.

Use platform = facebook | instagram | telegram | whatsapp | sms | slack

The conversation.started webhook payload also adds conversation.platform=slack in WebhookPayloadConversationStarted.

POST /v1/posts/sync-external now supports LinkedIn personal profiles.

Because LinkedIn personal profiles don’t have a listing API, you must provide url to import a single post authored by the connected member (works even for posts published before the account was connected).

Use accountId + url (required for LinkedIn personal), where url can be:
• linkedin.com/posts/…
• linkedin.com/feed/update/urn:li:activity:…
• urn:li:share:… / urn:li:ugcPost:…

Imported LinkedIn personal posts return analytics (impressions, reach, reactions, comments, reshares, saves) but no content/media.

Slack accounts now support reading and updating per-channel default message identity via new endpoints GET /v1/accounts/{accountId}/slack-settings and PATCH /v1/accounts/{accountId}/slack-settings.

This lets you set default author name/avatar for Slack messages on an account (per-post platformSpecificData.username/platformSpecificData.iconUrl can still override).

Update with defaultUsername (max 80) and defaultIconUrl. Send an empty string to clear either field.

The settings response includes channel details like channelId, channelName, channelType (public or private), plus teamId/teamName.

POST /v1/inbox/conversations/{conversationId}/messages now returns more detailed send failures in 400 responses.

You can distinguish missing-recipient cases and, for Instagram/Facebook, get Meta’s diagnostic fields to debug rejected sends.

New 400 fields:
• code: PLATFORMLIMITATION | MISSINGPARTICIPANT
• platformError (Instagram/Facebook only): code, subcode, fbtraceId, type

Slack is now supported as a posting platform via POST /v1/posts and POST /v1/tools/validate/post, and can be connected via GET /v1/connect/{platform}.

You can schedule/publish Slack messages to the channel tied to the connected Slack accountId (one connected account per channel).

Use platform=slack and Slack options in platformSpecificData:
• threadTs
• unfurlLinks
• unfurlMedia
• username
• iconUrl

Slack is also available for filtering in GET /v1/accounts/health via platform=slack.

New Google Ads keyword research endpoints are available, and GET /v1/ads/insights now supports Google Ads queries.

You can now pull Keyword Planner data via:
• POST /v1/ads/keywords/ideas (generate ideas from seedKeywords and/or seedUrl)
• POST /v1/ads/keywords/historical-metrics (metrics for up to keywords = 1000)

Key request fields:
• accountId (required)
• customerId (optional; needed if the connection has several Google Ads accounts)
• countries (optional; omitted = worldwide)
• languageConstantId (default 1000)
• network: GOOGLESEARCH | GOOGLESEARCHANDPARTNERS

GET /v1/ads/insights now routes by platform:
• Meta: use objectId (+ fields/breakdowns/filtering as before)
• Google Ads: use query (GAQL SELECT), with paging via pageToken and paging.nextPageToken (fixed 10,000 rows/page)

Note: Google responses return raw rows (camelCase) with int64 counters encoded as strings; bid/CPC values are in micros.

Instagram and Facebook Inbox now include pre-connect DM history replay in GET /v1/inbox/conversations and GET /v1/inbox/conversations/{conversationId}/messages.

When an IG/FB account is connected, Zernio replays existing Meta DM history in the background so older threads can appear in listings; if you sync into your own store, you should re-sweep rather than relying on a single pass at connect time.

Key behavior:
• GET /v1/inbox/conversations: up to 500 conversations per account are replayed; replayed threads keep their original lastMessageAt/updatedTime so they sort into date order (not bumped to the top)
• Replayed history emits no webhooks and is stored as read (does not affect unreadCount)
• GET /v1/inbox/conversations/{conversationId}/messages: replay includes the 500 most recent messages per conversation; older messages beyond that are not retrievable

POST /v1/sms/registrations no longer requires phoneNumbers in the request body.

For 10DLC registrations, if phoneNumbers is omitted or an empty array, it now defaults to your active SMS-enabled US local numbers that aren’t already covered by another registration.

Key request fields:
• registrationType: standard10dlc | soleprop10dlc | tollfree
• phoneNumbers: optional (new defaulting behavior for 10DLC)

Webhooks now support post.platform.deleted in events for POST /v1/webhooks/settings and PUT /v1/webhooks/settings.

This event fires when Zernio’s background sync detects a platform post (published via Zernio) was later deleted on the platform (poll-driven ~hourly, not real-time).

Subscribe by including post.platform.deleted in events.

In WebhookPayloadPostPlatform:
• event: post.platform.published | post.platform.failed | post.platform.deleted | post.tiktok.url_resolved
• platform.status: published | failed | deleted
• New field on delete events: platform.deletedAt (ISO 8601)

Instagram is now supported for typing indicators via POST /v1/inbox/conversations/{conversationId}/typing.

Calling this endpoint can now show typing... to the Instagram recipient (works for both Instagram Login and Facebook Login accounts; recipient must be signed in to Instagram to see it).

Request: { "accountId": "..." }
Response: { "success": true|false } where success indicates whether the typing indicator was actually sent (false on unsupported platforms or if the platform call failed).

The endpoint may now also return 400 (BadRequest) in addition to existing responses.

Meta conversion goals on POST /v1/ads/create now support optimizing against a Custom Conversion.

This lets you run goal conversions or lead_conversion without providing a standard event type, by pointing the ad set at an existing Custom Conversion.

Use promotedObject.customConversionId (instead of promotedObject.customEventType) for:
• goal=conversions
• goal=lead_conversion

SMS carrier registrations now support a preflight dry-run and change-request replies.

Use POST /v1/sms/registrations/preflight to validate and preview the exact 10DLC brand/campaign payloads that would be stored, without creating a registration. It returns compliance findings (including AI review when available) so you can fix issues before submitting.

Request: registrationType (standard10dlc | soleprop_10dlc), brand, campaign, optional phoneNumbers, optional messagingBrandName
Response: composed, advisories (severity block | warn), verdict (pass | warn | fail | unreviewed), aiUnavailable

Use POST /v1/sms/registrations/{id}/respond to reply to a reviewer change request (when a registration is in changes_requested) with a note, files (hosted URLs), or both—without resubmitting the full registration. On success, status returns to requested.

Also added to POST /v1/sms/registrations: messagingBrandName (2–60 chars) to brand samples/auto-replies when it differs from the legal brand.displayName.

Webhook limits have increased: you can now configure up to 50 webhooks per user (was 10).

This lets you split event subscriptions across more endpoints/environments without hitting the previous cap.

Applies to:
• GET /v1/webhooks/settings (list up to 50)
• POST /v1/webhooks/settings (create up to 50; 400 if max reached)

New endpoint GET /v1/twitter/search lets you search public tweets from the last 7 days using an X query (passed through unchanged) to discover tweets to reply to.

Use it with:
• accountId (required)
• query (required, 1–512 chars)
• limit (10–100, default 10)
• cursor (pagination)
• sinceId / untilId (numeric tweet IDs)
• startTime / endTime (ISO 8601 UTC, within last 7 days)
• sortOrder: recency | relevancy (default recency)

To reply to a found tweet, set platformSpecificData.replyToTweetId to the returned tweets[].id when creating a post.

Rate limit: 300 requests per 15 minutes per connected account.

KYC submission now enforces stricter validation when requesting multiple numbers with an areaCode.

If you pass areaCode and request quantity above that area’s live inventory, the request is rejected with 400 (instead of best-effort skipping).

Applies to:
• POST /v1/phone-numbers/kyc
• POST /v1/whatsapp/phone-numbers/kyc

Key params: areaCode, quantity (1–5).

GET /v1/accounts now enforces stricter pagination and query validation.

If you use server-side pagination, you must send page and limit together; sending only one now returns 400. Out-of-range page/limit values are also rejected with 400 (instead of being silently clamped).

Key params:
• page (1-based) + limit (1–100) must be supplied together
• profileId must be a valid ObjectId

POST /v1/tools/validate/post now accepts accountId per platform to validate against account-specific limits.

For platform=twitter, providing platforms[].accountId lets validation apply the correct character limit (280 vs 25000 for X Premium). Missing/invalid/foreign IDs fall back to 280 and won’t error.

Use:
• platforms[].platform (enum: twitter, instagram, tiktok, youtube, facebook, linkedin, bluesky, threads, reddit, pinterest, telegram, snapchat, googlebusiness, discord)
• platforms[].accountId

New endpoint GET /v1/ads/keywords is available to list Google Search keyword criteria (positive and negative) synced from connected Google Ads accounts (one row per ad-group keyword).

Keywords are populated by the periodic ads discovery sweep (~every 3 hours per account). Campaign-level negative keywords aren’t included (ad-group-level only).

Filter with:
• accountId, adAccountId (Google customer ID), profileId
• campaignId, adSetId (Google ad group)
• status: active | paused
• matchType: exact | phrase | broad | unknown
• negative: true (negative only) | false (positive only)
• search (substring match), plus pagination via page/limit (1–500)

Response returns keywords with fields like keyword, matchType, status, negative, and syncedAt, plus pagination.

WhatsApp template endpoints can now return 502 when Meta rejects the request or is unreachable.

This makes Meta-side failures explicit so you can distinguish platform outages/rejections from Zernio validation/auth errors.

Applies to:
• GET /v1/whatsapp/templates/{templateName}
• PATCH /v1/whatsapp/templates/{templateName}
• DELETE /v1/whatsapp/templates/{templateName}

Also added ad review state support via reviewStatus (schema AdReviewStatus: inreview, approved, rejected, withissues) and Meta-only configuredStatus on Ad to separate delivery status from the ad’s on/off toggle.

message.sent webhook payload now includes message.source for WhatsApp.

This lets you tell whether a sent message came from the WhatsApp Business phone app on a Coexistence number vs being sent through Zernio (dashboard/API/broadcasts).

New field: message.source = whatsappbusinessapp | cloud_api

Only present for WhatsApp; absent on non-WhatsApp platforms.

New endpoint: POST /v1/phone-numbers/{id}/remediate/respond lets you respond to a regulatory reviewer for a phone number awaiting remediation.

You can send a reviewer message and/or submit corrected requirement data in a single call; submitting corrections re-submits the number back to review, while message-only posts to the reviewer thread.

Request body supports:
• message (max 2000)
• documents[] keyed by requirementId (use base64 or documentId)
• address (corrected address record)
• entityType: individual | business | null
• attachments[] (max 5; each filename + base64)

Response includes status: resubmitted | replied, plus posted, phoneNumber, and siblingsResubmitted.

GET /v1/profiles now supports exact-name filtering and pagination, and the default sort order is now default-first (then creation date).

Use name (exact match) to find a profile by name, and limit/skip to paginate. When limit or skip is provided, the response may include total, skip, and limit.

New query params: name, limit (1..1000), skip (>=0)

POST /v1/profiles now supports idempotent retries via Idempotency-Key (header).

With Idempotency-Key: same key + same body replays the original 201; same key + different body returns 422; key still processing returns 409. Duplicate name conflicts (409) now include details.existingProfileId.

New endpoint: POST /v1/phone-numbers/{id}/remediate/reply lets you reply to a regulatory reviewer on a phone number awaiting remediation, including optional file attachments.

Use it when the reviewer asks for info the structured remediation form can’t express; posting a reply can move the number back to in review (comment-style asks). Requires text or at least one attachments item.

Request body:
• text (string, max 2000)
• attachments (array, max 5) items: { filename, base64 } (PDF/JPG/PNG/WEBP, max 10MB each)

Response 200:
• posted (boolean)
• attachments (integer uploaded)

Errors: 400, 401, 404, 502 (retry).

You can now view KYC documents on file via GET /v1/phone-numbers/kyc/document/{documentId}.

This streams the stored verification document inline as application/pdf, so users can confirm what’s on file before reusing a verification. Access is auth-scoped (returns 404 if the documentId isn’t referenced by one of your numbers).

KYC spec responses now include documentId on document rows:
• GET /v1/phone-numbers/kyc → reusable.options[].details[].documentId
• GET /v1/whatsapp/phone-numbers/kyc → reusable.options[].details[].documentId

Use that documentId as the {documentId} path parameter when fetching the PDF.

KYC reuse selection now supports a stable option identifier via reusable.options[].id, and KYC reuse options now include instant to indicate activation speed.

This makes selecting which prior verification to reuse unambiguous (a phone number may label multiple verifications) and lets you know whether reuse activates in minutes or still queues for carrier review.

Use on submit:
• POST /v1/phone-numbers/kyc: pass reuseOptionId (preferred)
• reuseFrom is now a legacy fallback and may be ambiguous

Returned on form spec:
• GET /v1/phone-numbers/kyc (and the deprecated WhatsApp alias): reusable.options[] now includes id and instant

PUT /v1/ads/ad-sets/{adSetId} now supports updating bid strategy for platform=openai.

You can set OpenAI ad group bidding via bidStrategy + bidAmount; bidAmount is converted to micros (× 1,000,000).

Use bidStrategy:
• LOWESTCOSTWITHBIDCAP (requires bidAmount)
• COST_CAP (requires bidAmount)

LOWESTCOSTWITHMINROAS is not supported on OpenAI and will return 422.

Zernio Ads now supports OpenAI Ads (ChatGPT Ads), including connect, create/manage, reporting, and conversions.

Connect an OpenAI Ads account via POST /v1/connect/openai-ads/credentials with apiKey and profileId (requires Ads add-on).

Ads endpoints now accept platform=openai:
• GET /v1/ads, GET /v1/ads/campaigns, GET /v1/ads/tree, GET /v1/ads/timeline
• Campaign/ad set status updates: PUT /v1/ads/campaigns/{campaignId}/status, POST /v1/ads/campaigns/bulk-status, PUT /v1/ads/ad-sets/{adSetId}, PUT /v1/ads/ad-sets/{adSetId}/status

Creating ads: POST /v1/ads/create supports OpenAI Ads with:
• goal: traffic | awareness | conversions
• Required creative fields: headline, body, imageUrl, linkUrl
• Budget: budgetType must be lifetime (sending daily returns 422) and requires endDate

Conversions: POST /v1/ads/conversions now supports accountId platform openaiads.
• Use GET /v1/accounts/{accountId}/conversion-destinations to get the OpenAI pixel destinationId (pixel wire id)
• If no pixel exists yet, create one via POST /v1/accounts/{accountId}/tracking-tags (OpenAI Ads may return 422 if pixel management isn’t enabled)

Note: PUT /v1/ads/{adId} supports OpenAI Ads for status + budget only (no targeting/creative updates). DELETE /v1/ads/{adId} archives OpenAI Ads (no platform delete API).

YouTube analytics endpoints now support returning provisional (not-yet-finalized) days when you set an explicit endDate up to today.

By default, endDate still resolves to the newest fully finalized day (~3-day delay). If you request into the delay window, the response indicates which days may still change.

Applies to:
• GET /v1/analytics/youtube/daily-views
• GET /v1/analytics/youtube/video-retention
• GET /v1/analytics/youtube/demographics

New response field:
• provisionalSince — first date in the returned range whose numbers are provisional and may be revised by YouTube.

WhatsApp template creation now supports carousel and limited time offer components in components on POST /v1/whatsapp/templates.

This lets you build richer MARKETING templates (multi-card carousels and offer labels/countdowns) using the same template creation endpoint.

New component types:
• type=carousel with cards (2–10), each card components can include type=header, type=body, type=buttons
• type=limitedtimeoffer with limitedtimeoffer.text (<=16 chars) and optional limitedtimeoffer.has_expiration

Phone number purchase adds wantsWhatsapp on POST /v1/phone-numbers/purchase (used when connectWhatsapp=false) to ensure the assigned number is WhatsApp-eligible by swapping it during purchase if needed.

Profile create/update now return 409 Conflict when the profile name is already taken.

This lets clients distinguish name collisions from generic validation errors and handle retries/renames cleanly.

New response:
• POST /v1/profiles → 409 (code: profilenameconflict)
• PUT /v1/profiles/{profileId} → 409 (code: profilenameconflict)

Several Ads read endpoints now also document 400 Bad Request for invalid query input:
• GET /v1/ads → 400
• GET /v1/ads/catalogs → 400
• GET /v1/ads/catalogs/{catalogId}/product-sets → 400
• GET /v1/ads/conversions/quality → 400

Meta ads now support additional promoted-object fields, and some payloads are validated more strictly.

In POST /v1/ads/create, promotedObject adds:
• offlineConversionDataSetId
• whatsappPhoneNumber

In PUT /v1/ads/ad-sets/{adSetId}, platformSpecificData.promotedObject adds the same fields and now rejects unknown keys (additionalProperties: false), returning 400.

In POST /v1/ads/boost and POST /v1/ads/create, Meta adds specialAdCategoryCountry (array of 2-letter ISO codes). It requires specialAdCategories to be set (400 otherwise).

GET /v1/ads/audiences and POST /v1/ads/audiences add a new audience type value: meta_engagement.

Discord: new member lookup + search endpoints, and guild member listing now fails fast when the Server Members Intent is missing.

You can now fetch a single member or prefix-search members without the privileged intent (useful when full listing is blocked).

New endpoints:
• GET /v1/discord/guilds/{guildId}/members/{userId} (accountId)
• GET /v1/discord/guilds/{guildId}/members/search (accountId, query, optional limit) — query is prefix-only

Breaking change:
• GET /v1/discord/guilds/{guildId}/members now returns 403 if the Server Members Intent is not enabled (previously Discord could return an empty array).

SMS: alphanumeric Sender IDs are now supported.

Create and manage branded one-way SMS sender IDs (3–11 chars; letters/digits/spaces; at least one letter) and view the workspace-wide daily cap.

New endpoints:
• GET /v1/sms/sender-ids (returns senderIds + budget with cap/usedToday/level/pendingRequest)
• POST /v1/sms/sender-ids (senderId)
• DELETE /v1/sms/sender-ids/{id}
• POST /v1/sms/sender-ids/limit-request (requestedCap, reason)

Ads (Meta): new campaign/creative utilities + validate-only dry runs.

You can now create campaign shells, manage the creative library, duplicate ad sets/ads, and run a Meta validation pass without creating anything.

New endpoints:
• POST /v1/ads/campaigns (standalone campaign)
• POST /v1/ads/creatives, GET /v1/ads/creatives, GET /v1/ads/creatives/{creativeId}, PUT /v1/ads/creatives/{creativeId}, DELETE /v1/ads/creatives/{creativeId}
• GET /v1/ads/images, GET /v1/ads/labels, GET /v1/ads/businesses, GET /v1/ads/high-demand-periods
• POST /v1/ads/ad-sets/{adSetId}/duplicate, POST /v1/ads/{adId}/duplicate

New option on POST /v1/ads/create:
• validateOnly: true (Meta only; single standalone shape only) — returns 200 with validation results instead of creating entities.

WhatsApp inbound attachments can now be downloaded via GET /v1/whatsapp/media/{mediaId}.

This streams the binary for a WhatsApp attachment referenced by attachments[].url in message.received webhooks and List messages.

Call it with:
• mediaId (path) from attachments[].payload.id
• accountId (query) = the WhatsApp account that received the media
• Authorization: Bearer <your API key> (required; otherwise 401)

Important behavior:
• Download on receipt: WhatsApp media expires on Meta’s side (typically ~7 days). After expiry this endpoint returns 400 permanently (do not retry).

Removed endpoints:
• GET /v1/sms/sender-ids, POST /v1/sms/sender-ids, POST /v1/sms/sender-ids/limit-request, DELETE /v1/sms/sender-ids/{id}
• POST /v1/ads/campaigns
• POST /v1/ads/ad-sets/{adSetId}/duplicate
• POST /v1/ads/{adId}/duplicate
• GET /v1/ads/labels
• GET /v1/ads/high-demand-periods
• GET/POST/GET/PUT/DELETE /v1/ads/creatives (and /v1/ads/creatives/{creativeId})
• GET /v1/ads/images

Breaking change (SMS): POST /v1/sms/messages no longer supports alphanumeric sender IDs in from (now requires an SMS-enabled number).

Meta Ads: new endpoints for campaign/creative management, duplication, and library access.

You can now create a standalone campaign shell, duplicate ad sets/ads via Meta native copy, manage creatives separately from ads, and query labels/images/creative library + budget schedules.

New endpoints:
• Create campaign (ODAX shell): POST /v1/ads/campaigns with goal (engagement, traffic, awareness, videoviews, leadgeneration, leadconversion, jobapplicants, conversions, apppromotion, catalogsales), optional CBO via budgetAmount + budgetType (daily|lifetime), status (ACTIVE|PAUSED)
• Duplicate ad set: POST /v1/ads/ad-sets/{adSetId}/duplicate with deepCopy, campaignId, statusOption (ACTIVE|PAUSED|INHERITEDFROMSOURCE), syncAfter
• Duplicate ad: POST /v1/ads/{adId}/duplicate with adSetId, statusOption (ACTIVE|PAUSED|INHERITEDFROMSOURCE), syncAfter
• Creative library + CRUD: GET /v1/ads/creatives, POST /v1/ads/creatives (use imageUrl or imageHash or carouselCards), GET /v1/ads/creatives/{creativeId}, PUT /v1/ads/creatives/{creativeId} (rename via name), DELETE /v1/ads/creatives/{creativeId}
• Libraries/metadata: GET /v1/ads/images, GET /v1/ads/labels
• Budget schedules: GET /v1/ads/high-demand-periods (exactly one of campaignId or adSetId)

Audience updates expanded:
PUT /v1/ads/audiences/{audienceId} now supports updating platform audiences’ name/description (Meta only). spec is still allowed only for saved_targeting; sending spec for a platform audience returns 400. Non-Meta platform audience updates return 501.

SMS now supports alphanumeric sender IDs (e.g. ZERNIO) for one-way international texting.

Create/manage sender IDs via:
• GET /v1/sms/sender-ids (includes workspace daily budget: budget.cap, budget.usedToday, budget.level, budget.pendingRequest)
• POST /v1/sms/sender-ids with senderId (3–11 chars; letters/digits/spaces; at least one letter)
• DELETE /v1/sms/sender-ids/{id}
• POST /v1/sms/sender-ids/limit-request with requestedCap + reason

Sending: POST /v1/sms/messages now accepts from as either an SMS-enabled number or an approved sender ID.

Notes for sender IDs: text-only (no MMS), recipients can’t reply, and sends to US/CA/PR are blocked.

New responses to handle on POST /v1/sms/messages:
• 403 (gate: registration/MMS not supported/alpha to US-CA-PR)
• 429 (alphanumeric daily cap reached; code alphadailylimit_reached; resets midnight UTC)
• 404 now covers “no SMS-enabled number or sender ID matches from”.

Meta ads now support Reach & Frequency (RESERVED) buying via new R&F prediction + reservation endpoints.

You can request a quote (no spend, no entities created), reserve it to lock price/inventory, then create an ad using the reserved prediction.

New endpoints:
• POST /v1/ads/rf-predictions (create quote; provide date range + exactly one of budgetAmount or reach)
• GET /v1/ads/rf-predictions/{predictionId}
• POST /v1/ads/rf-predictions/{predictionId}/reserve (returns a NEW RESERVED predictionId + expiresAt)
• DELETE /v1/ads/rf-predictions/{predictionId} (cancel reservation)

POST /v1/ads/create adds:
• buyingType: AUCTION | RESERVED
• rfPredictionId (required when buyingType=RESERVED)

Notes: RESERVED uses the single-ad shape only (no creatives[], adSetId, existingCampaignId, or dynamicCreative). Budget/schedule/pricing come from the reservation; bid fields are ignored.

New Meta Ads endpoints are available for live reads, auditing, studies, finances, and asset upload.

You can now:
• Read a live Meta ad set (incl. learning phase) via GET /v1/ads/ad-sets/{adSetId} with accountId and optional fields (default includes learningstageinfo).
• Fetch account audit/activity log via GET /v1/ads/activity using accountId, adAccountId, optional since/until, optional objectId (client-side filter), plus paging limit/after.
• List A/B tests & lift studies via GET /v1/ads/studies with accountId, adAccountId, optional fields, and paging limit/after.
• Read ad account finances via GET /v1/ads/accounts/finance (balance, amountSpent, spendCap, fundingSource).
• Upload ad images from base64 via POST /v1/ads/images with accountId, adAccountId, imageBase64 (optional filename); returns image.hash and image.url.

Also updated:
• specialAdCategories now includes FINANCIALPRODUCTSSERVICES and ONLINEGAMBLINGAND_GAMING on POST /v1/ads/boost and POST /v1/ads/create.
• callToAction enums expanded on POST /v1/ads/create (and Meta creatives[].callToAction) to include values like ADDTOCART, APPLYNOW, BOOKNOW, ORDERNOW, INSTALLMOBILEAPP, USEAPP (plus others).
• POST /v1/ads/conversions: consent now affects Meta too — if adUserData or adPersonalization is DENIED, events are sent with Meta Limited Data Use (LDU); GRANTED (or omitted) uses default processing.

New Meta Ads capabilities are available: ad previews, click-to-message ads, and click-to-call ads.

You can now render embeddable preview iframes before creating an ad via POST /v1/ads/preview (provide exactly one of existingCreativeId or creativeSpec) or for an existing ad via GET /v1/ads/{adId}/preview. Use formats (Meta ad_format values, max 10) to control placements.

Click-to-message ads are now unified under POST /v1/ads/messaging with destination:
• whatsapp
• messenger
• instagram_direct

Click-to-call ads are supported via POST /v1/ads/call using phoneNumber (E.164) and linkUrl.

POST /v1/ads/ctwa is now deprecated; use POST /v1/ads/messaging with destination: whatsapp (the old endpoint remains for back-compat).

Meta insights now supports action-level segmentation and attribution controls on both the sync and async insights APIs.

You can segment actions[] and control attribution windows/reporting time without changing endpoints.

New on GET /v1/ads/insights:
• actionBreakdowns
• actionAttributionWindows
• actionReportTime
• useUnifiedAttributionSetting

New on POST /v1/ads/insights/reports:
• actionBreakdowns
• actionAttributionWindows (array of strings)
• actionReportTime
• useUnifiedAttributionSetting

Meta ad creation also adds hand-built carousels via carouselCards on POST /v1/ads/create (2–10 cards, deterministic order).

Google Business batch reviews now supports server-side sorting via orderBy on POST /v1/accounts/{accountId}/gmb-reviews/batch.

This lets you fetch newest-updated reviews first (default) and stop paginating earlier when polling for recent changes.

Use orderBy:
• updateTime desc (default)
• rating
• rating desc

Also note: locationNames is now capped at maxItems: 50 per request (chunk larger sets).

Responses now clarify attribution: each locationReviews[].name is the LOCATION resource name (not the review resource name), and review includes review.name (full review resource name) plus reviewMediaItems (photos/videos).

Inbox reviews (GET /v1/inbox/reviews) now includes Google Business location attribution fields: locationId (bare id) and locationName (display name).

POST /v1/inbox/comments/{postId} now supports attaching an image when replying on Facebook via attachmentUrl.

This lets you publish a photo comment alongside the text reply. The image URL must be publicly accessible so Meta can fetch it.

New request field:
• attachmentUrl (uri) — Facebook only

If attachmentUrl is sent for non-Facebook platforms, the API now returns 400 (e.g. code PLATFORMNOTSUPPORTED).

POST /v1/ads/create now supports more TikTok controls and targeting.

You can create TikTok ads/campaigns in a paused state and use additional geo targeting fields for TikTok.

Key changes:
• status now applies to Meta and TikTok: ACTIVE | PAUSED (TikTok pauses campaign > ad group > ad)
• Geo targeting fields now support TikTok: cities, regions, metros

GET /v1/ads/targeting/search: TikTok geo searches now return mixed levels in one list (type can be country | region | city | district | metro), and geoType is not applied for TikTok results.

TikTok conversion ads created via POST /v1/ads/create now accept TikTok Events Manager event names in promotedObject.customEventType (auto-resolved to the underlying optimization_event code).

This makes it easier to configure goal=conversions without manually mapping to TikTok’s internal codes; note that ONWEBORDER is now deprecated.

Use promotedObject.customEventType with one of:
• SHOPPING, ONWEBCART, INITIATEORDER, FORM, ONWEBREGISTER, ONWEB_DETAIL

Applies to TikTok only; promotedObject.pixelId is still required for goal=conversions.

New Meta Ads insights endpoints are available: GET /v1/ads/insights, POST /v1/ads/insights/reports, GET /v1/ads/insights/reports/{reportRunId}.

You can now run a flexible live insights query that forwards your chosen Meta Graph parameters (fields/breakdowns/filtering) and returns rows in Meta’s raw shape; use the async report flow for long ranges or large accounts.

Sync query: GET /v1/ads/insights with accountId, objectId, optional level (ad/adset/campaign/account), fields, breakdowns, filtering, datePreset or fromDate+toDate, timeIncrement, limit, after.

Async flow:
• Submit: POST /v1/ads/insights/reports (body includes accountId, objectId, optional level, fields, breakdowns, filtering, datePreset or fromDate/toDate, timeIncrement (1-90 | monthly | all_days)) → returns reportRunId
• Poll: GET /v1/ads/insights/reports/{reportRunId} with accountId, limit, after → returns status and percentCompletion; when status is Job Completed, includes data + paging.

Meta only (facebook/instagram). Invalid field/breakdown combos return 400 with Meta’s error message.

Google Business Profiles: you can now assign a GBP location to a different profile by reusing an existing OAuth grant (no browser re-auth).

Use POST /v1/accounts/{accountId}/gmb-locations/assign with:
• profileId (target profile)
• selectedLocationId (e.g. locations/123)
• googleAccountId (optional, recommended for accounts with many locations)
Returns 409 if the target profile already has a Google Business connection.

Phone number purchasing now supports selecting a number type.

On POST /v1/phone-numbers/purchase you can pass numberType: local | mobile | national | toll_free. Availability/KYC can vary by (country, type).

Country/type discovery updates:
• GET /v1/phone-numbers/countries now includes inStock and types[] (per-type monthlyCents, needsKyc, whatsappAvailable, smsAvailable, callsAvailable, inStock)
• GET /v1/phone-numbers/availability adds optional numberType
• GET /v1/phone-numbers/kyc adds optional numberType

Facebook connect flow: POST /v1/connect/facebook/select-page can now return 409 with code RECONNECTACCOUNTMISMATCH when a force=true token-recovery re-auth lands on a different user/page than the existing connection.

Google Business reviews now include attached photos in review responses.

You can display/download reviewer-uploaded images and know how many photos are attached per review.

Added fields:
• GET /v1/accounts/{accountId}/gmb-reviews → reviews[].photoCount, reviews[].photos[] (each item: url)
• GET /v1/inbox/reviews → data[].photos[] (Google Business only; each item: url)

Notes: photoCount counts photos only (videos not counted). For non-Google platforms, photos is always an empty array.

Meta campaign updates now support a lifetime spend cap via platformSpecificData.spendCap on PUT /v1/ads/campaigns/{campaignId}.

This lets you set or remove a campaign-level spend cap without recreating the campaign.

Use:
• platformSpecificData.spendCap = number (sets cap)
• platformSpecificData.spendCap = null (removes cap; Meta rejects 0)

Meta ad set updates now accept post-launch delivery settings via platformSpecificData on PUT /v1/ads/ad-sets/{adSetId}.

Set any of:
• platformSpecificData.optimizationGoal
• platformSpecificData.billingEvent
• platformSpecificData.startDate, platformSpecificData.endDate
• platformSpecificData.promotedObject (e.g. pixelId, customEventType, pageId, applicationId, objectStoreUrl, customConversionId, productCatalogId, productSetId)

Also added: billingEvent (Meta only) on POST /v1/ads/create to explicitly set the ad set’s billing event (defaults to IMPRESSIONS).

Queue schedules: DELETE /v1/queue/slots now supports deleting all queues for a profile by omitting queueId.

This lets you clear a profile’s entire queue schedule in one call (previously queueId was required).

Use:
• profileId (required)
• queueId (optional) — omit to delete all queues

Sequences: POST /v1/sequences/{sequenceId}/enroll now returns per-contact outcomes.

Response now includes failed and results (array of { contactId, success, error }) in addition to enrolled.

Also: GET /v1/queue/slots expands all to true | false.

GET /v1/accounts/{accountId}/gmb-locations now supports a limit query parameter.

You can raise the maximum number of Google Business Profile locations returned (default was effectively 100) up to 500 to enumerate accounts with more than 100 locations.

Use limit:
• limit (integer, default 100, min 1, max 500)

Invalid values now return 400 (e.g. limit out of range).

YouTube demographics analytics now supports per-video audience breakdowns via videoId on GET /v1/analytics/youtube/demographics.

Pass videoId to fetch demographics for a single video (instead of the whole channel). Note: YouTube may return empty breakdowns for low-traffic videos due to signed-in view thresholds.

Use:
• videoId - YouTube video ID (scoped to the connected channel; otherwise 404)
• startDate - defaults to the video publish date (lifetime) when videoId is provided

Response adds (video mode only): videoId, title, publishedAt.

Also: Meta city targeting docs were updated to reflect that cities[].radius has a minimum (~17 km / 10 mi). Smaller values can produce a 0-size audience and fail at launch; use customLocations for tighter radius targeting.

GET /v1/connect/{platform}/ads now supports force to trigger a fresh OAuth flow even when an ads account is already connected.

This lets you proactively refresh stored tokens (the endpoint normally returns alreadyConnected: true based on account active state, not token liveness).

Use force=true to always receive authUrl; completing OAuth refreshes the stored token on the existing posting + ads accounts in place.

New param: force (true/false, default false)

SMS carrier registration status now includes additional lifecycle states in registration APIs.

You may now see pre-submission review and deactivation states when listing, fetching, or reusing registrations, which can affect clients that assume only the previous 3 statuses.

Updated status enum:
• pending, approved, rejected, requested, changes_requested, deactivated

Applies to:
• GET /v1/sms/registrations
• GET /v1/sms/registrations/{id}
• POST /v1/phone-numbers/{id}/sms/reuse-registration

Also added to POST /v1/sms/registrations request body:
• resubmitRequestId (resubmit an existing registration returned for changes)
• wizardValues (optional raw wizard answers; can be omitted by API integrators)

conversions in ads metrics now includes non-Meta platforms.

You can now rely on conversions for more platforms when charting or aggregating performance (instead of always getting 0 outside Meta).

Applies to:
• GET /v1/ads/timeline (rows[].conversions)
• AdMetrics.conversions

New platform behavior:
• Meta: events matching the campaign optimization goal
• Google: tracked conversions
• X / LinkedIn: reported website/lead conversions (added 2026-07)

GET /v1/sms/registrations now supports includeDeactivated (boolean).

Deactivated (terminated) registrations are hidden by default; pass includeDeactivated=true to include them in the results.

New query param:
• includeDeactivated - true to include deactivated registrations (default: hidden)

New endpoint: DELETE /v1/sms/registrations/{id} to deactivate an SMS brand/campaign registration.

This terminates the carrier registry campaign so recurring monthly campaign fees stop; numbers under the registration can no longer send texts (receiving is unaffected). Deactivation is irreversible and the operation is idempotent.

Key parameter: id (path, string)

Response: 200 returns status = deactivated (enum: deactivated)

LinkedIn now supports Thought Leader ads on POST /v1/ads/create via platformSpecificData.thoughtLeader.

This lets you create a LinkedIn ad that references an existing post (share/ugcPost) as the creative, while still using the normal /v1/ads/create flow for targeting/bidding/schedule.

Set:
• platformSpecificData.thoughtLeader.postUrn (pattern: urn:li:share:\d+ or urn:li:ugcPost:\d+)

Notes:
• Mutually exclusive with other LinkedIn creative sources in platformSpecificData (e.g. carousel, document, conversation, etc.)
• When using thoughtLeader, you don’t need headline/body/imageUrl/organizationId for the creative (the referenced post provides them).

New LinkedIn-only Ads helpers are available:

• Suggested bid & budget bounds via POST /v1/ads/targeting/bid-pricing
Returns suggested bid + allowed bid limits and daily budget bounds for a targeting spec (use before POST /v1/ads/create).
Key request fields: accountId, adAccountId, spec, optional campaignType (TEXTAD/SPONSOREDUPDATES/SPONSOREDINMAILS), bidType (CPM/CPC/CPV), matchType (EXACT/AUDIENCEEXPANDED), dailyBudget.
Response: available and pricing (may be null).

• Impressions/clicks/spend forecast via POST /v1/ads/targeting/supply-forecast
Forecasts metrics for a targeting spec over a future time range.
Key request fields: accountId, adAccountId, spec, timeRangeStart, timeRangeEnd, plus either dailyBudget or totalBudget. For manual bidding, set competingBid with bidType (CPM/CPC/CPV) and amount; for auto-bidding, set optimizationTarget.
Response: available and forecast series with metricType and granularity (DAILY/SEVENDAY/THIRTYDAY/CUSTOM).

For non-LinkedIn accounts, both endpoints return available: false (not an error).

New endpoint POST /v1/sms/opt-in-proof uploads SMS opt-in proof (screenshot/PDF) and returns a public URL you can include in a campaign’s messageFlow for carrier review.

Send multipart/form-data with file (PNG/JPG/WebP/GIF/PDF, max 4MB).

Response: { "url": "..." }

Errors: 422 unsupported type/too large, 401 unauthorized. Alias: /v1/sms/registrations/{id}/opt-in-proof.

POST /v1/sms/messages now supports scheduling via sendAt.

Set sendAt (ISO 8601 date-time with offset) to queue an SMS/MMS for a future time; it must be in the future. The message is queued and the message.delivered webhook fires when it actually sends.

New field: sendAt

SMS carrier registration now accepts optional policy URLs on 10DLC campaigns via POST /v1/sms/registrations.

You can include privacy/terms links in the campaign object to help carrier reviewers validate compliance.

New campaign properties:
• privacyPolicyLink
• termsAndConditionsLink

Also, embeddedLink and embeddedPhone now document auto-derivation from your sample messages when omitted.

New endpoint: POST /v1/sms/registrations/{id}/opt-in-proof uploads an SMS opt-in form screenshot/PDF and returns a public URL you can include in an appeal.

Use it to host proof of consent when submitting POST /v1/sms/registrations/{id}/appeal (add the returned URL to your messageFlow).

Request: multipart/form-data with file (PNG/JPG/WebP/GIF/PDF, max 4MB)
Response: { "url": "..." }
Errors: 404 registration not found, 422 unsupported type/too large

New endpoint: POST /v1/accounts/{accountId}/pinterest-boards to create Pinterest boards on a connected Pinterest account.

The returned board.id can be used immediately as platformSpecificData.boardId when creating a Pinterest post.

Request body:
• name (required)
• description
• privacy: PUBLIC | PROTECTED | SECRET (default PUBLIC)

Response (201): board with id, name, description, privacy, url.

Website retargeting audiences are now supported via a new audience type: website_retargeting (LinkedIn only).

You can now create and list these audiences using type=website_retargeting on POST /v1/ads/audiences and filter them via GET /v1/ads/audiences.

When creating, set:
• type: website_retargeting
• matchRules: array of URL patterns (matchType: EXACT | STARTSWITH | CONTAINS | ENDSWITH, plus matchValue)

Custom audiences now support new types: company_list and engagement on /v1/ads/audiences.

You can list and filter these via GET /v1/ads/audiences using type = customerlist | companylist | engagement | website | lookalike | saved_targeting.

To create them via POST /v1/ads/audiences:
• type=engagement (LinkedIn): requires sourceType (VIDEOADS | LEADGENFORMS | ORGANIZATIONPAGES | EVENTPAGES | SINGLEIMAGE_ADS), plus trigger, lookbackDays (30 | 60 | 90 | 180 | 365), and engagementSources.
• type=company_list (LinkedIn): requires companies (array of company rows like name, domain, website, linkedinPageUrl).

LinkedIn firmographic breakdowns are now supported in analytics via the breakdowns query param on GET /v1/ads/{adId}/analytics and GET /v1/ads/campaigns/{campaignId}/analytics.

This lets you request LinkedIn aggregated firmographic segments for the requested date range (note: LinkedIn data is aggregated over the whole range, delayed 12–24h, and segments with <3 events are omitted).

Use breakdowns with LinkedIn dimensions:
• jobtitle, jobfunction, seniority, industry
• company, company_size
• country, region

LinkedIn breakdown rows include the raw pivot value plus a resolved name.

POST /v1/ads/create now supports LinkedIn Jobs ads via a new goal job_applicants.

This lets you create Dynamic Jobs Ads that promote open roles (requires a Company Page with active job postings).

Use:
• goal: job_applicants
• platformSpecificData.jobs with headline and buttonLabel (each takes exactly one of preApproved or custom)

Also added for LinkedIn-only creatives on platformSpecificData:
• conversation (Conversation Ads) with subject, firstMessageId, and messages (buttons use exactly one of nextMessageId or url).

POST /v1/ads/create now supports more LinkedIn ad formats via platformSpecificData.

You can create LinkedIn-only creatives (beyond single image/video) by setting one of these mutually-exclusive options:
• platformSpecificData.carousel (2–10 cards)
• platformSpecificData.document (PDF/PPT/DOC)
• platformSpecificData.spotlight (dynamic spotlight)
• platformSpecificData.follower (dynamic follower)
• platformSpecificData.textAd (right-rail text ad)
• platformSpecificData.event (promote an existing event)

Notes:
• Carousel cards use cards[].imageUrl and optionally cards[].headline / cards[].landingUrl (falls back to ad-level linkUrl).
• Document ads use document.url + document.title.
• Spotlight ads use spotlight.headline + spotlight.callToAction + spotlight.landingUrl.
• Follower ads use follower.callToAction enum: VISITORGANIZATIONCOMPANYPAGE, VISITORGANIZATIONLIFEPAGE, VISITORGANIZATIONJOBSPAGE, VISITORGANIZATIONCAREERSPAGE.

Also clarified: on LinkedIn, imageUrl + linkUrl publishes an ARTICLE-content creative (with longHeadline as the description).

Sole-prop 10DLC registrations can now re-send the OTP via POST /v1/sms/registrations/{id}/resend-otp.

Use this when the original code expired or never arrived. It only works while the registration is pending and awaiting OTP, and is rate-limited to 1 request/min.

Request: id (path)
Response: { sent: boolean }
Errors: 400 not awaiting OTP, 404 not found, 429 wait 1 minute

Port-in updates:
• POST /v1/phone-numbers/port-in: endUser.accountNumber is now required (and endUser.countryCode is restricted to US/CA)
• POST /v1/phone-numbers/port-in/check: response adds lineType (when known) to indicate if a transfer PIN is required at submit

10DLC campaign submissions:
• POST /v1/sms/registrations: campaign.optinMessage, campaign.optoutMessage, and campaign.helpMessage are now optional; when omitted, compliant templates are generated.

LinkedIn ads now support campaign bidding & delivery controls via platformSpecificData on POST /v1/ads/create and POST /v1/ads/boost.

This lets you set LinkedIn-specific options (manual bids, cost model, audience expansion, Audience Network, etc.) while keeping the platform inferred from accountId (sending options for a different platform returns 400).

Use platformSpecificData (LinkedIn only):
• costType: CPM | CPC | CPV
• unitCost (manual bid; requires costType)
• optimizationTargetType (pass-through)
• creativeSelection: OPTIMIZED | ROUND_ROBIN
• audienceExpansionEnabled, offsiteDeliveryEnabled, connectedTelevisionOnly

Comment-to-DM automations now support message variations for random rotation of DM text and public comment replies.

This lets you provide multiple alternate texts so repeat triggers don’t always send identical messages.

New optional fields:
• Create/Update: dmMessageVariations (up to 5), commentReplyVariations (up to 5)
• Returned on list/detail/update responses: dmMessageVariations, commentReplyVariations

Rotation behavior:
• DM text is picked at random from [dmMessage, ...dmMessageVariations]
• Public reply is picked at random from [commentReply, ...commentReplyVariations]

Applies to: POST /v1/comment-automations, PATCH /v1/comment-automations/{automationId}, GET /v1/comment-automations, GET /v1/comment-automations/{automationId}.

Analytics responses now include media accessibility alt text via mediaItems[].altText.

Use this to display or audit the alt text set on each media item when available.

New field:
• mediaItems[].altText (string)

Included in:
• AnalyticsSinglePostResponse
• AnalyticsListResponse

GET /v1/inbox/reviews now returns Google Business review photo info via hasPhotos and photoCount.

This lets you detect and display reviews with attached photos (Google Business only; other platforms return hasPhotos=false and photoCount=0).

New fields:
• hasPhotos
• photoCount

GET /v1/ads/accounts now includes Meta’s minimum daily budget via minimumDailyBudget.

Use this to validate budget inputs against account-level minimums (field may be absent if the connected token can’t read it).

New field:
• minimumDailyBudget

Meta ads now support setting EU DSA (Article 26) defaults at the ad-account level, so EU-targeted calls can omit per-ad dsaBeneficiary/dsaPayor when defaults are configured.

Set defaults once via PATCH /v1/ads/accounts with accountId, adAccountId, defaultDsaBeneficiary, optional defaultDsaPayor (if omitted, payor defaults to beneficiary).

Read current defaults via GET /v1/ads/dsa-defaults (accountId, adAccountId), and fetch Meta-provided suggestions via GET /v1/ads/dsa-recommendations (accountId, adAccountId).

POST /v1/ads/create, POST /v1/ads/boost, and POST /v1/ads/ctwa now treat dsaBeneficiary/dsaPayor as optional for EU targeting when the Meta ad account has defaults set (Meta accounts only; other platforms return 400).

POST /v1/phone-numbers/port-in now supports portType to specify whether you’re porting the entire losing account or only some numbers.

Use portType to avoid ambiguity on ports where the losing account keeps some numbers.

New/updated request behavior:
• portType: full | partial (default: full)
• endUser.billingPhoneNumber: now documented as the number on the losing carrier’s bill; defaults to the ported number itself on single-number orders
• focDatetimeRequested: when omitted, defaults to ~1 week out (shifted off weekends)

New endpoint: PUT /v1/ads/{adId}/status to pause/resume a single ad.

This is ad-scoped only (does not affect the parent ad set/campaign), and is a thin wrapper around updating the ad status.

Set status to active or paused. {adId} accepts Zernio _id, Meta platformAdId, or the creative’s effective story/media IDs.

Response includes updated (1/0) and skipped (1/0); message is returned when the change is skipped (terminal status or already in target state).

conversation.started webhooks now include SMS conversations via conversation.platform.

This lets you receive “new conversation started” events for SMS in the same platform-agnostic subscription.

New enum value:
• conversation.platform: sms (in addition to existing platforms)

WhatsApp template sends via POST /v1/inbox/conversations now support overriding a media-header template asset per message using headerMedia.

This lets you use a single approved template with an image/video/document header while sending a different asset for each recipient (e.g. a unique invoice PDF), instead of always sending the template’s approved sample asset.

Set headerMedia (JSON body only):
• type: image | video | document (must match the template header type)
• Provide exactly one of link (public URL) or id (Meta media id)
• Optional: filename (document only)

GET /v1/ads/accounts now returns Meta ad account usability flags: selectable and unusableReason.

This lets you filter out ad accounts that can’t currently create/run ads and show a user-friendly reason in your UI.

New fields in accounts[] (Meta only):
• selectable (boolean) — whether the account can create/run ads now
• unusableReason (string|null) — reason when selectable is false; null when selectable

On non-Meta platforms these fields are absent (treat selectable as true).

GET /v1/inbox/conversations/search now searches by contact identity (participant name/username/phone) in addition to message text, returning matching conversations once (message matches included when present).

Contact-identity matches are case-insensitive substrings; they return matchCount=0 and matches=[]. Note: identity matching is not applied when direction is set (incoming | outgoing).

Also updated:
• Searchable platforms now include Twitter/X and Reddit; Bluesky is live-fetched and appears in meta.accountsSkipped
• Response adds conversation.lastMessage (most recent message preview)

Meta placements now support delivering ads on WhatsApp by allowing whatsapp in placements.publisherPlatforms.

This lets you explicitly include WhatsApp inventory when using manual placements (instead of relying on automatic placements).

Set placements.publisherPlatforms to include:
• whatsapp (alongside facebook, instagram, threads, messenger, audience_network)

Applies to:
• POST /v1/ads/create
• POST /v1/ads/ctwa

POST /v1/ads/ctwa now supports manual ad placements via placements.

This lets you restrict CTWA ad delivery to specific Meta surfaces/devices instead of using automatic placements (Meta may still enforce eligibility/co-selection rules and return actionable errors).

Use placements with:
• publisherPlatforms: facebook | instagram | threads | messenger | audience_network
• facebookPositions, instagramPositions, messengerPositions, audienceNetworkPositions, threadsPositions, whatsappPositions
• devicePlatforms: mobile | desktop

GET /v1/usage now includes estimated tax via a new tax field on UsageMetering.

This lets you show an estimated tax amount (computed with Stripe Tax) on top of the window’s net spend (totals.total). tax is null when no billing address is on file, the total is ≤ 0, or the estimate fails.

New fields:
• tax.taxUsd — estimated tax in USD (added on top of totals.total)
• tax.ratePercent — combined rate percentage (nullable)
• tax.jurisdictionLabel — human label like “ES VAT” (nullable)
• tax.reverseCharge — true for EU/UK B2B reverse charge (0 tax added)

Webhooks now support additional event subscriptions for conversations, calls, leads, and WhatsApp.

You can subscribe to these new events via POST /v1/webhooks/settings or PUT /v1/webhooks/settings:
• conversation.started
• call.received, call.ended, call.failed, call.permission_request
• lead.received
• whatsapp.automatic_event

SMS carrier registrations (10DLC) now accept campaign.subUsecases on POST /v1/sms/registrations (2–5 values): 2FA, ACCOUNTNOTIFICATION, CUSTOMERCARE, DELIVERYNOTIFICATION, FRAUDALERT, HIGHEREDUCATION, MARKETING, POLLINGVOTING, PUBLICSERVICEANNOUNCEMENT, SECURITY_ALERT.

For rejected registrations, GET /v1/sms/registrations/{id} may now include campaignContent (messageFlow, sample1, sample2), and POST /v1/sms/registrations/{id}/appeal can include corrected messageFlow/sample1/sample2 along with appealReason.

New billing snapshot endpoint: GET /v1/billing.

It returns the billing “statement” view (plan, current cycle, balance/credits, spend caps, and payment/access status). Use this for billing state; use GET /v1/usage for usage/metering.

Key response blocks:
• plan (includes isUsageBased)
• period (start/end may be null on Stripe)
• balance (null for Stripe; populated for Metronome)
• caps (e.g. xSpendUsedCents, xSpendLimitCents)
• status (e.g. hasAccess, suspended, openInvoiceUrl, declineReason)

Also: GET /v1/usage is now dual-mode.
• Default (no metering params): same snapshot as before
• Metering mode (billed spend by product) when passing any of: range, granularity, from, to

Metering params:
• range: cycle | prev-cycle | 7d | 14d | 30d | 3mo | 12mo | custom
• granularity: day | month | total
• from/to required when range=custom

Stripe accounts calling metering mode receive { "supported": false }.

POST /v1/whatsapp/business-profile/photo now accepts an image via URL in addition to multipart upload.

You can either upload bytes with multipart/form-data (file) or send application/json with url; we fetch the image server-side and upload the bytes to Meta.

New JSON body option:
• accountId
• url (public https image URL; must resolve directly without redirects)

New response to handle:
• 422 when the profile photo is locked for WhatsApp coexistence numbers (must be managed in the WhatsApp Business app).

POST /v1/sms/registrations now enforces additional required fields for 10DLC registrations.

This can break existing integrations that submit brand/campaign without the newly-required fields.

For brand, these fields are now required: website, street, city, state, postalCode (in addition to existing required fields).

For campaign, sample2 is now required and must be distinct from sample1.

Webhook post events now echo back your post’s free-form metadata (when provided at create time) in:
• WebhookPayloadPost.post.metadata
• WebhookPayloadPostPlatform.post.metadata

Google Business Profile posts: offer.offerType has been removed from GoogleBusinessPlatformData.

If you were sending offerType (previously OFFER or BUYONEGET_ONE), remove it from your payloads and use the remaining offer fields instead:
• redeemOnlineUrl
• termsConditions
• couponCode

The supported breakdowns values were reduced on analytics endpoints.

If you request breakdowns that are no longer supported, your call may fail (400) or no longer return those breakdowns.

Affected endpoints:
• GET /v1/ads/{adId}/analytics: Meta breakdowns now limited to age, gender, country, publisherplatform, deviceplatform, region (removed: platformposition, impressiondevice, videoasset, imageasset, bodyasset, titleasset; also removed aliases placement and singular breakdown)
• GET /v1/ads/campaigns/{campaignId}/analytics: Meta breakdowns now limited to age, gender, country, publisherplatform, deviceplatform, region, platformposition, impressiondevice, videoasset, imageasset, bodyasset, titleasset (removed aliases placement and singular breakdown)

GET /v1/analytics now supports a new metric: follows.

You can read analytics.follows in responses (Instagram feed posts and stories only: organic accounts that started following from this post; 0 for reels and other platforms).

You can also sort analytics results by sortBy = follows (enum now includes: date, engagement, impressions, reach, likes, comments, shares, saves, clicks, views, follows).

GET /v1/ads/{adId}/analytics and GET /v1/ads/campaigns/{campaignId}/analytics now validate breakdown dimensions and will return 400 for unknown values.

This prevents silent/partial breakdown results and makes invalid breakdowns requests fail fast with a supported-values list.

Updates:
• breakdowns: unknown dimensions now return 400 (instead of being ignored)
• placement is accepted as an alias for publisher_platform
• breakdown (singular) is also accepted

New Meta breakdown options include: platformposition, impressiondevice, videoasset, imageasset, bodyasset, titleasset.

You can now update saved_targeting audiences via PUT /v1/ads/audiences/{audienceId}.

This lets you change an audience’s name, description, or fully replace its spec (no merge). Uploaded/derived audiences aren’t updatable and return 422.

Request body (send at least one): name, description, spec

Also: GET /v1/ads/audiences now returns accountId for type=savedtargeting items, and DELETE /v1/ads/audiences/{audienceId} clarifies that savedtargeting deletes only the local record (it exists only on Zernio).

Ads reporting endpoints may now return 202 when part of the requested date range isn’t ingested yet.

When this happens, the response includes currently-available data plus backfillPending: true, and a Retry-After header with the recommended poll interval. Repeat the same request until it returns 200 with the full range.

Applies to:
• GET /v1/ads
• GET /v1/ads/tree
• GET /v1/ads/timeline
• GET /v1/ads/campaigns/{campaignId}/analytics
• GET /v1/ads/{adId}/analytics

Also, POST /v1/posts 403 responses now include a stable code to distinguish causes:
• ACCOUNT_DISCONNECTED
• PROFILEOVERLIMIT

WhatsApp inbox messages now support commerce interactive messages (products, product lists, catalog messages, and carousels) via interactive on POST /v1/inbox/conversations/{conversationId}/messages.

This lets you send catalog-driven messages and receive cart submissions / product inquiries back in webhooks.

New interactive.type values:
• product, productlist, catalogmessage, carousel

Webhook message.received metadata adds:
• metadata.order (cart submitted from commerce messages)
• metadata.referredProduct (product inquiry context)

Note: interactive messages are session messages (must be sent within WhatsApp’s 24-hour window).

GET /v1/inbox/mentions now returns additional LinkedIn author details in each mention.

You can display richer mention attribution (when available) without extra profile resolution on your side.

New fields:
• authorName - display name resolved from authorUrn (can be null)
• authorUsername - LinkedIn vanity name (can be null)
• authorPicture - author profile picture URL (can be null; CDN URLs may expire, so fetch promptly)

Meta ad metrics now include video performance fields in AdMetrics (and therefore AdDailyMetrics).

You can track video starts, thruplays, 30s views, completion percentiles, and average watch time for hook/hold/drop-off analysis. These fields are Meta video ads only (0 for non-video ads and other platforms).

New fields:
• videoPlayActions
• video30SecWatchedActions
• videoThruplayWatchedActions
• videoP25WatchedActions, videoP50WatchedActions, videoP75WatchedActions, videoP95WatchedActions, videoP100WatchedActions
• videoAvgTimeWatchedActions

Note: in AdDailyMetrics, videoAvgTimeWatchedActions is recomputed per day; don’t sum or plain-average it across days (the range value is play-weighted).

New endpoint: GET /v1/inbox/conversations/search.

You can now search message text across stored inbox conversations and get back matching conversations with up to 3 most-recent matching messages per conversation (useful for finding threads by topic or filtering by sent/received).

Key params:
• query (required, 2–200 chars)
• direction: incoming | outgoing
• platform: facebook | instagram | telegram | whatsapp | sms
• profileId, accountId
• limit (1–50, default 20), cursor

Response includes data[].conversation, matchCount, matches (up to 3), plus pagination and meta.accountsSkipped for connected accounts on live-fetched platforms that can’t be searched.

Requires Inbox addon (403 if missing).

Inbox webhook account context now includes optional profileId in InboxWebhookAccount.

Use profileId (workspace/profile ID) to route or filter inbox webhooks by workspace. It may be omitted for the shared WhatsApp sandbox account or when the account has no resolvable profile.

New API surfaces for Usage, Calls, Voice (PSTN), SMS, and Phone Numbers are now available, including a unified call history and a new usage “hub”. Several older WhatsApp-prefixed paths are now deprecated aliases of the new canonical endpoints.

Usage snapshot + breakdowns:
• GET /v1/usage (replaces GET /v1/usage-stats; same contract)
• GET /v1/usage/calls with optional groupBy: day | number | channel and filters since, until, channel (whatsapp | pstn), number
• GET /v1/usage/sms with optional groupBy: day | number and filters since, until, number

Unified call history (WhatsApp + PSTN) + recordings:
• GET /v1/calls filters: channel (whatsapp | pstn), status (ringing | answered | ended | failed), direction (inbound | outbound), number, search, cursor pagination via before + nextCursor
• GET /v1/calls/{id}
• GET /v1/calls/{id}/recording (default 302; as=json returns { url })

WhatsApp call history improvements:
• GET /v1/whatsapp/calls now supports cursor pagination via before and returns nextCursor
• POST /v1/whatsapp/calls now supports idempotent retries via Idempotency-Key

PSTN Voice calling (new):
• POST /v1/phone-numbers/{id}/voice configure inbound routing (forwardTo), recording/transcription, voicemail, business hours, IVR, blocklist
• DELETE /v1/phone-numbers/{id}/voice
• Call control: POST /v1/voice/calls (supports Idempotency-Key), GET /v1/voice/calls, GET /v1/voice/calls/{id}, POST /v1/voice/calls/{id}/end, POST /v1/voice/calls/{id}/transfer, GET /v1/voice/calls/{id}/recording (as=json), GET /v1/voice/calls/estimate
• Browser softphone handshake: POST /v1/voice/calls/web then POST /v1/voice/calls/web/dial

SMS (new):
• POST /v1/sms/messages (supports Idempotency-Key; MMS via mediaUrls)
• GET /v1/sms/lookup (carrier + line type mobile | landline | voip | toll-free | unknown)
• Opt-outs export: GET /v1/sms/opt-outs with format: json | csv
• US carrier registration flows: GET/POST /v1/sms/registrations, GET /v1/sms/registrations/{id}, POST /v1/sms/registrations/{id}/verify-otp, POST /v1/sms/registrations/{id}/appeal, POST /v1/sms/registrations/share

Phone Numbers (new canonical resource):
• GET /v1/phone-numbers, GET /v1/phone-numbers/{id}, DELETE /v1/phone-numbers/{id}
• Purchase + inventory: POST /v1/phone-numbers/purchase, GET /v1/phone-numbers/countries, GET /v1/phone-numbers/available, GET /v1/phone-numbers/availability
• Regulated KYC: GET/POST /v1/phone-numbers/kyc, POST /v1/phone-numbers/kyc/upload-document, POST /v1/phone-numbers/kyc/validate-address, POST /v1/phone-numbers/kyc/share, POST /v1/phone-numbers/kyc/review-packet, remediation via GET/POST /v1/phone-numbers/{id}/remediate
• Port-in: GET /v1/phone-numbers/port-in, POST /v1/phone-numbers/port-in, POST /v1/phone-numbers/port-in/check, POST /v1/phone-numbers/port-in/documents, DELETE /v1/phone-numbers/port-in/{id}

WhatsApp Calling config is now number-keyed:
• New canonical sub-resource: GET/POST/PATCH/DELETE /v1/phone-numbers/{id}/whatsapp/calling
• Existing /v1/whatsapp/phone-numbers/{id}/calling endpoints are deprecated aliases

Deprecated aliases (no immediate break, but new integrations should switch):
• GET /v1/usage-stats → GET /v1/usage
• Many /v1/whatsapp/phone-numbers/* paths → corresponding /v1/phone-numbers/* paths

Webhooks now support TikTok URL backfill via the new event post.tiktok.url_resolved.

This fires when a published TikTok post’s public URL is resolved/backfilled, using the same payload shape as post.platform.published/post.platform.failed (see WebhookPayloadPostPlatform).

Subscribe by including post.tiktok.url_resolved in events when calling POST /v1/webhooks/settings or PUT /v1/webhooks/settings.

Also clarified for PUT /v1/posts/{postId}: to promote a draft to scheduled you must send isDraft: false together with scheduledFor (or publishNow: true / queuedFromProfile). If isDraft is omitted, the post keeps its current draft status.

Webhook payloads now include account.accountId (same value as account.id) as a canonical field for filtering/routing events.

This makes it easier to consistently filter all webhook events by a single field (e.g. route staging vs production by account) while keeping account.id for backward compatibility.

New field:
• account.accountId

Added to these webhook payloads:
• comment.received
• lead.received
• review.new
• review.updated
• post.external.created, post.external.updated, post.external.deleted
• inbox webhook payloads via InboxWebhookAccount

Webhook post events now include the connected social account per platform target via post.platforms[].accountId.

This lets you route/attribute webhook deliveries by the specific SocialAccount used for each platform publish (useful when a single post spans multiple accounts).

New field:
• WebhookPayloadPost.post.platforms[].accountId
• WebhookPayloadPostPlatform.post.platforms[].accountId (on post.platform.published / post.platform.failed; see also the top-level account block there)

WhatsApp KYC form spec now returns an optional audience per requirement in GET /v1/whatsapp/phone-numbers/kyc.

This lets you show/collect only the fields that apply to the end-user type (business vs individual) and avoid submitting both sets of requirements.

New field: fields[].audience = business | individual | null (applies to both).

GET /v1/connect/pending-data now supports Pinterest board selection in headless OAuth flows.

For Pinterest (in addition to LinkedIn orgs and Snapchat profiles), the OAuth redirect returns pendingDataToken and you can fetch the full selection payload via token.

Use token (query) from the redirect, and read selectionType (enum: organizations, pages, boards, locations, profiles) to determine which selection array to consume (e.g. boards for Pinterest).

Workflow send_message nodes now allow omitting interactive.type; it will be inferred from the interactive payload shape.

This makes interactive message configs simpler, but payloads with neither type nor an inferable shape are now rejected.

Applies to send_message.config with messageType = interactive (WhatsApp-only).

POST /v1/invite/tokens now supports inviting users with the new admin role via role.

Use role=admin to grant team-management permissions (invite/remove members, change roles and access) without billing, ownership transfer, or account deletion permissions.

role enum is now: admin, member, billing_admin, viewer.

Note: readOnly (deprecated) can’t be combined with role=billing_admin or role=admin.

WhatsApp document sends via URL now support setting the displayed filename using attachmentName on POST /v1/inbox/conversations/{conversationId}/messages.

This lets you control the recipient-visible file name for attachmentUrl document messages (otherwise WhatsApp derives it from the URL and may show “Untitled”).

Use:
• attachmentType: file
• attachmentUrl: (public URL)
• attachmentName: e.g. Report.pdf

Applies to WhatsApp only; ignored for image/video/audio and for multipart binary uploads.

New endpoint POST /v1/posts/sync-external lets you sync/verify external (non-Zernio) posts on demand, so a just-published post can be retrieved within seconds instead of waiting for the background sync.

Use it to confirm a user-submitted post exists by sending accountId plus either url or postId.

Request body:
• accountId (required)
• url (optional)
• postId (optional)

Response:
• synced.postsFound, synced.postsSynced, synced.skipped
• If url/postId provided: found + post (or null)
• If no locator provided: posts (recent external posts)

Returned posts use ExternalPostSummary (includes platform, platformPostId, platformPostUrl, publishedAt, and basic analytics like likes/comments).

WhatsApp Business Profile now supports managing business usernames via new endpoints.

You can fetch the current username + approval state, claim/transfer a username, release it, and retrieve available suggestions.

New endpoints:
• GET /v1/whatsapp/business-profile/username (accountId query) → returns username (nullable) and status (approved/reserved/none)
• POST /v1/whatsapp/business-profile/username body: accountId, username, optional transferAction (none/force_transfer)
• DELETE /v1/whatsapp/business-profile/username body: accountId
• GET /v1/whatsapp/business-profile/username/suggestions (accountId query) → returns suggestions[]

On username claim failures, expect error codes like whatsappusernameunavailable, whatsappusernameineligible, or whatsappusernametransfer_required.

New endpoint GET /v1/inbox/mentions is available to list mentions of your connected organization accounts delivered via platform webhooks.

Currently supports LinkedIn organization mentions and requires the Inbox addon.

Key query params:
• accountId (filter by social account ID)
• profileId (filter by profile ID)
• sortOrder (asc | desc, default desc)
• limit (1–100, default 25)
• cursor (pagination)

Response includes data items with id, platform (linkedin), content, permalink, authorUrn, organizationalEntity, publishedAt, plus pagination (hasMore, cursor).

New endpoint GET /v1/ads/campaigns/{campaignId}/analytics returns campaign-level analytics in one call (summary metrics, daily[] timeline, and optional Meta demographic breakdowns).

Use query params fromDate, toDate (defaults to last 90 days; max 730 days) and optional platform to disambiguate IDs. For Meta-only breakdowns, pass breakdowns as a comma-separated list: age, gender, country, publisherplatform, deviceplatform, region, platformposition, impressiondevice, videoasset, imageasset, bodyasset, titleasset.

GET /v1/ads/tree now supports daily trends in the same response: set timeIncrement=1 to add daily[] metrics series, and control where it appears with dailyLevel = campaign (default) | adset | ad.

Instagram Trial Reels are now identifiable per platform target in post responses.

When an Instagram reel is created as a Trial (via platformSpecificData.trialParams), the corresponding PlatformTarget may include:
• isTrialReel (boolean) — present and true only for trial reels
• trialGraduationStrategy — MANUAL | SS_PERFORMANCE (present only when isTrialReel is true)

Use these fields to segment trial reels in analytics; note this reflects creation-time intent (Instagram doesn’t expose a readable trial flag).

Removed endpoint GET /v1/accounts/{accountId}/posts.

This endpoint previously returned recent posts for a connected social account by calling the platform API directly (Facebook, Instagram, X/Twitter, Bluesky, Threads, YouTube, LinkedIn, Reddit, TikTok, Pinterest).

If you were using YouTube filtering, note that excludeUnlisted is no longer available via this route.

New endpoint GET /v1/accounts/{accountId}/posts lists recent posts for a connected social account by calling the platform API directly (Facebook, Instagram, X/Twitter, Bluesky, Threads, YouTube, LinkedIn, Reddit, TikTok, Pinterest).

You can optionally filter YouTube results to avoid returning internal/unlisted content with excludeUnlisted.

Use:
• accountId (path)
• excludeUnlisted (query, boolean; YouTube only)

Also note a targeting spec change: TargetingSpec.cities[].distanceUnit is now TargetingSpec.cities[].distanceunit (with radius still supported). excludedLocations now supports excluded cities with optional radius + distanceunit, plus excluded places, neighborhoods, and excluded customLocations.

Instagram posts now support AI-generated media self-disclosure via isAiGenerated in platformSpecificData.

When isAiGenerated is true, Instagram labels the post as containing AI-generated media (this is for media, not AI-written captions).

Set:
• isAiGenerated (boolean, default false)

Applies to feed posts, Reels, Stories, and carousels.

POST /v1/whatsapp/phone-numbers/kyc now supports provisioning multiple same-country numbers in a single KYC submission via quantity.

Set quantity (default 1, min 1, max 5) to request several numbers; the same verification covers all of them and each number is billed only when it activates (best-effort if some orders fail).

Response now includes numbers (array) with all provisioned numbers. phoneNumber remains and represents the first/primary number for backward compatibility.

status remains: kycsubmitted | kycreused | kycalreadysubmitted

WhatsApp phone number provisioning now supports creating a hosted KYC link via POST /v1/whatsapp/phone-numbers/kyc/share.

This generates a single-use, 7-day link your end customer can complete without a Zernio login; once submitted, the number provisions under your account (only for regulated/KYC countries).

Request fields:
• profileId (required)
• country (required, ISO-2; non-KYC countries return 400)
• branding (optional: companyName, logoUrl, brandColor)
• redirect_url (optional; on success appends kyc=submitted and country=<ISO-2>)

Response fields:
• url
• token
• expiresAt

To react when the form is completed, subscribe webhooks to the new event: whatsapp.number.kyc_submitted (available in POST/PUT /v1/webhooks/settings).

Comment webhooks (comment.received) now include an optional comment.attachment object for Facebook graphic-only comments (sticker, GIF, photo).

This lets you detect and render comments that have no text content; note Meta URLs may be ephemeral, so fetch promptly.

Key fields:
• comment.attachment.type (required)
• comment.attachment.imageUrl
• comment.attachment.url

Meta boosts via POST /v1/ads/boost now support raw Meta-native targeting with rawTargeting.

Use rawTargeting to pass a Meta targeting spec verbatim (snakecase like geolocations, customaudiences, excludedcustomaudiences, flexiblespec, targeting_automation) to target specific custom/lookalike audiences or clone targeting exactly.

Key rule: rawTargeting is mutually exclusive with targeting (sending both returns 422).

POST /v1/ads/create now supports additional Meta geo targeting controls.

You can target more precise location types and explicitly exclude locations when creating Meta ads.

New fields:
• places (Meta geoType place)
• neighborhoods (Meta geoType neighborhood)
• excludedLocations with countries, regions, cities, zips

POST /v1/ads/lead-forms adds richer Meta Instant Form configuration.

New fields:
• formType: MOREVOLUME | HIGHERINTENT | RICH_CREATIVE
• blockDisplayForNonTargetedViewer
• allowOrganicLeadGen
• questionPageCustomHeadline
• contextCard (title, content, style: LISTSTYLE | PARAGRAPHSTYLE, buttonText, coverPhoto)

GET /v1/ads/targeting/search geo search now supports geoType=all and returns coordinates.

Use dimension=geo with geoType=all to search across all geo types in one call, and read latitude / longitude from results (when available).

Moving an account to another profile via PATCH /v1/accounts/{accountId} can now return 409 when the target profile already has an account on the same platform.

This enforces the rule that a profile can hold only one account per platform.

Handle the new response:
• 409 - target profile already has an account of the same platform (profileplatformconflict)

GET /v1/ads/lead-forms/{formId} now returns a fully detailed form object (enough to duplicate the form via POST /v1/ads/lead-forms).

Key fields include form.status (ACTIVE/ARCHIVED), questions, thankyoupage, and context_card.

Geo targeting search via GET /v1/ads/targeting/search now supports additional geoType values when dimension=geo: subcity, neighborhood, place, metroarea, geomarket (in addition to country, region, city, zip).

Inbox conversations now include ad-click attribution via a new metadata object in responses from GET /v1/inbox/conversations and GET /v1/inbox/conversations/{conversationId}.

This lets you identify when a conversation started from a click-to-message ad (vs organic) and store the associated ad identifiers/details.

New field:
• metadata (object, nullable) — only present for ad-originated conversations; absent for organic

Common keys you may see in metadata:
• WhatsApp CTWA: ctwaclid, ctwasourceid, ctwasourceurl, ctwaheadline, ctwasourcetype, ctwacapturedat
• Meta CTM/CTD: metaadid, metaadtitle, metaadsource, metaadtype, metaadref, metaadcapturedat, metaadphotourl, metaadvideourl, metaadpostid, metaadproductid, metaadflowid

Analytics post items now include isAd in AnalyticsListResponse.posts[].

This lets you distinguish ad creatives from organic posts in analytics results (currently only available for LinkedIn posts; false when unavailable).

New field:
• isAd (boolean) — true for ad creatives, otherwise false

Meta ads created via POST /v1/ads/create now allow combining manual placements with rawTargeting.

This lets you clone an ad set’s full Meta-native targeting spec via rawTargeting while still overriding placements using the structured placements object.

When both are set, placements is converted to Meta snake_case and merged into rawTargeting before sending to Meta.

Key fields:
• rawTargeting (Meta TargetingSpec, snake_case)
• placements.publisherPlatforms: facebook, instagram, threads, messenger, audience_network
• placements.facebookPositions, placements.instagramPositions, placements.messengerPositions, placements.audienceNetworkPositions, placements.threadsPositions, placements.whatsappPositions, placements.devicePlatforms: mobile/desktop

POST /v1/ads/create now supports more control over Meta publish state and creative reuse.

You can stage Meta campaigns/ads more safely (e.g., create everything paused, or pause just the campaign while keeping the ad set ready), and you can now attach new ads using an existing creative without resending copy/media.

New/updated fields:
• status (ACTIVE | PAUSED) now explicitly controls desired publish state; in attach mode (adSetId) it affects only the new ad
• campaignStatus (ACTIVE | PAUSED) lets you set campaign state independently on the legacy create shape (ignored when existingCampaignId is set)
• existingCreativeId can now be used with adSetId to attach an ad that reuses an existing Meta creative (copy/media fields can be omitted)

POST /v1/ads/create now supports additional Meta-only creation options: you can create ads/ad sets paused, add a new ad set under an existing campaign, and/or reuse an existing creative.

This enables safer launches (no immediate spend) and easier multi-ad-set testing while keeping creatives consistent.

New request fields:
• status: ACTIVE | PAUSED
• existingCampaignId (Meta only; mutually exclusive with adSetId and creatives[])
• existingCreativeId (Meta only; mutually exclusive with creatives[], dynamicCreative, placementAssets)

LinkedIn posts now support quote-reshare via reshareUrl in LinkedInPlatformData.

Set reshareUrl to a LinkedIn post link ("Copy link to post") or a urn:li:share / urn:li:ugcPost / urn:li:groupPost URN. The published post becomes a repost with your content as commentary and the original post embedded underneath.

Notes:
• reshareUrl is mutually exclusive with media
• Works on personal profiles and organization pages

Error responses are now more structured for programmatic handling: ErrorResponse adds type, code, param, platform, and platformError (raw upstream payload when type is platform_error).

type can be: invalidrequesterror, authenticationerror, permissionerror, notfound, ratelimiterror, platformerror, api_error.

POST /v1/ads/conversions now supports TikTok conversions (platform tiktokads).

You can now relay OFFLINE conversion events to TikTok via the Offline Events API. Use destinationId as the TikTok Offline Event Set ID, and note each event must include an email or phone.

Key details:
• accountId now accepts: metaads, googleads, linkedinads, tiktokads
• Response platform enum now includes tiktokads

GET /v1/accounts/{accountId}/conversion-destinations also now supports tiktokads (platform enum includes tiktokads).

GET /v1/ads/tree adds campaignId (platform campaign id) to restrict the tree to a single campaign, independent of pagination.

Google Ads conversion destination creation via POST /v1/accounts/{accountId}/conversion-destinations is now effectively idempotent by name.

If a conversion action with the same name already exists, the API will reuse it and return the same response as a fresh create. If the same name is used with a different type (category), the API now returns 409 with error code IDEMPOTENCY_CONFLICT.

Key fields:
• name
• type

New response:
• 409 (Google Ads only) — IDEMPOTENCY_CONFLICT

POST /v1/accounts/{accountId}/conversion-destinations now supports creating conversion destinations for Google Ads in addition to LinkedIn.

You can create a Google Ads conversion action (created as UPLOAD_CLICKS for offline uploads). Standard event names are mapped automatically, and actions default to secondary unless you opt in.

Key Google Ads fields:
• countingType: MANYPERCLICK | ONEPERCLICK
• primaryForGoal: true | false (default false)

Notes:
• accountId can now be linkedinads or googleads
• Creation is not idempotent — retries can create duplicates
• 201 response platform now includes linkedinads | googleads

WhatsApp regulated-number KYC reuse now supports choosing which prior approved verification to reuse.

GET /v1/whatsapp/phone-numbers/kyc adds reusable.options (newest first), listing all approved verifications (each with fromPhoneNumber + details).

When submitting with reuse, POST /v1/whatsapp/phone-numbers/kyc adds reuseFrom to select the verification to reuse (set to reusable.options[].fromPhoneNumber). Omit reuseFrom to use the newest; no match returns 409.

GET /v1/whatsapp/phone-numbers/kyc now returns a human-readable summary when a reusable KYC verification is available.

When reusable.available is true, you can show what verification is already on file (best-effort; may be empty if provider lookup fails) and let users skip re-entering the form.

New field: reusable.details (array of { label, value }) alongside reusable.fromPhoneNumber.

GET /v1/connect/{platform}/ads now supports ad sync scoping via adAccountId/adAccountIds across more ads platforms (not just Meta).

You can limit discovery/sync to specific ad accounts for facebook/instagram (Meta), linkedin, googleads, and twitter. Changing the scope will also remove already-synced ads from any de-scoped ad accounts.

Use:
• adAccountId - single ad account id (platform-specific format)
• adAccountIds - multiple ids (repeat param or comma-separated)

Notes:
• tiktok ignores these params (advertisers are scoped during OAuth)
• pinterest ignores these params (no ads discovery)
• Meta ids (act_<digits>) are validated against the connected token; unreachable ids return 400
• Omitting both adAccountId and adAccountIds keeps the previously persisted scope unchanged

Broadcast recipient results now include a plain-language failure reason via errorExplanation on GET /v1/broadcasts/{broadcastId}/recipients.

This helps you interpret WhatsApp errorCode values (e.g. opt-out / re-engagement required) without maintaining your own mapping.

Use:
• recipients[].errorCode (integer, nullable)
• recipients[].errorExplanation (string, nullable; null if unmapped — fall back to error)

Webhooks for delivery status now also include error.explanation in WebhookPayloadMessageDeliveryStatus (populated on event=message.failed).

Google campaign objects now include advertisingChannelType in AdCampaign and AdTreeCampaign.

This exposes the raw Google Ads campaign.advertisingchanneltype so you can distinguish campaign serving surfaces (e.g. Search vs Performance Max) when syncing/reporting.

New field:
• advertisingChannelType (string, nullable) — Google-only (e.g. SEARCH, PERFORMANCEMAX, VIDEO, DEMANDGEN, DISPLAY, SHOPPING)

WhatsApp interactive messages now support voice call buttons when sending inbox messages via POST /v1/inbox/conversations/{conversationId}/messages.

This lets you render WhatsApp’s native “call” CTA in-chat (requires WhatsApp Business Calling enabled on the sending number). Optional attribution data can be echoed back on the calls webhook.

Use interactive.type = voicecall and interactive.action.name = voicecall. Optional interactive.action.parameters:
• display_text
• ttl_minutes
• payload

Also, GET /v1/whatsapp/calling now returns callDeepLink (nullable) for the public https://wa.me/call/<number> deep link when calling is enabled.

YouTube analytics now supports video retention curves via GET /v1/analytics/youtube/video-retention.

This returns an aggregated (not per-day) audience retention curve for a single video, plus durationSeconds so you can render the curve on a time axis.

Call with:
• videoId
• accountId
• optional startDate, endDate

Response highlights:
• retentionCurve[] points with elapsedVideoTimeRatio, audienceWatchRatio (can be > 1), relativeRetentionPerformance
• empty retentionCurve for low-view / not-yet-processed videos (2–3 day delay)

Requires yt-analytics.readonly; if missing you may get 412 with code=youtubeanalyticsscope_missing.

Also added to GET /v1/analytics/youtube/daily-views responses:
• top-level durationSeconds
• per-day averageViewPercentage (can exceed 100; don’t clamp client-side)

GET /v1/analytics/daily-metrics now supports engagement attribution via a new query param attribution.

This lets you choose whether daily totals are attributed to the post’s publish date or bucketed by the day engagement was actually received (engagement-over-time).

Use attribution:
• publish (default) — attribute each post’s lifetime total to its publish date
• received — attribute per-day engagement increases to the day they occurred

WhatsApp adds blocked-status lookup for a single contact via GET /v1/whatsapp/block-users/status.

This returns a definitive blocked state using Zernio’s blocklist mirror (kept in sync by block/unblock; first call per account may backfill from Meta’s full list).

Required query params:
• accountId
• user (consumer wa_id or E.164 phone; leading + optional)

Response 200:
• blocked (boolean)

POST /v1/whatsapp/calls now supports sending the WhatsApp call-consent prompt via a new optional action parameter.

Use this to request consumer permission before placing a Business-Initiated Call; the consumer must tap Allow before start_call is permitted (Meta rate-limits prompts and requires an open 24h service window).

Set:
• action: sendcallpermission_request (omit action to place a call)
• bodyText: optional text shown with the consent prompt (max 1024 chars)

WhatsApp now supports managing your blocklist via /v1/whatsapp/block-users.

You can list blocked users, block up to 1,000 users per request, and unblock in batches (per-user failures are returned without failing the whole request).

New endpoints:
• GET /v1/whatsapp/block-users with accountId, optional limit, after (cursor pagination via nextCursor)
• POST /v1/whatsapp/block-users body: accountId, users (1..1000)
• DELETE /v1/whatsapp/block-users body: accountId, users (1..1000)

WhatsApp interactive messages now also support location requests in POST /v1/inbox/conversations/{conversationId}/messages via interactive.type = locationrequestmessage (and action can be omitted; defaults to {"name":"send_location"}).

Meta catalog ads are now supported via goal = catalog_sales on POST /v1/ads/create.

This lets you create Advantage+ catalog ads (e.g. vehicle inventory) using a Meta product catalog + product set; Meta renders the visuals per catalog item (no imageUrl/video sent).

Discover inputs with:
• GET /v1/ads/catalogs (accountId, adAccountId)
• GET /v1/ads/catalogs/{catalogId}/product-sets (catalogId, accountId)

Create the ad with:
• goal: catalog_sales
• promotedObject.productSetId
• promotedObject.pixelId
• promotedObject.customEventType

Notes: catalog_sales is single-shape only (no creatives[], adSetId, dynamicCreative, or placementAssets).

GET /v1/whatsapp/phone-numbers now also returns connected (bring-your-own) WhatsApp numbers in a separate connected array.

This lets you list Embedded Signup–linked WABA numbers alongside purchased numbers (which remain in numbers). Connected numbers aren’t provisioned or billed by Zernio and use accountId for messaging/inbox endpoints.

New response field: connected[] with:
• accountId
• phoneNumber
• displayName
• profileId
• connectedAt

Included only on the default view and when status=active.

WhatsApp phone number purchase now supports idempotent retries and duplicate-purchase protection on POST /v1/whatsapp/phone-numbers/purchase.

Use purchaseIntentId (optional) as an idempotency key: retry with the same value and, if a number was already bought, the API returns { status: "already_purchased", numberId, phoneNumber } instead of provisioning a second number.

A second purchase within 10 minutes is now rejected with 409 and code PURCHASE_VELOCITY. To confirm an intentional additional purchase (e.g. bulk provisioning), set allowMultiple to true.

New endpoint: GET /v1/accounts/{accountId}/gmb-attribute-metadata.

You can now fetch Google Business Profile attribute metadata (valid attribute names, value types, and allowed enum values) before reading/writing via gmb-attributes.

Query modes (mutually exclusive):
• Location mode: locationId (or omit to use the account’s stored selectedLocationId)
• Category mode: categoryName (must start with categories/) + regionCode (optional languageCode)

Pagination: pageSize (1–200) and pageToken.

Response includes attributeMetadata[] with parent, valueType (e.g. BOOL, ENUM, URL, REPEATED_ENUM), displayName, repeatable, deprecated, and valueMetadata[] (enum options), plus nextPageToken when more results are available.

Meta video ads created via POST /v1/ads/create no longer require a thumbnail.

You can now omit video.thumbnailUrl and Zernio/Meta will auto-generate the poster frame using Meta’s preferred video thumbnail (same candidates as Ads Manager). Provide it only if you need an exact poster frame.

Applies to:
• Top-level video (legacy + attach shapes): video.url required, video.thumbnailUrl optional
• creatives[].video (Meta multi-creative): video.url required, video.thumbnailUrl optional

POST /v1/ads/create now supports Meta link descriptions via a new description field.

This lets you set the secondary link text on Facebook/Instagram ads instead of relying on Meta scraping OpenGraph data.

Use:
• description (Meta only) — applies to legacy + attach + placementAssets
• creatives[].description (Meta multi-creative) — per-ad override; falls back to top-level description

Also clarified for Meta lead ads: when using adSetId (attach shape) into a lead ad set, you must pass leadGenFormId on every attached ad.

Invite creation now supports a dedicated read-only role via role on POST /v1/invite/tokens.

Use role to control access level:
• member
• billing_admin
• viewer - read-only (no publish/edit/delete/connect)

The readOnly field is now deprecated. If readOnly=true, the invite is created with role=viewer (and it can’t be combined with role=billing_admin).

Webhooks now support a new WhatsApp number event: whatsapp.number.action_required.

Subscribe to this event to be notified when a WhatsApp number needs additional action to proceed.

Add it to events when creating/updating a webhook via POST /v1/webhooks/settings or PUT /v1/webhooks/settings:
• events: ["whatsapp.number.action_required", ...]

Invite token creation now supports assigning an org role and issuing read-only invites via POST /v1/invite/tokens.

Use role to grant org-level permissions (member | billing_admin, default member), and readOnly to restrict the invitee to view-only access within their scope (default false).

WhatsApp template buttons updated: WhatsAppTemplateButton now supports a new button type value copy_code, and text is no longer required for all button types.

This enables WhatsApp marketing “copy code” buttons where the label is fixed by WhatsApp, and the coupon code is provided via example.

Key changes:
• type enum now includes: quickreply, url, phonenumber, otp, copy_code, flow, mpm, catalog
• text: required for all types except copy_code
• example is now string or string[] (URL buttons: string[]; copy_code: coupon code as string)

Meta Lead Gen ads created via POST /v1/ads/create now support Dynamic Creative using dynamicCreative together with goal=lead_generation.

You can run Meta’s multi-text / multi-asset optimization ("Multiple Text Options") on instant-form lead ads; Zernio will create the required Dynamic Creative ad set automatically and attach the form for you.

Use:
• goal=lead_generation
• leadGenFormId=<form_id>
• dynamicCreative.imageUrls (send 1+; send a single entry if you only want multi-text)
• Optional variations: dynamicCreative.titles, dynamicCreative.bodies, dynamicCreative.descriptions, dynamicCreative.linkUrls
• Required: dynamicCreative.callToActionTypes (e.g. LEARNMORE, SIGNUP, DOWNLOAD, REGISTER, BUY_NOW)

X (Twitter) posts now support additional labeling and media safety controls via platformSpecificData.

You can label posts as paid promotions or AI-generated media, and mark attached media with sensitive-content warnings.

New fields in TwitterPlatformData:
• paidPartnership (boolean)
• madeWithAi (boolean)
• sensitiveMedia with adultContent, graphicViolence, other (booleans; requires media)

Reddit posts now support additional post options via platformSpecificData.

New fields in RedditPlatformData:
• flairText (string; ignored if flairId is set)
• nsfw (boolean)
• spoiler (boolean)
• sendreplies (boolean)

GET /v1/accounts now supports filtering by connection status via the new status query param.

This lets you fetch only healthy accounts or only accounts that need reconnection (matching the dashboard reconnection check). Pagination totals reflect the filtered result set when used with page/limit.

Use status:
• connected
• disconnected

Meta Lead Gen ads created via POST /v1/ads/create now support per-placement creative using placementAssets.

You can pin different image/video assets to placement groups (e.g. Stories/Reels vs Feed) while still attaching a Lead Gen form via leadGenFormId.

Use:
• goal=lead_generation
• leadGenFormId
• placementAssets with defaultImageUrl or defaultVideoUrl + rules[].placements

Note: dynamicCreative is still not compatible with goal=lead_generation.

Meta ads tracking-tag updates are now simpler on PATCH /v1/ads/{adId}/tracking-tags: you can send urlTags alone and Zernio will preserve the existing creative verbatim while rebuilding/repointing the ad.

This removes the previous requirement to provide the full Meta creative payload just to add/update click-URL tags. For creatives where Meta strips objectstoryspec (e.g. share/page-post/dark/asset_feed), you may still get 422 and need to include creative explicitly.

Key fields:
• urlTags (Meta)
• creative (Meta, optional; required only when preservation isn’t possible)
• trackingUrlTemplate, finalUrlSuffix (Google)
• dynamicValueParameters, customValueParameters (LinkedIn)

Meta ads created via POST /v1/ads/create now support explicitly setting the ad set optimization goal via optimizationGoal.

This lets you override the default optimization derived from goal (e.g. traffic defaulting to LINKCLICKS) and pass a Meta-native optimizationgoal value directly; Meta will validate and reject incompatible combinations.

Use optimizationGoal (Meta only), e.g. LANDINGPAGEVIEWS, LINKCLICKS, REACH, IMPRESSIONS, OFFSITECONVERSIONS, THRUPLAY, LEAD_GENERATION.

Google Ads now supports conversion adjustments via POST /v1/ads/conversions/adjustments.

You can retract, restate value, or enhance an already-uploaded conversion (Google only; other platforms return 405). Partial failure is supported (check adjustmentsFailed / failures[]).

Send:
• accountId (must be a googleads account)
• destinationId (conversion action resource name)
• adjustments[] with adjustmentType = RETRACTION | RESTATEMENT | ENHANCEMENT

Per adjustment:
• Identify the original conversion with orderId (required for ENHANCEMENT) or gclid + conversionTime
• adjustmentTime (unix seconds)
• restatementValue + currency (for RESTATEMENT)
• user.email/user.phone (+ optional userAgent) for ENHANCEMENT

Also: Meta standalone ad creation adds goal = leadconversion on POST /v1/ads/create (and Ad.goal) for website pixel lead optimization (distinct from leadgeneration instant forms).

GET /v1/comment-automations now returns stats.trackedSends for each automation.

Use trackedSends as the CTR denominator for tracked links (divide stats.linkClicks by stats.trackedSends, not stats.dmsSent). It may lag dmsSent for automations that predate click tracking.

New field:
• stats.trackedSends - DMs sent with a trackable (wrapped) link

Webhooks now support external post events for posts created/updated/deleted directly on the platform (not published via Zernio).

Subscribe by including these in events when calling POST /v1/webhooks/settings or PUT /v1/webhooks/settings:
• post.external.created
• post.external.updated
• post.external.deleted

Payload uses WebhookPayloadExternalPost with post = ExternalPostWebhookPost (includes post.id = platform-native ID, post.source = external; on post.external.deleted, post.deletedAt is populated). Events are sync-detected (~hourly), not real-time.

POST /v1/ads/create now supports Meta-specific single-ad naming and ad-level tracking.

You can explicitly set the created ad’s name (instead of inheriting name), and attach pixel measurement + URL tags regardless of optimization goal.

New fields:
• adName (Meta only) — overrides the default ad name (default was name)
• tracking.pixelId (Meta only) — attaches pixel measurement via ad tracking_specs
• tracking.urlTags (Meta only) — sets ad url_tags as [{ key, value }]

New Inbox Analytics endpoints are available to query messaging volume, response times, and conversation-level stats (max date range: 365 days).

New endpoints:
• GET /v1/analytics/inbox/volume — volume + KPIs + per-platform split (key params: fromDate, toDate, profileId, platform, accountId, source)
• GET /v1/analytics/inbox/heatmap — day-of-week × hour heatmap (key params: fromDate, toDate, action=message.received|message.sent|message.read|all)
• GET /v1/analytics/inbox/source-breakdown — breakdown by metadata.source
• GET /v1/analytics/inbox/response-time — time-to-first-response summary + histogram
• GET /v1/analytics/inbox/top-accounts — top accounts by inbox volume (key param: limit 1–50)
• GET /v1/analytics/inbox/conversations — paginated conversation analytics (key params: limit, page, sortBy=lastMessageAt|firstMessageAt|totalMessages|received|sent|read|failed, order=asc|desc)
• GET /v1/analytics/inbox/conversations/{conversationId} — single-conversation analytics ({conversationId} accepts Mongo _id or platformConversationId)

Webhook event enums were expanded in POST /v1/webhooks/settings, PUT /v1/webhooks/settings, and the Webhook schema to include:
• whatsapp.number.suspended
• whatsapp.number.reactivated
• whatsapp.number.released

You can now rename Meta ads objects via update endpoints.

This adds name updates without recreating entities (Meta only; other platforms return 501).

• PUT /v1/ads/campaigns/{campaignId} now accepts name (max 255)
• PUT /v1/ads/ad-sets/{adSetId} now accepts name (max 255)
• PUT /v1/ads/{adId} now supports name (max 255) and propagates it to Meta; non-Meta returns 501

Ad creation on Meta also adds more naming control:
• POST /v1/ads/create now accepts campaignName and adSetName (max 255)
• In Meta multi-creative mode, creatives[].name sets the per-ad name (max 255)

Meta ads created via POST /v1/ads/create now support raw Meta-native targeting via rawTargeting.

This lets you pass a Meta targeting spec through verbatim (snake_case) to clone an existing campaign’s targeting exactly, including advanced fields not covered by the camelCase targeting fields.

Use rawTargeting (Meta only) and do not combine it with:
• camelCase targeting fields (e.g. countries, regions, cities, interests, ageMin, ...)
• audienceId
• savedTargetingId

Sending both will return 422. If targeting EU users, also provide dsaBeneficiary / dsaPayor separately (not inside rawTargeting).

POST /v1/ads/create now supports safe retries via an optional Idempotency-Key header.

This endpoint isn’t idempotent at the ad-platform level (a blind retry can create duplicate campaigns/ad sets/ads). With Idempotency-Key, retries return the original stored response instead of creating duplicates.

Use Idempotency-Key (e.g. a UUID):
• Same key + same body → replays the original response (response header Idempotent-Replayed: true)
• Same key + different body → 422
• Key still processing → 409 (retry after backoff)

Keys are scoped to your credential and expire after 24h.

Google Business Profile location listing now supports server-side narrowing for large accounts via search and advanced filter.

This helps users find a specific location without loading the full list, and responses can now indicate when the list is bounded.

Changes:
• GET /v1/connect/googlebusiness/locations: new search, filter; response adds hasMore and per-location storeCode
• GET /v1/accounts/{accountId}/gmb-locations: new search, filter; response adds hasMore and per-location storeCode
• POST /v1/connect/googlebusiness/select-location: request body adds optional (recommended) accountId to resolve the location directly for large accounts
• PUT /v1/accounts/{accountId}/gmb-locations: request body adds optional (recommended) accountId when switching locations

Meta placement asset customization in POST /v1/ads/create now supports pinning video per placement group (not just images).

You can now run a single ad with different assets by placement (e.g. 9:16 video on Stories/Reels, 4:5 on Feed). A placementAssets block must be all-image or all-video (no mixing).

Use placementAssets in one of these modes:
• Image mode: defaultImageUrl + rules[].imageUrl
• Video mode: defaultVideoUrl + rules[].videoUrl (+ optional defaultThumbnailUrl / rules[].thumbnailUrl)

placementAssets still can’t be combined with dynamicCreative, creatives[], or adSetId.

Ads now support unified read/update of click-URL tracking tags via GET /v1/ads/{adId}/tracking-tags and PATCH /v1/ads/{adId}/tracking-tags.

This lets you audit and set platform-native tracking params across Meta/Google/LinkedIn (platforms without a click-URL tracking surface return 405).

Read returns platform, level (creative | campaign) plus platform fields:
• Meta: urlTags, templateUrlSpec
• Google: trackingUrlTemplate, finalUrlSuffix
• LinkedIn: dynamicValueParameters, customValueParameters

Update expects only the platform fields:
• Meta: urlTags (array of {key,value}) + full creative (headline, body, callToAction, linkUrl, imageUrl); may return 422 if the creative can’t be rebuilt
• Google: trackingUrlTemplate and/or finalUrlSuffix
• LinkedIn: dynamicValueParameters and/or customValueParameters

Meta-only: you can now read Event Match Quality (EMQ) + pixel↔CAPI coverage via GET /v1/ads/conversions/quality with accountId and destinationId (non-Meta returns 405).

Also added Meta advanced matching fields to ConversionEvent.user: city, state, zip, dob, gender (Meta-only; hashed server-side).

POST /v1/ads/create now supports Meta placement asset customization via placementAssets.

This lets you pin a specific image to each placement group (e.g. 9:16 for Stories/Reels and 4:5 for Feed) within a single ad, using Meta’s assetfeedspec + assetcustomizationrules behavior.

Use placementAssets:
• defaultImageUrl (required)
• rules[] (1-10), each with imageUrl + placements

placements supports: publisherPlatforms, facebookPositions, instagramPositions, messengerPositions, audienceNetworkPositions, threadsPositions, whatsappPositions, devicePlatforms.

Constraints: Meta-only; cannot be combined with dynamicCreative, creatives[], or adSetId.

Comment-to-DM automations now support Instagram story reply triggers via a new trigger field.

You can create automations that fire on keyword replies to stories (in addition to post comments). For story replies, platformPostId is the story media id (omit it to target any story).

Use trigger:
• comment
• story_reply

Applies to:
• POST /v1/comment-automations (new request field trigger, default comment)
• GET /v1/comment-automations and GET /v1/comment-automations/{automationId} (responses now include trigger)

GET /v1/comment-automations now returns additional automation stats: stats.delivered and stats.read.

This lets you report delivery/read performance for comment-to-DM automations (where supported) without extra calls.

New fields:
• stats.delivered - DMs confirmed delivered (Messenger; IG emits no delivery receipt)
• stats.read - DMs confirmed read (IG messagingseen / Messenger messagereads)

Comment-to-DM automations now support tagging contacts who click tracked links via clickTag.

When linkTracking is enabled, you can set clickTag so anyone who clicks a tracked link button in the DM gets tagged for segmentation (broadcasts/sequences).

Use:
• POST /v1/comment-automations: clickTag (optional; requires linkTracking)
• PATCH /v1/comment-automations/{automationId}: clickTag (empty string clears it)

Returned in:
• GET /v1/comment-automations: clickTag
• GET /v1/comment-automations/{automationId}: clickTag

Comment-to-DM automations now support link tracking for DM button URLs, and the list endpoint includes click metrics.

When enabled, link buttons are wrapped in a tracked redirect so you can measure clicks and CTR.

New fields:
• Create/update: linkTracking (POST default: true; set false to send links untouched)
• List: automations[].linkTracking
• List stats: automations[].stats.linkClicks, automations[].stats.uniqueClicks
• Details/create responses: automation.linkTracking

X (Twitter) posts now support quote reposting via quoteTweetId in TwitterPlatformData.

Set quoteTweetId to a tweet ID (or full status URL) to publish a quote tweet. For threads, it applies to the first tweet only.

Key property:
• quoteTweetId - mutually exclusive with media and poll; X only allows quoting your own posts or posts you’re mentioned in / part of the conversation thread of; billed at the standard create rate ($0.015).

WhatsApp call billing now includes billableCostUSD in call history, cost estimates, and call.ended webhooks.

This makes it explicit what Zernio bills you (Telnyx + recording) vs what Meta bills directly to your WABA (display-only).

New/updated billing fields:
• billing.billableCostUSD - amount Zernio bills (excludes Meta)
• billing.metaCostUSD - Meta per-minute charge (billed by Meta directly; display only)
• billing.totalCostUSD - full cost including Meta (display only)

Applies to:
• GET /v1/whatsapp/calls
• GET /v1/whatsapp/calls/estimate (in breakdown)
• Webhook schema WebhookPayloadCallEnded (in call.billing)

GET /v1/contacts/{contactId} now returns additional messaging activity fields on the contact and channels.

You can use these to show engagement stats and recent activity without querying message history.

New fields:
• Contact: messagesSentCount, messagesReceivedCount, lastMessageSentAt (nullable), lastMessageReceivedAt (nullable)
• Channel: lastActiveAt (nullable)

New Workflows API endpoints are available to build and run branching conversation workflows (node/edge graphs), including activation/pausing and execution tracking.

Manage workflows:
• GET /v1/workflows (filters: profileId, status = draft|active|paused, limit, skip)
• POST /v1/workflows (create draft; required: profileId, accountId, name; optional: platform = whatsapp|instagram|facebook|telegram|twitter|bluesky|reddit, nodes, edges, entryNodeId)
• GET /v1/workflows/{workflowId}
• PATCH /v1/workflows/{workflowId} (graph edits only when draft or paused)
• DELETE /v1/workflows/{workflowId}

Control lifecycle:
• POST /v1/workflows/{workflowId}/activate (validates runnable graph; idempotent)
• POST /v1/workflows/{workflowId}/pause (stops matching new inbound messages; idempotent)

Track and test runs:
• GET /v1/workflows/{workflowId}/executions (filter status = running|waiting|completed|exited|failed; limit, skip)
• POST /v1/workflows/{workflowId}/executions (manual start; provide conversationId or WhatsApp-only to; optional text seeds lastMessage)

WhatsApp now supports Sandbox session management via new endpoints: GET /v1/whatsapp/sandbox/sessions, POST /v1/whatsapp/sandbox/sessions, DELETE /v1/whatsapp/sandbox/sessions/{sessionId}.

This lets you activate a test phone against the shared sandbox number (reply-to-activate), list non-expired sessions, and revoke access to block future sends.

Key fields:
• Create/refresh with phone (server normalizes to E.164)
• Session object WhatsAppSandboxSession: id, phoneE164, status (pending | active), expiresAt, activatedAt
• Responses include sandboxNumber

Also, GET /v1/whatsapp/phone-numbers now includes an optional sandbox object (or null) with phoneNumber, accountId, and allowed template (name, language), plus isSandbox = true.

WhatsApp conversion events no longer require a Facebook Page ID on the account when calling POST /v1/whatsapp/conversions.

The endpoint now only requires metaCapiDatasetId (provision via POST /v1/whatsapp/dataset) and forwards the WABA ID as userdata.whatsappbusinessaccountid for Meta attribution.

If you were setting account metadata with connectedFacebookPageId, you can stop—missing it will no longer cause 422. Missing metaCapiDatasetId can still return 422.

Inbox webhooks now include contactId on conversation (via InboxWebhookConversation).

This lets you join any inbox webhook event back to the Zernio CRM Contact (best-effort), without relying on the sender identity — useful for outgoing and delivery-status style events.

New field:
• conversation.contactId - Zernio CRM Contact ID for the participant (omitted when no match or participantId is absent)

Applies to:
• message.received
• message.sent
• reaction.received
• conversation.started

CTWA ad creation now supports more precise geo targeting in POST /v1/ads/ctwa.

You can target by city/region/ZIP/metro or point-radius locations (useful for local WhatsApp campaigns) instead of relying only on country targeting.

New optional geo fields:
• cities[] (with optional radius + distance_unit: mile | kilometer)
• regions[]
• zips[]
• metros[]
• customLocations[] (requires latitude, longitude, radius, distanceUnit: mile | kilometer)

Note: countries now defaults to ["US"] only when no other geo targeting (cities/regions/zips/metros/customLocations) is provided.

New webhook event conversation.started is available via WebhookPayloadConversationStarted.

It fires once when a new DM conversation begins (first message exchange) and is platform-agnostic across instagram, facebook, telegram, whatsapp, twitter, reddit, bluesky.

Key fields:
• event=conversation.started
• conversation.id, conversation.platform, conversation.platformConversationId
• conversation.status: active | archived
• account
• startedAt, timestamp
• id (stable webhook event ID)

POST /v1/inbox/conversations/{conversationId}/messages now supports WhatsApp voice messages (PTT) via voiceNote in the JSON body.

When sending an audio attachment, set voiceNote to true to send it as a WhatsApp voice note (waveform/voice-note UI) instead of a regular audio file.

Key params:
• attachmentType: audio
• attachmentUrl: public URL to the audio file
• voiceNote: true (WhatsApp only)

Note: the audio must be .ogg encoded with OPUS (mono); other formats will be rejected by WhatsApp.

New endpoint: GET /v1/whatsapp/conversions.

You can now fetch recent WhatsApp conversion send events (from delivery logs, ~30-day retention) to power a “recent activity” view without maintaining your own persistence.

Required query: accountId
Optional query: limit (1–200, default 50)

Response includes per-event fields like timestamp, eventName (LeadSubmitted, Purchase, AddToCart, InitiateCheckout, ViewContent), conversationId, eventsReceived, eventsFailed, traceId, durationMs.

Inbox webhooks now include a sender contactId when the sender matches a Zernio CRM Contact.

This lets you link inbound messages/reactions directly to a Contact (via the ContactChannel mapping) without an extra Contacts API lookup. The field is omitted when no contact exists (and typically for outgoing/business sender).

New field:
• message.sender.contactId in message.received and message.sent
• reaction.sender.contactId in reaction.received
• InboxWebhookMessage.sender.contactId

WhatsApp now supports managing the Meta CTWA conversions dataset via two new endpoints.

Use these to detect whether Conversions API reporting is configured for a WhatsApp account and to provision the required Meta dataset (idempotent).

Check current dataset: GET /v1/whatsapp/dataset with accountId (query)
Returns datasetId (nullable).

Provision (or fetch existing) dataset: POST /v1/whatsapp/dataset with body accountId
Returns datasetId and created (boolean).

If the account token is missing whatsappbusinessmanage_events, provisioning returns 422 (reconnect required).

New endpoint: GET /v1/whatsapp/template-library.

You can now look up a single pre-approved WhatsApp Template Library template by exact name to inspect its structure before importing—especially the buttons you must mirror when creating a template (e.g., URL/PHONE_NUMBER inputs).

Required query params:
• accountId (WhatsApp social account ID)
• name (exact library template name)

Response (200): template (object or null) with key fields like bodyparams and buttons where buttons[].type can be QUICKREPLY, URL, PHONE_NUMBER, OTP, FLOW, ...

WhatsApp Flows now supports listing submitted flow responses via GET /v1/whatsapp/flow-responses.

This lets you fetch customer responses parsed from nfm_reply webhook messages (newest first), and optionally scope them to a specific flow.

Use:
• accountId (required)
• flowId (optional)
• limit (optional, max 200, default 50)

Response items include id, receivedAt, from, senderName, conversationId, flowToken, data, raw.

Also updated: when sending flows via POST /v1/whatsapp/flows/send, if flow_token is omitted it is now auto-generated as <flowId>:<uuid> so responses can be attributed to that flow in the Flow Responses view.

WhatsApp Flows now support flow previews and version history.

You can fetch Meta’s embeddable web preview URL for a flow (drafts included), and list Zernio-tracked versions for a flow’s clone lineage.

New endpoints:
• GET /v1/whatsapp/flows/{flowId}/preview with accountId and optional invalidate (mint a fresh link)
• GET /v1/whatsapp/flows/{flowId}/versions with accountId

Flow versioning metadata is now returned:
• GET /v1/whatsapp/flows adds version and lineageId per flow
• POST /v1/whatsapp/flows response adds version and lineageId

Cloning can now stay in the same lineage:
• POST /v1/whatsapp/flows adds asVersion (only when using cloneFlowId)

Inbox messages now include platform-specific metadata on each message via messages[].metadata.

This lets you read extra context like quoted replies and WhatsApp interactive/tap details without relying only on webhooks.

New field:
• messages[].metadata (free-form object; commonly includes quotedMessageId, waInteractive, and inbound tap fields like interactiveType / interactiveId)

WhatsApp multipart sends now support voice note uploads via voiceNote.

Set voiceNote to true when uploading an in-browser recorded audio so it’s transcoded to WhatsApp-native ogg/Opus.

New multipart field:
• voiceNote: true (WhatsApp-only)

Inbox messages now include emoji reactions on supported platforms (WhatsApp / Telegram) via reactions on each message.

This lets you display who reacted and when, alongside the message timeline.

New per-message field:
• reactions[]: { emoji, fromMe, reactedAt }

Sending messages now supports WhatsApp location and contact cards.

New request fields for POST /v1/inbox/conversations/{conversationId}/messages:
• location: { latitude, longitude, name?, address? }
• contacts[]: contact card objects (requires name.formatted_name; optional phones[], emails[])

POST /v1/inbox/conversations now supports starting conversations on X/Twitter, Bluesky, Reddit, and WhatsApp (previously X/Twitter only).

You can initiate DMs across these platforms using participantId or participantUsername (platform-dependent).

WhatsApp requires an approved template to start a conversation: set templateName, templateLanguage, and optional templateParams (freeform initial messages aren’t allowed). message is now optional when using a WhatsApp template.

skipDmCheck remains X/Twitter only.

PostAnalytics now includes Instagram Reels watch-time metrics.

You can retrieve average and total watch time for Reels (values are 0 for non-Reels media and other platforms).

New fields:
• igReelsAvgWatchTime (ms)
• igReelsVideoViewTotalTime (ms)

New webhook payload schema added for Meta Lead Gen / Instant Forms: lead.received events now use WebhookPayloadLead.

This lets webhook consumers reliably parse incoming leads, including form metadata, ad attribution (when available), and a flattened field map.

Key properties:
• event: lead.received
• lead.fields: key → value map (multiple-choice values are option keys, e.g. k1)
• lead.isOrganic: boolean
• lead.createdAt: ISO 8601 datetime
• account.platform: facebook
• lead.formName, lead.adId, lead.adsetId, lead.campaignId: nullable when not available

Meta Lead Gen is now supported end-to-end: you can manage Instant Forms and retrieve submitted leads via new Ads endpoints.

New endpoints:
• List all leads (cross-form CRM view): GET /v1/ads/leads with formId, accountId, since, limit, cursor
• Manage forms: GET /v1/ads/lead-forms, POST /v1/ads/lead-forms, GET /v1/ads/lead-forms/{formId}, DELETE /v1/ads/lead-forms/{formId}
• Form leads + testing: GET /v1/ads/lead-forms/{formId}/leads, POST /v1/ads/lead-forms/{formId}/test-leads

Ad creation update (Meta only): POST /v1/ads/create now accepts leadGenFormId. When goal is lead_generation, leadGenFormId is REQUIRED, and linkUrl is NOT required (the ad opens the form).

New endpoint POST /v1/ads/targeting/reach-estimate returns a normalized pre-flight audience reach estimate for a targeting spec before creating a campaign.

Send accountId + spec (same shape as TargetingSpec used by ads create). Optionally pass optimizationGoal.

Response includes available, and when available: lower, upper, optional daily, currency, and Meta-only estimateReady.

GET /v1/ads/interests is now deprecated. Use GET /v1/ads/targeting/search with dimension=interest (the deprecated alias still returns the legacy { interests: [...] } shape).

GET /v1/ads/targeting/search is now cross-platform and normalized. Use dimension = geo | interest | behavior | income, and for geo also geoType = country | region | city | zip | metro. Results return { results: [{ id, name, type, path?, audienceSize? }] }.

POST /v1/ads/create targeting now supports additional fields: zips, metros, customLocations, behaviors, incomeTier (top5 | top10 | top1025 | top2550), languages, savedTargetingId, specialAdCategories (HOUSING | EMPLOYMENT | CREDIT | ISSUESELECTIONSPOLITICS).

Audiences now support reusable targeting presets: POST /v1/ads/audiences accepts type=savedtargeting with spec (no adAccountId), and GET /v1/ads/audiences adds type filter and returns spec when type is savedtargeting.

GET /v1/inbox/comments/{postId} now returns (Reddit only) post metadata alongside comments in a new post object.

This lets you render a post preview in the inbox/comments view without an additional Reddit fetch. post is null/absent for non-Reddit platforms and may be missing if the upstream post listing isn’t available.

Key fields in post: id, fullname, title, selftext, author, subreddit, permalink, url, score, numComments, createdUtc, over18, stickied, flairText, isGallery.

Google Business Profile verification is now supported via new GMB Verifications endpoints.

You can fetch verification status/history, discover eligible methods, start a verification (SMS/call/email/postcard), and complete it by submitting the PIN.

New endpoints:
• GET /v1/accounts/{accountId}/gmb-verifications (optional locationId) returns voiceOfMerchantState.hasVoiceOfMerchant and verifications[].state = PENDING/COMPLETED/FAILED
• POST /v1/accounts/{accountId}/gmb-verifications/options requires languageCode; returns options[].verificationMethod = ADDRESS/EMAIL/PHONECALL/SMS/AUTO/VETTEDPARTNER
• POST /v1/accounts/{accountId}/gmb-verifications starts verification with method (+ method-specific fields like phoneNumber/emailAddress)
• POST /v1/accounts/{accountId}/gmb-verifications/{verificationId}/complete completes with pin

Note: service-area businesses may require context (service address) when fetching options/starting verification.

Webhooks now support message reaction events via the new reaction.received subscription.

Subscribe by including reaction.received in events when calling POST /v1/webhooks/settings or PUT /v1/webhooks/settings.

The reaction payload includes emoji, action (added | removed), platformMessageId, optional messageId, sender, and reactedAt.

GET /v1/ads/audiences now supports fetching custom audiences for LinkedIn and X (Twitter) ad accounts.

Use the platform query param with one of:
• facebook, instagram, googleads, tiktok, tiktokads, pinterest, linkedin, linkedinads, twitter, xads

GET /v1/broadcasts/{broadcastId}/recipients now returns errorCode per recipient.

This provides the Meta WhatsApp error code to help you classify and handle delivery failures (only populated when status=failed).

New field: errorCode (integer, nullable) — e.g. 131049 (antispam), 131021 (invalid phone), 131026 (re-engagement required).

Instagram now supports Stories retrieval + insights.

You can list currently-active stories and fetch metrics for a specific story, including a clear indicator of whether insights are live, cached, or unavailable.

New endpoints:
• GET /v1/accounts/{accountId}/instagram/stories
Returns active stories (24h window). Key fields: id, mediaType, mediaUrl (nullable), permalink, thumbnailUrl, timestamp
• GET /v1/accounts/{accountId}/instagram/stories/{storyId}/insights
Returns data.source = live | cached | unavailable and data.metrics including views, reach, replies, shares, navigation, tapsForward, tapsBack, exits, swipesForward, profileVisits, follows, reposts, totalInteractions.

WhatsApp is now supported as a platform for connecting accounts and checking account health.

You can now use whatsapp with:
• GET /v1/connect/{platform} (path param platform enum now includes whatsapp)
• GET /v1/accounts/health (query param platform enum now includes whatsapp)

GET /v1/ads/tree now supports campaign-level sorting via a new sort query parameter.

This lets you control the order of returned campaigns (by recency or aggregated spend) while keeping pagination at the campaign level.

Use sort:
• newest (default)
• oldest
• spend_desc
• spend_asc

Facebook now supports multi-link carousel posts via facebookSettings on POST /v1/posts.

This lets you publish a 2–5 card carousel where each image has its own click-through link (and optional headline/description).

Set facebookSettings.carouselCards (2–5 items) with:
• link (required)
• name (optional)
• description (optional)

Optionally set facebookSettings.carouselLink for the carousel end-card destination.

Constraints: mediaItems must be images only, and must match carouselCards length/order. Mutually exclusive with facebookSettings.contentType = story or reel.

POST /v1/posts now supports request idempotency via x-request-id.

If you send the same x-request-id again within ~5 minutes (including while the first request is in-flight), the API treats it as a retry and returns HTTP 200 with the original post in existingPost (no duplicate post is created).

Use x-request-id (UUID) per logical create call. If you omit it, each request is treated as new.

Duplicate protection still applies separately: identical content to the same (platform, accountId) within 24h returns HTTP 409 with details.accountId, details.platform, details.existingPostId.

{adId} in GET /v1/ads/{adId} and GET /v1/ads/{adId}/comments now accepts multiple identifier types.

You can call these endpoints using the Zernio internal id (24-char hex), Meta numeric platformAdId (from comment.received as comment.ad.id), or the creative’s effectiveobjectstoryid / effectiveinstagrammedia_id. Any of these resolves to the same ad, so you don’t need a translation step.

Webhooks now support per-platform terminal post events: post.platform.published and post.platform.failed.

These fire once per platform target inside a post when that specific platform reaches a terminal state (published or permanent failure), which helps track multi-platform posts more precisely.

Subscribe via events on POST /v1/webhooks/settings or PUT /v1/webhooks/settings:
• post.platform.published
• post.platform.failed

A new webhook event is also available:
• whatsapp.template.status_updated

GET /v1/ads/campaigns now supports filtering aggregated campaign metrics by a date range.

Use fromDate and toDate (YYYY-MM-DD, inclusive) to control the metrics window returned for each campaign.

New query params:
• fromDate - start date (defaults to 90 days ago when both date params are omitted)
• toDate - end date (defaults to today; max 730-day range)

Webhooks now support WhatsApp template status updates via the new event whatsapp.template.status_updated.

This fires when Meta completes a (re)review of a template on a connected WABA, so you can react to approvals/rejections and other status transitions.

Subscribe by adding whatsapp.template.status_updated to Webhook.events.

Payload: WebhookPayloadWhatsAppTemplateStatusUpdated with template.status ∈ APPROVED, REJECTED, PENDING, PAUSED, DISABLED, INAPPEAL, PENDINGDELETION and template.reason (e.g. "NONE" on approval).

Google Business reviews now support owner replies via new endpoints: POST /v1/accounts/{accountId}/gmb-reviews/{reviewId}/reply and DELETE /v1/accounts/{accountId}/gmb-reviews/{reviewId}/reply.

Use comment to post/update a reply (calling POST again overwrites the previous reply). Deleting removes only the reply, not the review.

Reply body: { "comment": "..." }

POST /v1/ads/ctwa now supports creating multiple CTWA ads under one campaign/ad set by sending a non-empty creatives[] array (each creative has its own headline, body, and exactly one of imageUrl/video). Single-creative requests still work.

New optional bidding controls on CTWA: bidStrategy (LOWESTCOSTWITHOUTCAP, LOWESTCOSTWITHBIDCAP, COSTCAP, LOWESTCOSTWITHMINROAS) plus bidAmount (required for bid-cap/cost-cap) and roasAverageFloor (required for min-ROAS).

CTWA create response is now a tagged union via adType: single or multi.

Webhooks now support ad.status_changed.

Subscribe to get notified when a Meta ads object (campaign/ad set/ad) changes status or enters WITH_ISSUES.

Add ad.status_changed to events when creating/updating a webhook via POST /v1/webhooks/settings or PUT /v1/webhooks/settings.

Payload highlights:
• event: ad.status_changed
• adObject.level: CAMPAIGN | AD_SET | AD
• status.raw: platform-native status (e.g. ACTIVE, PAUSED, WITH_ISSUES)
• error: optional diagnostics on most WITH_ISSUES events

Also, GET /v1/ads/{adId}/analytics now returns ad.currency (ISO 4217) so you can interpret money values in summary and daily.

GET /v1/ads/timeline now supports filtering by a specific platform ad account via adAccountId.

Use this when a single Zernio connection wraps multiple platform ad accounts and you want the timeline chart for just one (e.g. Meta act_…, TikTok advertiser ID).

New query param:
• adAccountId (optional)

Note: rows ingested before 2026-05-13 may not include this dimension yet; the recurring 7-day re-sync will repopulate them over time.

New endpoint GET /v1/ads/timeline returns a daily time series of aggregate ad metrics for a social account (one row per calendar day), useful for spend/conversions charts without calling /v1/ads/tree per day.

Key params:
• accountId (required)
• fromDate, toDate (YYYY-MM-DD; defaults to last 90 days; max 730 days)
• platform (optional): facebook, instagram, tiktok, linkedin, pinterest, google, twitter

Response: rows[] with per-day metrics like spend, impressions, clicks, ctr, conversions, actions, purchaseValue, roas. Returns empty rows if no activity. 403 if Ads add-on is required.

New endpoint: PATCH /v1/accounts/{accountId} to move a connected account to a different profile owned by the same user.

Send profileId in the JSON body to set the target profile.

Request body:
• profileId (required)

Auth/scope note: for profile-restricted API keys, both the account’s current profile and the target profileId must be allowed, otherwise you’ll get 403.

Responses: 200 returns message and profileId; errors include 400, 401, 403, 404.

TikTok conversion ads via POST /v1/ads/create now support/require TikTok pixel optimization settings through promotedObject.

For TikTok, goal=conversions uses promotedObject to configure the ad group’s pixel + optimization event (or inherit them by using adSetId).

Set:
• goal: conversions
• promotedObject.pixelId (required for TikTok conversions)
• promotedObject.customEventType (optional TikTok optimizationevent code, e.g. ONWEBORDER, INITIATEORDER, ONWEBCART, ONWEBREGISTER, FORM, ONWEBDETAIL)

POST /v1/ads/create now supports creating LinkedIn standalone ads.

This creates a LinkedIn Single Image Ad backed by a Direct Sponsored Content ("dark post") authored by a Company Page, with supported goals engagement, traffic, awareness (and traffic requires linkUrl).

Key request fields for LinkedIn:
• organizationId (Company Page org ID or urn:li:organization:N; required unless it can be inferred)
• headline (now required for LinkedIn; max 400)
• body (used as LinkedIn post commentary)
• imageUrl (required for LinkedIn)
• linkUrl (required for goal=traffic)
• longHeadline (optional secondary description on LinkedIn traffic ads)

Also updated:
• callToAction enum expanded with REGISTER, JOIN, ATTEND, REQUESTDEMO, VIEWQUOTE, APPLY, SEEMORE, BUYNOW
• Meta-only: new attributionSpec to control conversion attribution windows (CLICKTHROUGH/VIEWTHROUGH/ENGAGEDVIDEOVIEW with windowDays 1/7/28).

Meta ads (boosted/dark posts) are now included in GET /v1/inbox/comments for users with the Ads add-on (Metronome plans always qualify).

Ad rows are flagged so you can route comment fetching to the ads comments thread.

Use platform:
• metaads - ads only
• facebook/instagram - organic only
• omit platform - both

New fields on inbox rows: isAd (boolean), adId (string). For ad rows, fetch the thread via GET /v1/ads/{adId}/comments.

GET /v1/inbox/comments/{postId} now returns meta.adComments when a boosted post has no organic comments (includes adId and adCommentsUrl), and may return 400 with code USEADCOMMENTS_ENDPOINT when postId is an ad creative/ad ID.

GET /v1/ads adds filters to map Business Manager IDs back to Zernio ads: platformAdId, effectiveObjectStoryId, effectiveInstagramMediaId.

GET /v1/ads/{adId}/comments now returns additional Instagram metadata in meta for Instagram-placed ads.

This makes it easier to identify the boosted IG post and which connected Instagram account was used to read comments (useful for follow-up reply/hide actions via /v1/inbox/comments).

New meta fields (Instagram-only):
• instagramUserId
• instagramPermalink
• instagramAccountId

Also clarified: for Instagram-placed ads, if no connected Instagram account on the profile can read the ad’s media, the endpoint returns 422 with code adsconnectionrequired.

Meta Ads now supports managing Tracking Tags (Meta Pixels) via new endpoints.

You can list/create/get/update pixels, share/unshare them across ad accounts, and fetch aggregated event stats.

New endpoints:
• GET /v1/accounts/{accountId}/tracking-tags (optional adAccountId=act_...)
• POST /v1/accounts/{accountId}/tracking-tags body: adAccountId, name (not idempotent)
• GET /v1/accounts/{accountId}/tracking-tags/{tagId} (includes install code)
• PATCH /v1/accounts/{accountId}/tracking-tags/{tagId} fields: name, enableAutomaticMatching, automaticMatchingFields (em/ph/fn/ln/ge/db/ct/st/zp/country/externalid), firstPartyCookieStatus (empty/firstpartycookiedisabled/firstpartycookieenabled), dataUseSetting (advertisingandanalytics/analyticsonly/empty)
• GET|POST|DELETE /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts (DELETE supports adAccountId query)
• GET /v1/accounts/{accountId}/tracking-tags/{tagId}/stats (optional aggregation, startTime, endTime; aggregation enum includes event, url, devicetype, browsertype, etc.)

Notes: Meta-only (platform=metaads; other platforms return 405). Requires the Meta ads SocialAccount from the Ads add-on connect flow; list view omits code (use get to retrieve it).

Comment-to-DM automations now support inline DM buttons via buttons.

You can attach up to 3 buttons to the auto-DM (URL, postback, or phone on Facebook) to drive clicks or capture postbacks.

Use buttons in:
• POST /v1/comment-automations
• PATCH /v1/comment-automations/{automationId} (pass buttons: [] to clear)

Button schema: { type, title, url|payload|phone } where type is url | postback | phone (phone = Facebook-only), and title is max 20 chars.

Note: when buttons is non-empty, dmMessage must be ≤ 640 characters. Responses from list/get/create/update may now include buttons (omitted when none are set).

X API pricing/usage reporting now includes a new $0.200 “posts with URL” operation and tier.

This lets you attribute X spend more accurately per action; new clients should rely on per-operation counts rather than tier aggregates.

Key changes:
• New operation in GET /v1/billing/x-pricing: operation=contentcreatewithurl with tier=xapi_200 and pricePerCallUsd=0.2
• contentcreate price moved to pricePerCallUsd=0.015 (now tier=xapi_015)
• In GET /v1/usage-stats, usage.xApiCalls is now deprecated and excludes xapi200 (and future tiers); use usage.xApiCallsByOperation as the source of truth