Outbound messages

Outbound messages let you show a proactive banner to visitors — a slim bar at the top or bottom of the page with a message and an optional button. You author and target messages from the dashboard; the SDK fetches the right one for each visitor and reports back how it performed.

This is separate from the chat widget: chat is a conversation the visitor opens, outbound is a message you push to them.

#Enable

Nothing to add to your code. Activate a message in the dashboard and the SDK picks it up on the next page load — the same way chat and session recording are switched on from Project settings.

vt.init('YOUR_PROJECT_TOKEN', {
  api_host: 'https://www.vtilt.com',
})

The SDK asks vTilt for your project's configuration on every page load, and that response says whether outbound has anything to show. A project with no active message stays completely inert, so there is nothing to switch off when you're not using it.

Everything else — the message text, button, which pages it shows on, and how often — is configured per-message in the dashboard under Outbound.

#Author a message

In the dashboard, open Outbound → New message. The editor shows a live banner preview of your copy, theme, position, and button as you edit. Preview opens a full-screen view of your project's homepage with the banner on it, so you can see overlay vs push the way visitors will.

Set:

• Message — the text shown in the banner.

• Position — top or bottom of the page.

• Display style — Overlay floats the banner over your page content (fixed to the edge); Push puts it in the page flow so the rest of the page shifts down to make room (no overlap). Overlay is the default.

• Call to action (optional) — turn on Button to add a call to action. Choose what it does:

  • Open a URL — navigates to a link (in a new or the same tab).
  • Start chat — opens the chat widget. Add an optional prefilled message to send an opening message and drop the visitor straight into a conversation (e.g. "Hi! I have a question about pricing."); leave it empty to just open the chat. Requires the chat widget to be enabled on the page.
  • No button — leave Button off for a text-only banner.

• Targeting — which pages it shows on (URL match) and, optionally, which people (using the same audience query builder as campaigns).

• Frequency — caps on how often a visitor sees it (per session, per day, lifetime, and "stop after dismiss").

Change anything and a Save draft (new) or Save (existing) button appears in the editor header. The final Activate step runs a checklist over your copy, button, targeting, and frequency caps, then activates the banner (or pauses one that's live) once the required items pass. Only active messages are ever shown.

#How targeting works

For each page view, the SDK sends the current URL (plus the visitor's ids) to vTilt, which returns the single highest-priority active message that matches. Matching considers, in order:

1. Delivery window — the message's optional start/end schedule.
2. URL match — e.g. "URL contains /pricing". Leave it as "Any page" to match everywhere.
3. Audience — an optional query over your people. vTilt resolves the visitor to their person record and checks membership, so audience-scoped messages effectively reach the people you've identified (a visitor who can't be resolved to a matching person never matches).
4. Frequency caps — a visitor who has already hit a cap (or dismissed the message) is skipped.

Single-page-app navigations are handled automatically — the SDK re-checks on route changes, so banners update as the visitor moves between pages.

#Outcomes

Every banner reports outcome events back to vTilt so you can see how it performs in the dashboard:

The per-message analytics view shows impressions, clicks, dismissals, and conversions. Dismissals are also remembered in the visitor's browser, so a dismissed banner won't flash back on the next page even before the server-side cap applies.

#Disable

Pause or archive your messages in the dashboard. With no active message there is nothing to deliver, and the SDK stops fetching outbound entirely.

To guarantee no banner can ever appear on a page — regardless of what anyone activates in the dashboard — set the flag explicitly in code. Values you pass to init always win over dashboard configuration:

vt.init('YOUR_PROJECT_TOKEN', {
  api_host: 'https://www.vtilt.com',
  outbound: { enabled: false },
})

Use that on checkout flows, embedded views, or anywhere a banner would be unwelcome.