@zernio/node 0.2.678 → 0.2.679

package/dist/index.d.mts

@@ -8439,9 +8439,23 @@ type WebhookPayloadMessage = {
         text: (string) | null;
         attachments: Array<{
             /**
-             * Attachment type (image, video, file, sticker, audio)
+             * Attachment type (image, video, file, sticker, audio, share)
              */
             type: string;
+            /**
+             * Instagram and Facebook only, and present only when it differs
+             * from `type`. Meta's own attachment type before Zernio normalized
+             * it: `ig_reel` and `reel` become `video`, while `ig_post`, `post`,
+             * `ig_story` and `story_mention` all become `share`.
+             *
+             * Read it before rendering, because `type: "share"` alone is
+             * ambiguous. In particular a story mention arrives as
+             * `type: "share"` with `originalType: "story_mention"`; treating an
+             * unrecognized type as a generic document shows your agent
+             * "document received" for what is usually a lead.
+             *
+             */
+            originalType?: string;
             /**
              * Where to fetch the attachment. **The contract differs by platform.**
              *
@@ -8456,6 +8470,18 @@ type WebhookPayloadMessage = {
              * that needs no authentication and expires on the platform's own
              * schedule.
              *
+             * **Webhook attachments carry no `refreshUrl`.** That field is
+             * stamped only when you read a message back over REST
+             * (`GET /v1/inbox/conversations/{conversationId}/messages`). On
+             * Instagram and Facebook the url above is a signed Meta CDN link
+             * that expires, so do not persist it: store the message id and
+             * resolve the media through
+             * `GET /v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}?accountId={accountId}`,
+             * which re-mints it on demand. Every value that URL needs is
+             * already in this payload: `message.conversationId`,
+             * `message.platformMessageId`, `account.accountId`, and the
+             * attachment's zero-based position in this array.
+             *
              */
             url: string;
             /**
@@ -9013,9 +9039,13 @@ type WebhookPayloadMessageSent = {
         text: (string) | null;
         attachments: Array<{
             /**
-             * Attachment type (image, video, file, sticker, audio)
+             * Attachment type (image, video, file, sticker, audio, share)
              */
             type: string;
+            /**
+             * Instagram and Facebook only, and present only when it differs from `type`. Meta's own attachment type before Zernio normalized it. See the same field on message.received for the full mapping.
+             */
+            originalType?: string;
             /**
              * Where to fetch the attachment. For outgoing messages this is the
              * media URL as sent, so for WhatsApp it is the URL you supplied when
@@ -9024,6 +9054,11 @@ type WebhookPayloadMessageSent = {
              * `message.received` attachment URLs on WhatsApp point at the
              * authenticated `GET /v1/whatsapp/media/{mediaId}`.
              *
+             * As on `message.received`, webhook attachments carry no
+             * `refreshUrl`: that field is stamped only on the REST read. Resolve
+             * Instagram and Facebook media through
+             * `GET /v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}?accountId={accountId}`.
+             *
              */
             url: string;
             /**
@@ -9033,14 +9068,37 @@ type WebhookPayloadMessageSent = {
                 [key: string]: unknown;
             };
         }>;
+        /**
+         * **On this event the sender is your own business, not the person you
+         * are talking to.** `id` is the Zernio account id and `name`,
+         * `username` and `picture` are that connected account's own profile.
+         *
+         * Do not read these to name or update a contact: doing so on an echo
+         * relabels the customer's record with your business name. The other
+         * party is `conversation.participantId` / `participantName` /
+         * `participantUsername`, which are populated in both directions.
+         *
+         */
         sender: {
+            /**
+             * The Zernio account id of the connected account that sent the message, not a contact id.
+             */
             id: string;
             /**
              * Always omitted on this event: the sender is the business, not a contact. Use conversation.contactId to join back to the CRM Contact.
              */
             contactId?: string;
+            /**
+             * Display name of your connected account.
+             */
             name?: string;
+            /**
+             * Username of your connected account.
+             */
             username?: string;
+            /**
+             * Profile picture of your connected account.
+             */
             picture?: string;
         };
         /**
@@ -13440,6 +13498,60 @@ type GetConnectUrlData = {
         profileId: string;
         /**
          * Your custom redirect URL after connection completes. Accepts an http(s) URL, a custom app scheme for mobile deeplinks (e.g. myapp://callback), or a relative path. Result params are appended with the URL API, so an existing query string is preserved. Standard mode appends connected={platform}&profileId=X&accountId=Y&username=Z. Headless mode appends OAuth data params for platforms requiring selection (e.g. LinkedIn orgs, Facebook pages). If no selection is needed, the account is created directly and the redirect includes accountId.
+         *
+         * On failure, the browser is sent to the same redirect_url with `error` and `platform` appended.
+         * `error` and `platform` are always present. `error_message`, `is_user_fixable`, `reason` and
+         * `dashboard_url` are conditional and must be treated as optional.
+         *
+         * This list is NOT exhaustive and new values may be added at any time. Treat an unrecognized
+         * value as a generic failure rather than matching it exhaustively. Existing values are not
+         * renamed or removed without notice.
+         *
+         * OAuth and callback:
+         * oauth_denied, invalid_callback, invalid_state, unsupported_platform, connection_failed,
+         * internal_error, token_exchange_failed, byok_config_error, personal_account_not_supported,
+         * missing_google_permissions, platform_requires_destination, reconnect_account_mismatch,
+         * invalid_request
+         *
+         * Access and limits:
+         * profile_not_found, invalid_profile_id, access_denied, account_limit_exceeded,
+         * profile_limit_exceeded, payment_required
+         *
+         * Destination selection:
+         * no_facebook_pages, facebook_pages_error, no_google_locations, google_locations_error,
+         * google_permission_denied, no_snapchat_public_profiles, snapchat_profiles_error,
+         * discord_no_guild, slack_no_team
+         *
+         * WhatsApp:
+         * whatsapp_error, one_whatsapp_per_profile, whatsapp_number_already_connected,
+         * whatsapp_number_pinned_to_profile, connection_cancelled
+         *
+         * Google Ads (platform=googleads):
+         * google_ads_auth_failed, google_ads_invalid_state, google_ads_config_error,
+         * google_ads_token_failed, google_ads_quota_exhausted, google_ads_callback_error
+         *
+         * TikTok Ads (platform=tiktokads):
+         * tiktok_ads_auth_failed, tiktok_ads_invalid_state, tiktok_ads_access_denied,
+         * tiktok_ads_config_error, tiktok_ads_token_failed, tiktok_ads_account_not_found,
+         * tiktok_ads_callback_error
+         *
+         * X Ads (platform=xads):
+         * x_ads_denied, x_ads_auth_failed, x_ads_config_error, x_ads_account_not_found,
+         * x_ads_state_error, x_ads_token_failed, x_ads_token_missing, x_ads_callback_error
+         *
+         * Shopify (platform=shopify):
+         * shopify_auth_failed, shopify_config_error, shopify_invalid_state, shopify_invalid_hmac,
+         * shopify_invalid_shop, shopify_missing_scopes, shopify_callback_error
+         *
+         * 1. On this endpoint every upstream OAuth error is collapsed into `oauth_denied`. The
+         * provider's own value (for example Meta's `access_denied`) is not forwarded. The dedicated
+         * ads flows below are different: they use their own denial slugs and `google_ads_auth_failed`
+         * and `tiktok_ads_auth_failed` may carry the provider's raw error string in `error_message`.
+         *
+         * 2. On the tiktok and twitter ads flows `platform` carries the ads platform id
+         * (`tiktokads`, `xads`), not the value used in the request path. The googleads and shopify
+         * flows report `googleads` and `shopify`.
+         *
          */
         redirect_url?: string;
     };
@@ -13580,6 +13692,11 @@ type ConnectAdsData = {
     path: {
         /**
          * Platform to connect ads for. Only platforms with ads support are accepted.
+         *
+         * `instagram` requires an Instagram account connected with loginMethod=facebook_login whose
+         * token carries ads_management and ads_read. With an account connected through the default
+         * instagram_login flow no ads account can be created; do not use this value for those accounts.
+         *
          */
         platform: 'facebook' | 'instagram' | 'linkedin' | 'tiktok' | 'twitter' | 'pinterest' | 'googleads';
     };
@@ -13643,8 +13760,12 @@ type ConnectAdsData = {
          * `tiktok`, `twitter` and `googleads` land on the URL unchanged, while the
          * same-token platforms (`facebook`, `instagram`, `linkedin`, `pinterest`)
          * append `connected`, `profileId`, `accountId`, `username` and, on API-key
-         * calls, `connect_token`. On failure every platform appends error details,
-         * starting with `error` and `platform`. When omitted, the browser lands on
+         * calls, `connect_token`. On failure the same error contract applies as on
+         * GET /v1/connect/{platform}: `error` and `platform` are always appended,
+         * other params are optional, and the value list there is not exhaustive.
+         * Note that on the tiktok, twitter and googleads flows `platform` carries
+         * the ads platform id (`tiktokads`, `xads`, `googleads`), not the value
+         * used in the request path. When omitted, the browser lands on
          * the Zernio dashboard.
          *
          */
@@ -19320,6 +19441,10 @@ type GetInboxConversationMessagesResponse = ({
         attachments?: Array<{
             id?: string;
             type?: 'image' | 'video' | 'audio' | 'file' | 'sticker' | 'share';
+            /**
+             * Instagram and Facebook only, and present only when it differs from `type`. Meta's own type before normalization: `ig_reel` and `reel` become `video`, while `ig_post`, `post`, `ig_story` and `story_mention` become `share`. A story mention is `type: "share"` with `originalType: "story_mention"`; render on this field, since `share` alone is ambiguous.
+             */
+            originalType?: string;
             /**
              * Direct media link. On Instagram and Facebook this is a signed Meta CDN url that EXPIRES: use it now, do not store it. Persist `refreshUrl` instead.
              */
@@ -20460,7 +20585,7 @@ type GetMessageAttachmentData = {
     };
     query: {
         /**
-         * Social account ID
+         * Social account ID. Required: without it the request returns 400 missing_required_field.
          */
         accountId: string;
         /**

package/dist/index.d.ts

@@ -8439,9 +8439,23 @@ type WebhookPayloadMessage = {
         text: (string) | null;
         attachments: Array<{
             /**
-             * Attachment type (image, video, file, sticker, audio)
+             * Attachment type (image, video, file, sticker, audio, share)
              */
             type: string;
+            /**
+             * Instagram and Facebook only, and present only when it differs
+             * from `type`. Meta's own attachment type before Zernio normalized
+             * it: `ig_reel` and `reel` become `video`, while `ig_post`, `post`,
+             * `ig_story` and `story_mention` all become `share`.
+             *
+             * Read it before rendering, because `type: "share"` alone is
+             * ambiguous. In particular a story mention arrives as
+             * `type: "share"` with `originalType: "story_mention"`; treating an
+             * unrecognized type as a generic document shows your agent
+             * "document received" for what is usually a lead.
+             *
+             */
+            originalType?: string;
             /**
              * Where to fetch the attachment. **The contract differs by platform.**
              *
@@ -8456,6 +8470,18 @@ type WebhookPayloadMessage = {
              * that needs no authentication and expires on the platform's own
              * schedule.
              *
+             * **Webhook attachments carry no `refreshUrl`.** That field is
+             * stamped only when you read a message back over REST
+             * (`GET /v1/inbox/conversations/{conversationId}/messages`). On
+             * Instagram and Facebook the url above is a signed Meta CDN link
+             * that expires, so do not persist it: store the message id and
+             * resolve the media through
+             * `GET /v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}?accountId={accountId}`,
+             * which re-mints it on demand. Every value that URL needs is
+             * already in this payload: `message.conversationId`,
+             * `message.platformMessageId`, `account.accountId`, and the
+             * attachment's zero-based position in this array.
+             *
              */
             url: string;
             /**
@@ -9013,9 +9039,13 @@ type WebhookPayloadMessageSent = {
         text: (string) | null;
         attachments: Array<{
             /**
-             * Attachment type (image, video, file, sticker, audio)
+             * Attachment type (image, video, file, sticker, audio, share)
              */
             type: string;
+            /**
+             * Instagram and Facebook only, and present only when it differs from `type`. Meta's own attachment type before Zernio normalized it. See the same field on message.received for the full mapping.
+             */
+            originalType?: string;
             /**
              * Where to fetch the attachment. For outgoing messages this is the
              * media URL as sent, so for WhatsApp it is the URL you supplied when
@@ -9024,6 +9054,11 @@ type WebhookPayloadMessageSent = {
              * `message.received` attachment URLs on WhatsApp point at the
              * authenticated `GET /v1/whatsapp/media/{mediaId}`.
              *
+             * As on `message.received`, webhook attachments carry no
+             * `refreshUrl`: that field is stamped only on the REST read. Resolve
+             * Instagram and Facebook media through
+             * `GET /v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}?accountId={accountId}`.
+             *
              */
             url: string;
             /**
@@ -9033,14 +9068,37 @@ type WebhookPayloadMessageSent = {
                 [key: string]: unknown;
             };
         }>;
+        /**
+         * **On this event the sender is your own business, not the person you
+         * are talking to.** `id` is the Zernio account id and `name`,
+         * `username` and `picture` are that connected account's own profile.
+         *
+         * Do not read these to name or update a contact: doing so on an echo
+         * relabels the customer's record with your business name. The other
+         * party is `conversation.participantId` / `participantName` /
+         * `participantUsername`, which are populated in both directions.
+         *
+         */
         sender: {
+            /**
+             * The Zernio account id of the connected account that sent the message, not a contact id.
+             */
             id: string;
             /**
              * Always omitted on this event: the sender is the business, not a contact. Use conversation.contactId to join back to the CRM Contact.
              */
             contactId?: string;
+            /**
+             * Display name of your connected account.
+             */
             name?: string;
+            /**
+             * Username of your connected account.
+             */
             username?: string;
+            /**
+             * Profile picture of your connected account.
+             */
             picture?: string;
         };
         /**
@@ -13440,6 +13498,60 @@ type GetConnectUrlData = {
         profileId: string;
         /**
          * Your custom redirect URL after connection completes. Accepts an http(s) URL, a custom app scheme for mobile deeplinks (e.g. myapp://callback), or a relative path. Result params are appended with the URL API, so an existing query string is preserved. Standard mode appends connected={platform}&profileId=X&accountId=Y&username=Z. Headless mode appends OAuth data params for platforms requiring selection (e.g. LinkedIn orgs, Facebook pages). If no selection is needed, the account is created directly and the redirect includes accountId.
+         *
+         * On failure, the browser is sent to the same redirect_url with `error` and `platform` appended.
+         * `error` and `platform` are always present. `error_message`, `is_user_fixable`, `reason` and
+         * `dashboard_url` are conditional and must be treated as optional.
+         *
+         * This list is NOT exhaustive and new values may be added at any time. Treat an unrecognized
+         * value as a generic failure rather than matching it exhaustively. Existing values are not
+         * renamed or removed without notice.
+         *
+         * OAuth and callback:
+         * oauth_denied, invalid_callback, invalid_state, unsupported_platform, connection_failed,
+         * internal_error, token_exchange_failed, byok_config_error, personal_account_not_supported,
+         * missing_google_permissions, platform_requires_destination, reconnect_account_mismatch,
+         * invalid_request
+         *
+         * Access and limits:
+         * profile_not_found, invalid_profile_id, access_denied, account_limit_exceeded,
+         * profile_limit_exceeded, payment_required
+         *
+         * Destination selection:
+         * no_facebook_pages, facebook_pages_error, no_google_locations, google_locations_error,
+         * google_permission_denied, no_snapchat_public_profiles, snapchat_profiles_error,
+         * discord_no_guild, slack_no_team
+         *
+         * WhatsApp:
+         * whatsapp_error, one_whatsapp_per_profile, whatsapp_number_already_connected,
+         * whatsapp_number_pinned_to_profile, connection_cancelled
+         *
+         * Google Ads (platform=googleads):
+         * google_ads_auth_failed, google_ads_invalid_state, google_ads_config_error,
+         * google_ads_token_failed, google_ads_quota_exhausted, google_ads_callback_error
+         *
+         * TikTok Ads (platform=tiktokads):
+         * tiktok_ads_auth_failed, tiktok_ads_invalid_state, tiktok_ads_access_denied,
+         * tiktok_ads_config_error, tiktok_ads_token_failed, tiktok_ads_account_not_found,
+         * tiktok_ads_callback_error
+         *
+         * X Ads (platform=xads):
+         * x_ads_denied, x_ads_auth_failed, x_ads_config_error, x_ads_account_not_found,
+         * x_ads_state_error, x_ads_token_failed, x_ads_token_missing, x_ads_callback_error
+         *
+         * Shopify (platform=shopify):
+         * shopify_auth_failed, shopify_config_error, shopify_invalid_state, shopify_invalid_hmac,
+         * shopify_invalid_shop, shopify_missing_scopes, shopify_callback_error
+         *
+         * 1. On this endpoint every upstream OAuth error is collapsed into `oauth_denied`. The
+         * provider's own value (for example Meta's `access_denied`) is not forwarded. The dedicated
+         * ads flows below are different: they use their own denial slugs and `google_ads_auth_failed`
+         * and `tiktok_ads_auth_failed` may carry the provider's raw error string in `error_message`.
+         *
+         * 2. On the tiktok and twitter ads flows `platform` carries the ads platform id
+         * (`tiktokads`, `xads`), not the value used in the request path. The googleads and shopify
+         * flows report `googleads` and `shopify`.
+         *
          */
         redirect_url?: string;
     };
@@ -13580,6 +13692,11 @@ type ConnectAdsData = {
     path: {
         /**
          * Platform to connect ads for. Only platforms with ads support are accepted.
+         *
+         * `instagram` requires an Instagram account connected with loginMethod=facebook_login whose
+         * token carries ads_management and ads_read. With an account connected through the default
+         * instagram_login flow no ads account can be created; do not use this value for those accounts.
+         *
          */
         platform: 'facebook' | 'instagram' | 'linkedin' | 'tiktok' | 'twitter' | 'pinterest' | 'googleads';
     };
@@ -13643,8 +13760,12 @@ type ConnectAdsData = {
          * `tiktok`, `twitter` and `googleads` land on the URL unchanged, while the
          * same-token platforms (`facebook`, `instagram`, `linkedin`, `pinterest`)
          * append `connected`, `profileId`, `accountId`, `username` and, on API-key
-         * calls, `connect_token`. On failure every platform appends error details,
-         * starting with `error` and `platform`. When omitted, the browser lands on
+         * calls, `connect_token`. On failure the same error contract applies as on
+         * GET /v1/connect/{platform}: `error` and `platform` are always appended,
+         * other params are optional, and the value list there is not exhaustive.
+         * Note that on the tiktok, twitter and googleads flows `platform` carries
+         * the ads platform id (`tiktokads`, `xads`, `googleads`), not the value
+         * used in the request path. When omitted, the browser lands on
          * the Zernio dashboard.
          *
          */
@@ -19320,6 +19441,10 @@ type GetInboxConversationMessagesResponse = ({
         attachments?: Array<{
             id?: string;
             type?: 'image' | 'video' | 'audio' | 'file' | 'sticker' | 'share';
+            /**
+             * Instagram and Facebook only, and present only when it differs from `type`. Meta's own type before normalization: `ig_reel` and `reel` become `video`, while `ig_post`, `post`, `ig_story` and `story_mention` become `share`. A story mention is `type: "share"` with `originalType: "story_mention"`; render on this field, since `share` alone is ambiguous.
+             */
+            originalType?: string;
             /**
              * Direct media link. On Instagram and Facebook this is a signed Meta CDN url that EXPIRES: use it now, do not store it. Persist `refreshUrl` instead.
              */
@@ -20460,7 +20585,7 @@ type GetMessageAttachmentData = {
     };
     query: {
         /**
-         * Social account ID
+         * Social account ID. Required: without it the request returns 400 missing_required_field.
          */
         accountId: string;
         /**

package/dist/index.js

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(index_exports);
 // package.json
 var package_default = {
   name: "@zernio/node",
-  version: "0.2.678",
+  version: "0.2.679",
   description: "The official Node.js library for the Zernio API",
   main: "dist/index.js",
   module: "dist/index.mjs",

package/dist/index.mjs

@@ -5,7 +5,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 // package.json
 var package_default = {
   name: "@zernio/node",
-  version: "0.2.678",
+  version: "0.2.679",
   description: "The official Node.js library for the Zernio API",
   main: "dist/index.js",
   module: "dist/index.mjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zernio/node",
-  "version": "0.2.678",
+  "version": "0.2.679",
   "description": "The official Node.js library for the Zernio API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/generated/sdk.gen.ts

@@ -1467,7 +1467,24 @@ export const handleOAuthCallback = <ThrowOnError extends boolean = false>(option
  * Connect ads for a platform
  * Unified ads connection endpoint. Creates a dedicated ads SocialAccount for the specified platform.
  *
- * Same-token platforms (facebook, instagram, linkedin, pinterest): Creates an ads SocialAccount (metaads, linkedinads, pinterestads) with a copied OAuth token from the parent posting account. If the ads account already exists, returns alreadyConnected: true. No extra OAuth needed.
+ * Same-token platforms (facebook, instagram, linkedin, pinterest): the ads SocialAccount
+ * (metaads, linkedinads, pinterestads) reuses the OAuth token of the parent posting account,
+ * but only when an active parent exists and, for facebook and instagram, its stored token
+ * carries ads_management and ads_read (linkedin and pinterest need no extra scope). In that
+ * case no extra OAuth happens and the response is alreadyConnected: true. When no such parent
+ * exists, or the scopes are missing, the endpoint returns an authUrl and a full OAuth round
+ * trip is required. When a parent exists but carries no token usable for ad accounts, the call
+ * fails with 400 RECONNECT_REQUIRED. Independently of the branch, the call can return 403
+ * ADS_ADDON_REQUIRED without the ads add-on and 402 PAYMENT_REQUIRED when the billing gate is
+ * closed.
+ *
+ * Meta Ads prerequisite: connecting Meta Ads (via facebook or instagram) requires a Facebook
+ * Page. Not because the ad account is read through a Page, but because both parent posting
+ * accounts are: the facebook flow only offers Pages you manage, and the instagram flow with
+ * loginMethod=facebook_login only offers Instagram accounts linked to one of those Pages.
+ * Without a Page there is no parent account to inherit a token from. A user who manages no
+ * Facebook Page cannot complete this connection, and the facebook flow ends with
+ * error=no_facebook_pages.
  *
  * Separate-token platforms (tiktok, twitter): Starts the platform-specific marketing API OAuth flow and creates an ads SocialAccount (tiktokads, xads) with its own token. If the ads account already exists, returns alreadyConnected: true.
  * - tiktok: accountId is OPTIONAL. With accountId, the new tiktokads account links to that posting account (parentAccountId set) — Spark Ads + standalone ads using the posting TT_USER identity become available. Without accountId, ads-only mode kicks in: the new tiktokads account has parentAccountId=null and standalone ads use a synthetic CUSTOMIZED_USER ("Brand Identity"); Spark Ads are unavailable because TikTok requires a posting account for them. The Brand Identity is configured separately via PATCH /v1/connect/tiktok-ads (or inline on POST /v1/ads/create via the brandIdentity field).
@@ -3769,7 +3786,16 @@ export const deleteTelegramCommands = <ThrowOnError extends boolean = false>(opt
  * and stops working later. This endpoint checks the stored url and, when it
  * has gone stale, re-mints the message's media from Meta and persists it
  * before answering. The message id never expires, so this URL is the one to
- * store — it is returned on each attachment as `refreshUrl`.
+ * store. It is returned ready-made on each attachment as `refreshUrl` when
+ * you read a message over REST.
+ *
+ * **Webhook payloads do not carry `refreshUrl`**, so a webhook-driven
+ * integration builds this URL itself. Every piece is in the event:
+ * `message.conversationId`, `message.platformMessageId`, the attachment's
+ * zero-based position, and `account.accountId`. Note that **`accountId` is a
+ * required query parameter**; omitting it returns `400`
+ * `missing_required_field`, which is the same requirement
+ * `GET /v1/whatsapp/media/{mediaId}` has.
  *
  * By default it responds `302` to the live media url, so it can be used
  * directly as an `<img src>` on a browser session. API-key integrators

package/src/generated/types.gen.ts

@@ -7378,9 +7378,23 @@ export type WebhookPayloadMessage = {
         text: (string) | null;
         attachments: Array<{
             /**
-             * Attachment type (image, video, file, sticker, audio)
+             * Attachment type (image, video, file, sticker, audio, share)
              */
             type: string;
+            /**
+             * Instagram and Facebook only, and present only when it differs
+             * from `type`. Meta's own attachment type before Zernio normalized
+             * it: `ig_reel` and `reel` become `video`, while `ig_post`, `post`,
+             * `ig_story` and `story_mention` all become `share`.
+             *
+             * Read it before rendering, because `type: "share"` alone is
+             * ambiguous. In particular a story mention arrives as
+             * `type: "share"` with `originalType: "story_mention"`; treating an
+             * unrecognized type as a generic document shows your agent
+             * "document received" for what is usually a lead.
+             *
+             */
+            originalType?: string;
             /**
              * Where to fetch the attachment. **The contract differs by platform.**
              *
@@ -7395,6 +7409,18 @@ export type WebhookPayloadMessage = {
              * that needs no authentication and expires on the platform's own
              * schedule.
              *
+             * **Webhook attachments carry no `refreshUrl`.** That field is
+             * stamped only when you read a message back over REST
+             * (`GET /v1/inbox/conversations/{conversationId}/messages`). On
+             * Instagram and Facebook the url above is a signed Meta CDN link
+             * that expires, so do not persist it: store the message id and
+             * resolve the media through
+             * `GET /v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}?accountId={accountId}`,
+             * which re-mints it on demand. Every value that URL needs is
+             * already in this payload: `message.conversationId`,
+             * `message.platformMessageId`, `account.accountId`, and the
+             * attachment's zero-based position in this array.
+             *
              */
             url: string;
             /**
@@ -7963,9 +7989,13 @@ export type WebhookPayloadMessageSent = {
         text: (string) | null;
         attachments: Array<{
             /**
-             * Attachment type (image, video, file, sticker, audio)
+             * Attachment type (image, video, file, sticker, audio, share)
              */
             type: string;
+            /**
+             * Instagram and Facebook only, and present only when it differs from `type`. Meta's own attachment type before Zernio normalized it. See the same field on message.received for the full mapping.
+             */
+            originalType?: string;
             /**
              * Where to fetch the attachment. For outgoing messages this is the
              * media URL as sent, so for WhatsApp it is the URL you supplied when
@@ -7974,6 +8004,11 @@ export type WebhookPayloadMessageSent = {
              * `message.received` attachment URLs on WhatsApp point at the
              * authenticated `GET /v1/whatsapp/media/{mediaId}`.
              *
+             * As on `message.received`, webhook attachments carry no
+             * `refreshUrl`: that field is stamped only on the REST read. Resolve
+             * Instagram and Facebook media through
+             * `GET /v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}?accountId={accountId}`.
+             *
              */
             url: string;
             /**
@@ -7983,14 +8018,37 @@ export type WebhookPayloadMessageSent = {
                 [key: string]: unknown;
             };
         }>;
+        /**
+         * **On this event the sender is your own business, not the person you
+         * are talking to.** `id` is the Zernio account id and `name`,
+         * `username` and `picture` are that connected account's own profile.
+         *
+         * Do not read these to name or update a contact: doing so on an echo
+         * relabels the customer's record with your business name. The other
+         * party is `conversation.participantId` / `participantName` /
+         * `participantUsername`, which are populated in both directions.
+         *
+         */
         sender: {
+            /**
+             * The Zernio account id of the connected account that sent the message, not a contact id.
+             */
             id: string;
             /**
              * Always omitted on this event: the sender is the business, not a contact. Use conversation.contactId to join back to the CRM Contact.
              */
             contactId?: string;
+            /**
+             * Display name of your connected account.
+             */
             name?: string;
+            /**
+             * Username of your connected account.
+             */
             username?: string;
+            /**
+             * Profile picture of your connected account.
+             */
             picture?: string;
         };
         /**
@@ -12695,6 +12753,60 @@ export type GetConnectUrlData = {
         profileId: string;
         /**
          * Your custom redirect URL after connection completes. Accepts an http(s) URL, a custom app scheme for mobile deeplinks (e.g. myapp://callback), or a relative path. Result params are appended with the URL API, so an existing query string is preserved. Standard mode appends connected={platform}&profileId=X&accountId=Y&username=Z. Headless mode appends OAuth data params for platforms requiring selection (e.g. LinkedIn orgs, Facebook pages). If no selection is needed, the account is created directly and the redirect includes accountId.
+         *
+         * On failure, the browser is sent to the same redirect_url with `error` and `platform` appended.
+         * `error` and `platform` are always present. `error_message`, `is_user_fixable`, `reason` and
+         * `dashboard_url` are conditional and must be treated as optional.
+         *
+         * This list is NOT exhaustive and new values may be added at any time. Treat an unrecognized
+         * value as a generic failure rather than matching it exhaustively. Existing values are not
+         * renamed or removed without notice.
+         *
+         * OAuth and callback:
+         * oauth_denied, invalid_callback, invalid_state, unsupported_platform, connection_failed,
+         * internal_error, token_exchange_failed, byok_config_error, personal_account_not_supported,
+         * missing_google_permissions, platform_requires_destination, reconnect_account_mismatch,
+         * invalid_request
+         *
+         * Access and limits:
+         * profile_not_found, invalid_profile_id, access_denied, account_limit_exceeded,
+         * profile_limit_exceeded, payment_required
+         *
+         * Destination selection:
+         * no_facebook_pages, facebook_pages_error, no_google_locations, google_locations_error,
+         * google_permission_denied, no_snapchat_public_profiles, snapchat_profiles_error,
+         * discord_no_guild, slack_no_team
+         *
+         * WhatsApp:
+         * whatsapp_error, one_whatsapp_per_profile, whatsapp_number_already_connected,
+         * whatsapp_number_pinned_to_profile, connection_cancelled
+         *
+         * Google Ads (platform=googleads):
+         * google_ads_auth_failed, google_ads_invalid_state, google_ads_config_error,
+         * google_ads_token_failed, google_ads_quota_exhausted, google_ads_callback_error
+         *
+         * TikTok Ads (platform=tiktokads):
+         * tiktok_ads_auth_failed, tiktok_ads_invalid_state, tiktok_ads_access_denied,
+         * tiktok_ads_config_error, tiktok_ads_token_failed, tiktok_ads_account_not_found,
+         * tiktok_ads_callback_error
+         *
+         * X Ads (platform=xads):
+         * x_ads_denied, x_ads_auth_failed, x_ads_config_error, x_ads_account_not_found,
+         * x_ads_state_error, x_ads_token_failed, x_ads_token_missing, x_ads_callback_error
+         *
+         * Shopify (platform=shopify):
+         * shopify_auth_failed, shopify_config_error, shopify_invalid_state, shopify_invalid_hmac,
+         * shopify_invalid_shop, shopify_missing_scopes, shopify_callback_error
+         *
+         * 1. On this endpoint every upstream OAuth error is collapsed into `oauth_denied`. The
+         * provider's own value (for example Meta's `access_denied`) is not forwarded. The dedicated
+         * ads flows below are different: they use their own denial slugs and `google_ads_auth_failed`
+         * and `tiktok_ads_auth_failed` may carry the provider's raw error string in `error_message`.
+         *
+         * 2. On the tiktok and twitter ads flows `platform` carries the ads platform id
+         * (`tiktokads`, `xads`), not the value used in the request path. The googleads and shopify
+         * flows report `googleads` and `shopify`.
+         *
          */
         redirect_url?: string;
     };
@@ -12841,6 +12953,11 @@ export type ConnectAdsData = {
     path: {
         /**
          * Platform to connect ads for. Only platforms with ads support are accepted.
+         *
+         * `instagram` requires an Instagram account connected with loginMethod=facebook_login whose
+         * token carries ads_management and ads_read. With an account connected through the default
+         * instagram_login flow no ads account can be created; do not use this value for those accounts.
+         *
          */
         platform: 'facebook' | 'instagram' | 'linkedin' | 'tiktok' | 'twitter' | 'pinterest' | 'googleads';
     };
@@ -12904,8 +13021,12 @@ export type ConnectAdsData = {
          * `tiktok`, `twitter` and `googleads` land on the URL unchanged, while the
          * same-token platforms (`facebook`, `instagram`, `linkedin`, `pinterest`)
          * append `connected`, `profileId`, `accountId`, `username` and, on API-key
-         * calls, `connect_token`. On failure every platform appends error details,
-         * starting with `error` and `platform`. When omitted, the browser lands on
+         * calls, `connect_token`. On failure the same error contract applies as on
+         * GET /v1/connect/{platform}: `error` and `platform` are always appended,
+         * other params are optional, and the value list there is not exhaustive.
+         * Note that on the tiktok, twitter and googleads flows `platform` carries
+         * the ads platform id (`tiktokads`, `xads`, `googleads`), not the value
+         * used in the request path. When omitted, the browser lands on
          * the Zernio dashboard.
          *
          */
@@ -18971,6 +19092,10 @@ export type GetInboxConversationMessagesResponse = ({
         attachments?: Array<{
             id?: string;
             type?: 'image' | 'video' | 'audio' | 'file' | 'sticker' | 'share';
+            /**
+             * Instagram and Facebook only, and present only when it differs from `type`. Meta's own type before normalization: `ig_reel` and `reel` become `video`, while `ig_post`, `post`, `ig_story` and `story_mention` become `share`. A story mention is `type: "share"` with `originalType: "story_mention"`; render on this field, since `share` alone is ambiguous.
+             */
+            originalType?: string;
             /**
              * Direct media link. On Instagram and Facebook this is a signed Meta CDN url that EXPIRES: use it now, do not store it. Persist `refreshUrl` instead.
              */
@@ -20167,7 +20292,7 @@ export type GetMessageAttachmentData = {
     };
     query: {
         /**
-         * Social account ID
+         * Social account ID. Required: without it the request returns 400 missing_required_field.
          */
         accountId: string;
         /**