Chat campaigns API

Access

Campaign routes require an authenticated workspace agent and the campaigns feature entitlement. Create, update, archive and duplicate actions require administrator access. Keep the workspace credential on your server.

Read campaigns

GET /api/v1/campaigns lists workspace campaigns with recent impression, click and started-chat aggregates. Use the supported status filter to include the relevant state. GET /api/v1/campaigns/:id returns one campaign.

Create a draft

POST /api/v1/campaigns accepts name, status, triggerRules and content. Use draft while configuring, then explicitly move to live. The example shows the actual request field names.

{
  "name": "Pricing help",
  "status": "draft",
  "triggerRules": {
    "urlMatch": {
      "operator": "contains",
      "value": "/pricing"
    },
    "showAfterMs": 15000,
    "frequency": "session",
    "officeHoursOnly": true
  },
  "content": {
    "body": "Need help choosing a plan?",
    "quickReplies": [
      {
        "label": "Ask a question",
        "action": "start-chat"
      },
      {
        "label": "Not now",
        "action": "dismiss"
      }
    ]
  }
}

Trigger and content fields

triggerRules supports urlMatch, showAfterMs (0–600000), exitIntent, scrollDepthPct (0–100), frequency (once, session or always) and officeHoursOnly. URL operators are contains, equals, starts-with, ends-with and regex. There is no public custom-event or idle trigger.

content requires body (up to 2000 characters) and optionally agentName, agentAvatarUrl and up to three quickReplies. Reply actions are start-chat, dismiss and navigate; navigation uses value.

Update and archive

PATCH /api/v1/campaigns/:id updates name, status, triggerRules or content. The supplied nested objects replace their prior values, so send all fields you intend to retain. DELETE /api/v1/campaigns/:id archives. POST /api/v1/campaigns/:id/duplicate creates a new draft. An archived row cannot be edited through PATCH.

Verify the published installation

Test the published page in a separate browser session. Confirm widget.js loads, the launcher opens, a visitor message reaches Inbox and an agent reply returns. Test with your site’s actual content security policy, consent controls and mobile layout.

The script connects to its own origin by default. With the standard snippet, allow the relevant script and HTTPS/WSS requests to app.message.com. Check image, media and injected-style requirements separately. Do not put an agent JWT or integration secret in the page.