AI product recommender in the Media Mix step

Recruiters on the recommendations-first product layout get a third tab, "AI Recommender", that asks HAPI's AI for a ranked shortlist of channels for the vacancy they are working on — each channel with the model's own reason for picking it. It is a shortcut past the filters for the case where the recruiter knows the vacancy but not the marketplace.

What's new

• An "AI Recommender" tab next to "Get recommendations" and "Search by product". Job title and job description arrive prefilled from the filters and the campaign and stay editable; job function, industry and location are shown as read-only chips with a link back to the first tab, because they are the filters themselves and editing them there re-runs the regular search.
• "What the AI receives" lists exactly what the request body will contain, including how many channels already in the basket are excluded from the answer.
• Generate, then wait. The tab shows a thinking state with a Cancel button while the job runs, and the result applies itself: the grid switches to the AI's picks in the model's ranked order.
• Reasons on the cards. Each card in an applied recommendation carries an "AI pick" strip and the model's one-line reason under the channel name. The rule-based "Recommended channel" strip steps aside while it does.
• A banner above the grid states how many channels are shown, notes that filters and sorting are bypassed, and offers Reset. Sort By and Filter By are disabled while a recommendation is applied, and the browse sections (frequently used, media-mix recommendations, free add-ons) are hidden — none of them is part of what the AI was asked.
• The bypass rule. While a recommendation is applied the product search sends only the recommendation id plus pagination: no job title, no location, no sort. That is what makes the ranked order survive.
• Failures are shown in the tab, with a Try again button: nothing to recommend, the feature not enabled for the account, the provider unavailable, the job taking too long, an expired or unknown recommendation.
• Layout v3 only. The tab lives in the tab strip introduced with he_product_filters_layout: "v3"; v1 and v2 have no entry point.
• Off unless VONQ turns it on. The tab appears only when settings.products.ai_recommendations_enabled is true on the account, which VONQ sets per partner.

Using it from the SDK

Three state keys carry the feature:

window.hapi.product.state.aiRecommendationId.value // applied recommendation id, or null
window.hapi.product.state.aiRecommendationJob.value // the current job: status, productCount, recommendations[], error
window.hapi.product.state.aiRecommendationPollingTimeoutsMap.value // running poll timers, keyed by job id

And four service functions:

// Build the request from the filters and the campaign description, or pass your own draft.
await window.hapi.product.service.createAiRecommendation.run()
await window.hapi.product.service.createAiRecommendation.run({
	title: "Registered nurse",
	description: "Night shifts in a teaching hospital…",
})

// One poll of a job. The create call polls on its own; this is for a job you
// already have an id for.
await window.hapi.product.service.getAiRecommendation.run(id)

// Point the product search at a recommendation (the create call does this
// itself as soon as the job completes with at least one channel).
await window.hapi.product.service.applyAiRecommendation.run(id)

// Drop the recommendation and search normally again.
await window.hapi.product.service.resetAiRecommendation.run()

The two HAPI calls are also available raw on window.hapi.product.api.createAiRecommendation and window.hapi.product.api.getAiRecommendation.

The bypass is exclusive. While aiRecommendationId is set, the product search sends recommendationId, format, limit and offset and nothing else — any filter you set meanwhile is ignored until the recommendation is reset. Two consequences for hosts:

• restartJourney clears the id and the job for you.
• If you reset the search filters yourself (writing product state directly rather than through the journey), call resetAiRecommendation as well — otherwise the grid keeps showing the AI's picks and your filters appear to do nothing.

Known behaviour

• Rate limit. HAPI allows 60 recommendation requests per 60 seconds per partner token, shared by all of that partner's customers. The create call and every poll count against it, which is why the client polls slowly.
• Poll cadence. The first poll waits 6 seconds, the next 8, then every 10. Jobs typically settle in under 10 seconds.
• 120-second deadline. A job that has not reached a terminal status by then is given up on locally with the timeout code; HAPI may still finish it.
• Expiry. Recommendations expire server-side. A search against an expired or unknown id drops the id, shows a notice on the banner, and re-runs the regular search.
• recommendation_provider_unavailable is HAPI's code for the model provider being down; it reads as "temporarily unavailable, try again shortly" and is worth a retry a minute later.
• Fewer channels than the AI picked. The model can pick a channel this account cannot order; the search drops it, and the banner says so.

Element ids and classes

Backwards compatibility

• Purely additive. No SDK function, getter, setter, property or event was removed or renamed, and no existing element id, class or data-* attribute changed.
• Nothing changes for an account without settings.products.ai_recommendations_enabled: no tab, no banner, no new requests, and the product search keeps sending exactly the parameters it sent before.
• The v1 and v2 filter layouts have no entry point for the feature yet.
• No theme variable was added; the new strip and banner reuse the existing success and info colours.

I18n

The following i18n translations have been added: