Campaigns Planned

Campaigns are proactive chat messages triggered by visitor behaviour. A campaign defines a trigger (URL match, time-on-page, exit intent, custom event), an audience filter, the message, and a schedule. When matched, the widget fires the message into the visitor's open chat.

Trigger kinds

List campaigns

Code samples

curl 'https://app.message.com/api/v1/campaigns' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_JWT'

const res = await fetch('https://app.message.com/api/v1/campaigns', {
  headers: { Authorization: 'Bearer ' + token }
});
const { campaigns } = await res.json();

import requests
r = requests.get(
    "https://app.message.com/api/v1/campaigns",
    headers={"Authorization": f"Bearer {token}"},
)
campaigns = r.json()["campaigns"]

require "net/http"
require "json"
uri = URI("https://app.message.com/api/v1/campaigns")
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  req = Net::HTTP::Get.new(uri)
  req["Authorization"] = "Bearer #{token}"
  http.request(req)
end
campaigns = JSON.parse(res.body)["campaigns"]

<?php
$ctx = stream_context_create([
  "http" => ["method" => "GET", "header" => "Authorization: Bearer $token"]
]);
$campaigns = json_decode(file_get_contents("https://app.message.com/api/v1/campaigns", false, $ctx), true)["campaigns"];

Get one campaign

{
  "id": "uuid",
  "version": 1,
  "name": "Cart abandonment nudge",
  "status": "active",
  "trigger": {
    "kind": "page-stay",
    "urlPattern": "/cart",
    "secondsOnPage": 30
  },
  "audience": {
    "filters": { "isReturning": true, "tag": "in-cart" }
  },
  "message": {
    "body": "Need help checking out? I can grab a code if it helps."
  },
  "schedule": {
    "businessHoursOnly": true,
    "frequencyCap": "1-per-visitor-per-day"
  },
  "createdAt": "2026-05-13T15:30:00Z"
}

Create a campaign

{
  "name": "Cart abandonment nudge",
  "trigger": {
    "kind": "page-stay",
    "urlPattern": "/cart",
    "secondsOnPage": 30
  },
  "audience": {
    "filters": { "isReturning": true }
  },
  "message": {
    "body": "Need help checking out?"
  }
}

Update a campaign

Requires expectedVersion. Edits to a running campaign take effect within ~30 seconds via the live widget config push.

Pause and resume

Toggle status between paused and active without losing config.

Campaign report

Returns impressions, engagements, replies, and (if a goal is attached) conversions for the date range.

Errors

Common pitfalls

• No frequency cap. Without one, returning visitors see the same nudge on every visit. Default to 1-per-visitor-per-day.
• Targeting "everyone". Wide audiences feel spammy. Lean on visitor attributes (returning, segment, intent) to keep the message relevant.
• Confusing campaigns with AI engagements. Campaigns are rule-driven; AI engagements are model-driven.