Ads Optimization

What it is

Nothing here is an ads dashboard. This module writes one setting on one automation scope: the event sets on bot.fuelyAutomations(scope: WhatsAppClickFromAds), which say which moments in a click-to-WhatsApp conversation are reported to Meta as conversions over the Conversions API — so Meta can optimize delivery towards the people who actually convert.

The surface is one screen: the sets on the left, the selected set beside them. And the ads a set claims are opaque strings that nothing ever checks.

Installed as

Neither hidden nor railHidden. The two recommendations are the surfaces the same data is seen from elsewhere: automations is the AI side of the very automations these sets live on, and contacts owns the properties and statuses two of the triggers fire on.

Routes and views

The path segment is not a view name here — it is the set. There is only one view.

Both survive a reload, because both are places a link can be sent to. Nothing else about the surface is, so nothing else is in the address.

The model

A set is a FuelyAutomation. A bot has exactly one base set — isBase: true, and the API leaves its name null, which is why the module supplies one ("Default events for all ads") — and up to thirty custom ones. The base set carries no list of ads at all: the API strips filter settings from a base automation, and that absence is what makes it "everything". A custom set claims the ads it lists in FuelySettingListOfAds.adIDs and overrides the base for exactly those.

Every setting on a custom set either holds its own value or follows a parent, named by inheritsFrom; canInheritFrom says which parents it may be pointed at. Two consequences are worth building around. Saving an inherited setting takes a private copy — the set stops following, and for sendEventsToMeta every event id is regenerated, so ids read a moment ago are gone. And a write on a parent republishes its children: one edit arrives as several subscription events, one per affected set, so merge by id.

An event is a conversion name plus a trigger. The name is one of Meta's fourteen standard ones, or one of your own — at most fifty characters, reported to Meta verbatim, and refused if it is one of the fourteen spelled differently. bot.availableMetaConversionEventNames remembers the custom names this bot has already used; do not hard-code either list.

The seven triggers, in the order the picker offers them:

Every save rewrites the whole ordered list of events. There is no add-one and no delete-one mutation; order is stored and is part of the value. Leave an id out to delete that event, keep it to keep it, omit it entirely to add one. Two events reporting the same conversion on the same trigger are refused. The API also cleans the input before it validates — ad ids and keywords are trimmed, blanks dropped, repeats removed — so what you read back is not always what you sent.

Ad ids are opaque and unverified. Any string under sixty characters is accepted, no query turns an id back into an ad, and nothing reports that an id names an ad that was deleted, paused or never existed. So a typo saves happily. The module validates the shape — a bare 15-to-20 digit run — and never claims an id is real. It also takes ids out of whatever is in the clipboard, because nobody reads an id off a screen: they copy the Ads Manager address bar. When selected_ad_ids= is present it is trusted exclusively, since act= and business_id= are digit runs too and taking either for an ad id silently points a set at nothing.

Configuration

No secret and no database of its own. Every variable the app reads, and which side reads it, is on environment variables.

Permissions

The third one is why a token with full Flows rights can still show an empty delivery state: the permission that decides whether anything is sent is read off the bot, not off the automation.

Limits

The server refuses the whole list. Not the offending entry — the list. One bad twentieth event throws away nineteen good ones typed in the same session, which is why the module checks every ceiling before the write, using the same error codes the server would have answered with.

Two sets claiming the same ad is not reported anywhere. One of them silently loses. The whole list is in hand after one query, so the module builds the reverse index itself and names the rival set on the chip; nothing on the server will.

A contact-property condition the server dislikes is stored anyway. The save succeeds and the error comes back on the event in attributeConditionErrors, so read that array or the condition looks fine and does nothing.

Errors arrive one level down. The top-level message names a failed subgraph fetch; the code is at errors[0].extensions.errors[0].extensions.code. Read both levels or you will find nothing.

There is no history and no read-back. Conversions are sent and forgotten: no query reports what Meta received, what it accepted, or how an ad performed afterwards. That question is Ads Manager's. The API does expose ads — currentUser.metaAdAccounts and MetaAdAccount.ads(...) — and none of it is used here, for three reasons: it hangs off the signed-in person's Facebook login rather than off the bot, MetaAd cannot be looked up by id (resolving a set's ids means paging an account and matching client-side), and the insights carry no date range at all — one aggregate figure per ad, and no trend to draw.

Every write lands on the production bot immediately. There is no draft mode and no preview. Undo is one entry, sixty seconds, and a compensating write: a restored event comes back with a new id. And turning a set on can be refused by the plan — NotAllowedBySubscriptionFeatureSet on a plan without AI. A concurrent write on the same bot answers FuelyAutomationBeingEdited, which is a lock rather than a conflict and clears on its own.

The ceilings, each with the code the server answers when you pass it: