Engagement Tools

Overview

The Engagement tool category handles all proactive customer engagement: banners, in-app chat messages, surveys, product tours, and news releases. You can draft these items, configure detailed trigger rules for when and where they appear, and order them in the list.

Permission required: Each type needs its matching permission — Outreach.Banners, Outreach.Messages, Outreach.Surveys, Outreach.Tours, or Outreach.News — the same permission you'd need to manage that item in the dashboard.

The dashboard calls this section Engagement. You'll find it at Marketing → Engagement, with Banners, Chat messages, News & Releases, Surveys and Tours inside it. Only the display name changed: the tool is still called manage_outreach, the permission keys still start with Outreach., and the web addresses still say /dashboard/outreach/…. Nothing about the tools themselves changed.

manage_outreach

Creates or updates an engagement item (banner, survey, tour, or chat message).

Parameters

Parameter	Type	Required	Description
`type`	string	Yes	The item type: `"banner"`, `"message"`, `"survey"`, or `"tour"`.
`id`	string	No	Item ID. Omit to create, provide to update.
`name`	string	No	Display name.
`content`	string	No	Body text (for banners and messages).
`widgetId`	string	No	Widget to associate with. Auto-assigns the organization's default widget if omitted.
`config`	object	No	Raw configuration object for advanced settings (banner style, survey flow, tour steps, etc.).
`position`	number	No	Display order, where 1 is first. Omit to append to the end. If the slot is taken, the items below shift down.

Trigger rules (natural-language):

Parameter	Type	Description
`trigger`	string	When to trigger: `"session_start"`, `"page_view"`, or `"custom_event"`.
`triggerDelay`	number	Delay in seconds after the trigger event.
`customEventName`	string	Custom JavaScript event name (only with `trigger: "custom_event"`).
`pageUrlContains`	string	Only show on pages whose URL contains this string.
`timeOnPageSeconds`	number	Only show after the visitor has spent this many seconds on the page.
`frequency`	string	How often to show: `"once"`, `"every_time"`, or `"limited"`.
`frequencyDays`	number	For limited frequency: within how many days.
`frequencyTimes`	number	For limited frequency: maximum number of times to show.
`countryEquals`	string	Only show to visitors from this country (ISO 2-letter code, e.g., `"US"`).
`countryNotEquals`	string	Hide from visitors in this country.

Parameter	Type	Description
`triggerSettings`	object	Raw trigger config JSON — overrides all natural-language trigger parameters. For advanced use.

How It Works

Creating an item:

Only type is required. A default name is generated (e.g., "New Banner").
The item is associated with your organization's default widget unless you specify widgetId. A widget belongs to a brand, so this decides which brand's visitors see it. If your organization has no default widget the call fails with an explanation.
Default configurations are applied based on type:
- Banner: inline style, yellow color, no close button.
- Survey: welcome message + thank you message flow.
- Tour: empty steps, no close button.
- Message: empty config.
The response includes a dashboardUrl pointing straight at the item's editor.

Trigger rules:

You can use natural-language parameters (like trigger, pageUrlContains, countryEquals) and the tool builds the trigger config automatically.
Or you can pass raw triggerSettings JSON for full control.
Natural-language parameters and triggerSettings are mutually exclusive — if both are provided, triggerSettings takes precedence.

Updating an item:

Provide the id and type, plus the fields to change.
Any update to an item — its name, its content, its position, its widget or its trigger rules — discards whatever was already queued for delivery and not yet sent, so the item goes out on the new version rather than the old.

This tool cannot publish anything. Every item is created unpublished and stays that way — there is no published parameter and no publish action. You review the draft at the returned dashboardUrl and switch it live yourself. That is deliberate: publishing puts something in front of real visitors.

Example Prompts

"Draft a banner announcing our holiday sale."
"Create a survey called 'Customer Feedback' that triggers on page view after 10 seconds."
"Create a product tour for our new dashboard."
"Create a chat message that shows on the pricing page to US visitors only."
"Set the banner to show only once per visitor."
"Change the trigger to show after 30 seconds on the page."
"Move my sale banner to the top of the list."
"Update the banner content to say '50% off everything — today only!'"
"Create a survey that only shows on pages containing '/checkout' and triggers after 5 seconds."
"Set the item to show a maximum of 3 times within 7 days."
"Target only visitors from Germany."
"Create a chat message triggered by a custom JavaScript event called 'purchase_complete'."

manage_outreach_news

Creates or updates a news release (a news article in the widget's News tab). Supports AI content generation.

Parameters

Parameter	Type	Required	Description
`id`	string	No	News item ID. Omit to create, provide to update.
`title`	string	Conditional	News title. Required when creating.
`content`	string	Conditional	HTML content. Required when creating unless `generateContent` is used.
`generateContent`	string	No	Describe the news article and AI generates HTML. Mutually exclusive with `content`.
`language`	string	No	Content language (e.g., `"en"`, `"hu"`). Defaults to `"en"` on create.
`widgetId`	string	No	Widget to show this news in. Auto-assigns the organization's default widget if omitted.
`position`	number	No	Display order, where 1 is first. Omit to append to the end. If the slot is taken, the items below shift down.

How It Works

Creating a news item:

Provide title plus either content (your HTML) or generateContent (a description for AI to write it).
The AI writes well-structured HTML news articles using headings, paragraphs, lists, and other standard elements. Generating content spends AI credits, the same as anywhere else in Yaplet.
Returns a dashboardUrl where you can review and edit the news item in the visual editor.

Updating a news item:

Provide id and the fields to change.
You can rewrite the content with AI by passing generateContent — it replaces the existing content entirely rather than editing it.
Cover images cannot be set from here. There is no image parameter; upload and attach a cover image in the dashboard editor.

Example Prompts

"Draft a news release about our new feature update — generate the content with AI."
"Write a news article titled 'Product Update v2.0' about our new dashboard features."
"Create a news item about our company milestone — we've reached 10,000 customers."
"Update the news title to 'Spring 2026 Product Update'."
"Generate a news article about our upcoming webinar series."
"Create a Hungarian language news release about our expansion to the EU market."
"Move my product update news to the top of the list."

Common Workflow Patterns

Promotional Campaign

Draft a coordinated set of engagement items:

Draft a banner → manage_outreach with type "banner"
Draft a targeted chat message → manage_outreach with type "message", page URL filter
Write a news release → manage_outreach_news with generateContent
Review and publish → open each returned dashboardUrl and switch it live

Example prompt: "Draft a complete promotional campaign: a banner for the sale announcement, a targeted chat message on the pricing page, and a news release about the sale. Generate all content with AI and give me the review links."

Feedback Collection

Draft a survey → manage_outreach with type "survey", trigger after time on page
Configure targeting → Set page URL filter and frequency
Review and publish → open the returned dashboardUrl and switch it live

Example prompt: "Draft a feedback survey that shows after 60 seconds on any page containing '/dashboard', only once per visitor, and only for US visitors."

Product Announcements

Write a news release → manage_outreach_news with generateContent
Draft a banner → manage_outreach with type "banner" to drive attention
Review and publish both → open each returned dashboardUrl and switch it live

Example prompt: "Announce our new feature: write a news release with AI-generated content about our new analytics dashboard, and draft a banner directing visitors to the news."