create_update_convo_ad

Create or update a LinkedIn Conversation Ad ("convo ad") —
                a branching in-message chat where each step contains a message bubble and
                a list of button actions that drive the conversation forward.

                BEHAVIOR:
                - If `id` is provided → UPDATES the existing convo ad with that ID.
                - If `id` is omitted → CREATES a new convo ad.

                PREREQUISITES (MUST DO BEFORE CALLING):
                1. Call get_linkedin_senders to get a valid (senderId, senderName) pair.
                   These are LinkedIn-issued IDs — do NOT invent them.
                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.

                THE STEP GRAPH:
                A convo is a directed graph of message "steps". Each step has:
                - `stepId` — unique integer; stepId=1 is ALWAYS the entry message.
                - `message` — the bubble text; HTML allowed (e.g.,
                  '<p style="margin:0">Hi!</p>').
                - `actions` — the buttons under the bubble (1 to 5).

                ACTIONS — each action has a `type` from this enum:
                - NEXT_STEP   → click jumps to another step by `nextStepId`. Use this to
                                build branches ("Interested? YES / NO").
                - WEBSITE_URL → click opens an external URL given in `link`. Use this for
                                "learn more" / external resources.
                - MAIN_CTA    → click opens the offer attached at campaign launch (either
                                a lead-gen form OR a landing page, depending on the offer).
                                DO NOT set `link` or `nextStepId` on a MAIN_CTA — they
                                are resolved by the campaign builder later.

                ⚠️ STRUCTURAL RULES (validated client-side before POST):
                1. Every action.type MUST be one of NEXT_STEP / WEBSITE_URL / MAIN_CTA.
                2. NEXT_STEP MUST have `nextStepId` pointing to an existing stepId, and
                   cannot point at itself.
                3. WEBSITE_URL MUST have a non-empty `link`.
                4. MAIN_CTA needs neither `link` nor `nextStepId`.
                5. The flow MUST terminate — any step with NO NEXT_STEP action must
                   include at least one MAIN_CTA or WEBSITE_URL so the user has an exit.
                6. `stepId=1` MUST exist — it is the entry point.
                7. stepIds must be unique.

                A single step CAN mix action types — e.g., step 1 can offer "Tell me
                more" (NEXT_STEP), "Visit site" (WEBSITE_URL), and "Book demo"
                (MAIN_CTA) all at once.

                INPUT PARAMETERS:
                - name (required, max 50 chars): Ad name in the platform library.
                - senderId (required): From get_linkedin_senders.
                - senderName (required): Matching display name from get_linkedin_senders.
                - headlineText (required): Subject line shown above the message thread.
                - bannerCreativeLibraryId (optional): imageLibraryId for the banner image
                  above the chat. Omit to skip the banner.
                - completionStatus (optional, default "DRAFT"): "DRAFT" or "COMPLETED".
                - flowId (optional, default 7): LinkedIn convo flow version ID.
                - templateId (optional, default 1): LinkedIn convo template ID.
                - id (optional): For UPDATE only — existing ad ID.
                - steps (required, ≥1): The step graph (see schema).

                EXAMPLE — TWO-STEP BRANCH WITH MULTI-ACTION FIRST STEP:
                create_update_convo_ad(
                    name="DemoConvo_Q4",
                    senderId="fQdRPtecbv",
                    senderName="Josh Desmarais",
                    headlineText="Quick question about your marketing stack",
                    completionStatus="DRAFT",
                    steps=[
                        {
                            "stepId": 1,
                            "message": "<p style=\"margin:0\">Want a 15-min demo?</p>",
                            "actions": [
                                {"type": "NEXT_STEP", "text": "Tell me more", "nextStepId": 2},
                                {"type": "WEBSITE_URL", "text": "Visit site", "link": "https://metadata.io"},
                                {"type": "MAIN_CTA", "text": "Book demo"}
                            ]
                        },
                        {
                            "stepId": 2,
                            "message": "<p style=\"margin:0\">More info — ready to book?</p>",
                            "actions": [
                                {"type": "MAIN_CTA", "text": "Yes, book"}
                            ]
                        }
                    ]
                )

                SUCCESS RESPONSE:
                {
                    "success": true,
                    "id": 21241,
                    "ad_url": "https://platform.metadata.io/hub/library/ads?adId=21241",
                    "name": "DemoConvo_Q4",
                    "channelType": "LINKEDIN",
                    "adType": "CONVO",
                    "completionStatus": "DRAFT",
                    "request": { "convo": { ... } }
                }

                COMMON MISTAKES:
                ❌ Inventing a senderId — IDs MUST come from get_linkedin_senders.
                ❌ Putting `link` on a MAIN_CTA — the offer link is set at campaign launch.
                ❌ Putting `nextStepId` on a MAIN_CTA / WEBSITE_URL — only NEXT_STEP uses it.
                ❌ Forgetting the terminator — every leaf must end with MAIN_CTA or WEBSITE_URL.
                ❌ Skipping stepId=1 — the entry must exist and be exactly 1.

                NOTES:
                - Convo ads are LinkedIn-only. channelType is fixed to "LINKEDIN".
                - `message` supports HTML; preserve the user's markup verbatim.