create_update_linkedin_message_ad

Create a new or update an existing LinkedIn Message Ad on the Metadata platform.

                A LinkedIn Message Ad is a Sponsored Messaging asset: a one-shot direct
                message delivered to a member's LinkedIn inbox from a specific sender,
                with a subject line, a body, an optional banner image, and a single
                call-to-action button. It is NOT a Conversation Ad — there is no
                branching step graph. Use create_update_convo_ad for multi-step convos.

                IMPORTANT: This tool is ONLY for LinkedIn Sponsored Messaging
                (channelType=LINKEDIN, adType=MESSAGE). For IMAGE/GIF ads use
                create_update_image_ad; for VIDEO ads use create_update_video_ad; for CONVO
                use create_update_convo_ad; for Google Ads text ads use
                create_update_google_ads_ad; for DOCUMENT ads use
                create_update_document_ad. SPOTLIGHT / CTV / FOLLOWER are not yet
                covered by the dedicated tools.

                BEHAVIOR:
                - If `id` is NOT provided → creates a new Message Ad.
                - If `id` IS provided → updates the existing Message Ad with that ID.

                PREREQUISITES (MUST DO BEFORE CALLING):
                1. Call get_linkedin_senders to fetch a valid (senderId, senderName) pair.
                   Message Ads share LinkedIn's sponsored-messaging sender allow-list
                   with Conversation Ads — both pull from the same endpoint. Do NOT
                   invent sender IDs.
                2. If using a banner image: upload it via upload_image_creative and
                   pass the returned imageLibraryId as `bannerCreativeLibraryId`. The
                   banner is OPTIONAL — omit the field to skip it. LinkedIn requires
                   an IMAGE creative ≤ 2 MB; oversize banners are rejected upstream.

                CHARACTER LIMITS (enforced by the platform; mirror the UI validator at
                metadata-ui-v3/.../li/message/edit/validation.ts):
                - name           ≤ 50   chars  (ad name in the library)
                - headlineText   ≤ 60   chars  (the message subject line)
                - messageText    ≤ 2000 chars  (the message body)
                - actionText     ≤ 20   chars  (the CTA button label)

                PERSONALIZATION MACROS IN messageText:
                The body supports LinkedIn personalization macros. Pass them verbatim
                inside `%...%` — the platform substitutes at send time. The validator
                accepts ONLY these five macros (any other %...% token is rejected):
                  %FIRSTNAME%
                  %LASTNAME%
                  %COMPANYNAME%
                  %JOBTITLE%
                  %INDUSTRY%
                Do not use `{firstName}` or any other syntax — only `%MACRO%`.

                USAGE INSTRUCTIONS FOR LLM:
                Use this tool when users want to:
                - Create a new LinkedIn Sponsored Message ad
                - Update an existing Message Ad (subject, body, CTA, sender, or banner)

                WHEN TO USE:
                - User asks "create a LinkedIn Message Ad" / "InMail ad" /
                  "Sponsored Messaging ad"
                - User wants a one-shot LinkedIn DM with subject + body + CTA
                - User wants to update an existing Message Ad

                WHEN NOT TO USE:
                - User wants a branching conversation flow → use create_update_convo_ad
                - User wants a feed image / GIF ad → use create_update_image_ad
                - User wants a feed video ad → use create_update_video_ad
                - User wants a Google Ads text ad → use create_update_google_ads_ad

                INPUT PARAMETERS:
                - id (optional): Existing Message Ad ID. Provide to UPDATE; omit to
                  CREATE.
                - name (required, ≤ 50): Ad name in the library.
                - senderId (required): LinkedIn sender ID from get_linkedin_senders.
                - senderName (required): Display name matching senderId.
                - headlineText (required, ≤ 60): Subject line shown in the inbox.
                - messageText (required, ≤ 2000): Message body. Supports the five
                  %MACRO% tokens listed above.
                - actionText (required, ≤ 20): CTA button label.
                - bannerCreativeLibraryId (optional): imageLibraryId of the banner
                  image. Upload first via upload_image_creative. Omit to skip the
                  banner.
                - completionStatus (optional, default DRAFT): "DRAFT" or "COMPLETED".
                  Use COMPLETED only when every required field is final.

                EXAMPLE USAGE (Create):
                create_update_linkedin_message_ad(
                    name="Q1_Demo_Outreach_LI_Message",
                    senderId="fQdRPtecbv",
                    senderName="Josh Desmarais",
                    headlineText="Quick question about your marketing stack",
                    messageText="Hi %FIRSTNAME%, as a %JOBTITLE% at %COMPANYNAME% you know how hard pipeline attribution is. Want a 15-min walkthrough?",
                    actionText="Book a demo",
                    bannerCreativeLibraryId=482931,
                )

                EXAMPLE USAGE (Update):
                create_update_linkedin_message_ad(
                    id=29144,
                    name="Q1_Demo_Outreach_LI_Message_v2",
                    senderId="fQdRPtecbv",
                    senderName="Josh Desmarais",
                    headlineText="Following up — quick demo?",
                    messageText="Hi %FIRSTNAME%, circling back…",
                    actionText="Book a demo",
                )

                SUCCESS RESPONSE (mirrors create_update_convo_ad):
                {
                    "success": true,
                    "id": 29144,
                    "ad_url": "https://platform.metadata.io/hub/library/ads?adId=29144",
                    "name": "Q1_Demo_Outreach_LI_Message",
                    "channelType": "LINKEDIN",
                    "adType": "MESSAGE",
                    "completionStatus": "DRAFT",
                    "request": { "message": { ... } }
                }

                COMMON MISTAKES:
                ❌ Inventing a senderId — IDs MUST come from get_linkedin_senders.
                ❌ Passing a banner URL instead of an imageLibraryId — upload first.
                ❌ Using `{firstName}`-style macros — LinkedIn uses `%FIRSTNAME%`.
                ❌ Using an unsupported macro (anything outside the five listed) —
                   the platform/UI validator rejects it.
                ❌ Using this tool for a multi-step flow — use create_update_convo_ad.