# RightMessage - Complete Documentation for AI Agents

> RightMessage is a website personalization platform that helps creators, SaaS companies, and agencies show the right message to the right visitor. It segments visitors via surveys, ESP data, and behavioral signals, then personalizes website content, CTAs, forms, and emails for each audience segment.

## Product Overview

RightMessage operates on a simple principle: different visitors should see different content. The platform provides:

1. **Audience Segmentation** - Categorize visitors into segments (e.g., by business type, experience level, company size) via behavioral signals (page URL, ESP tags, referring domain) or interactive survey questions synced to your ESP.
2. **Website Personalization** - Swap headlines, CTAs, images, and content blocks on any page based on visitor segments. No code changes required.
3. **Conversational Flows** - Build branching survey funnels that ask questions, segment visitors, and show personalized offers/CTAs.
4. **Widgets** - Display flows on your site via modals, bars, toasters, inline embeds, or full-page takeovers.
5. **Email Personalization** - Generate Liquid template code for segment-specific email content in your ESP.
6. **Analytics** - Track campaign performance, audience breakdown, flow completion rates, and conversion goals.
7. **A/B Testing** - Split test campaign variations with statistical confidence tracking.

## MCP Server

RightMessage provides a Model Context Protocol (MCP) server that enables AI assistants to manage all aspects of the platform through natural language.

### Connection Details
- **Endpoint:** `https://api.rightmessage.com/mcp/rightmessage`
- **Protocol:** MCP over HTTP (Streamable HTTP)
- **Authentication:** Bearer token via `Authorization: Bearer YOUR_API_TOKEN_HERE` header
- **Rate limit:** 120 requests per minute

### Configuration (Claude Code)
```
claude mcp add --transport http rightmessage https://api.rightmessage.com/mcp/rightmessage --header "Authorization: Bearer YOUR_API_TOKEN_HERE"
```

### Configuration (JSON - Claude Desktop, ChatGPT)
```json
{
  "mcpServers": {
    "rightmessage": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.rightmessage.com/mcp/rightmessage",
        "--header",
        "Authorization: Bearer YOUR_API_TOKEN_HERE"
      ]
    }
  }
}
```

### Configuration (JSON - Cursor, VS Code)
```json
{
  "mcpServers": {
    "rightmessage": {
      "url": "https://api.rightmessage.com/mcp/rightmessage",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN_HERE"
      }
    }
  }
}
```

### Draft/Publish Workflow
All mutations save as drafts. Nothing affects the live website until `publish-config` is called. This provides a safety net - you can review changes before they go live.

### Resource Dependency Order
When building from scratch, create resources in this order:
1. Segment Groups (with segments) - behavioral ones are populated via signals automatically
2. Questions (optional, linked to segment groups via segment_group_id) - only needed for interactive survey flows
3. Offers and/or Forms
4. Flows (containing question nodes + offer/form nodes)
5. Widgets (attached to flows)
6. Campaigns (for page content personalization)
7. Goals (for conversion tracking)

## Complete Tool Reference (138 tools)

### Segmentation

#### list-segment-groups
List all segment groups (dimensions) in the project. Returns name, ID, segment count, and linked question info.

#### get-segment-group
Get a specific segment group with all its segments. Parameters: `id` (required).

#### create-segment-group
Create a new segment group. Parameters: `name` (required), `description`, `is_multi_winning` (boolean, allows multiple segments per visitor).

#### update-segment-group
Update a segment group. Parameters: `id` (required), `name`, `description`.

#### delete-segment-group
Remove a segment group and all its segments. Parameters: `id` (required). Warning: this also removes any targeting that references these segments.

#### create-segment
Add a segment to a group. Parameters: `segment_group_id` (required), `name` (required).

#### update-segment
Update a segment. Parameters: `id` (required), `segment_group_id` (required), `name`.

#### delete-segment
Remove a segment. Parameters: `id` (required), `segment_group_id` (required).

### Questions & Surveys

#### list-questions
List all survey questions with their linked segment groups and option counts.

#### get-question
Get a question with all answer options. Parameters: `id` (required).

#### create-question
Create a new survey question. Parameters: `segment_group_id` (required - must link to an existing segment group), `text` (required), `description`, `options` (array of answer option objects).

#### update-question
Update a question. Parameters: `id` (required), `text`, `description`.

#### delete-question
Remove a question. Parameters: `id` (required).

#### create-question-option
Add an answer option. Parameters: `question_id` (required), `label` (required), `segment_id` (maps this option to a segment).

#### update-question-option
Update an answer option. Parameters: `id` (required), `question_id` (required), `label`.

#### delete-question-option
Remove an answer option. Parameters: `id` (required), `question_id` (required).

### Campaigns

#### list-campaigns
List all personalization campaigns with their status and target URLs.

#### get-campaign
Get campaign details including targeting conditions and content changes. Parameters: `id` (required).

#### create-campaign
Create a new personalization campaign. Important: call `get-page-elements` first to get Smart Match fingerprint data for reliable element targeting. Parameters: `name` (required), `url` (target page), `changes` (array of content swap objects with audience conditions and targeting data).

#### update-campaign
Modify a campaign. Parameters: `id` (required), plus any fields to update.

#### delete-campaign
Remove a campaign. Parameters: `id` (required).

#### duplicate-campaign
Copy a campaign. Parameters: `id` (required), `name` (optional new name).

#### get-page-elements
Scan a URL and return all targetable DOM elements with Smart Match fingerprints. Parameters: `url` (required). Returns element types (H1, H2, p, button, etc.) with stable fingerprint data for use in campaign targeting.

### Flows

#### list-flows
List all conversational flows with node counts.

#### get-flow
Get a flow with all nodes and branching logic. Parameters: `id` (required).

#### create-flow
Create a new empty flow. Parameters: `name` (required).

#### create-flow-from-description
AI-powered: generate a complete flow from a plain text description. Parameters: `description` (required - natural language description of the desired flow). This is the fastest way to create complex branching flows.

#### update-flow
Update flow settings. Parameters: `id` (required), `name`.

#### delete-flow
Remove a flow. Parameters: `id` (required).

#### duplicate-flow
Copy a flow. Parameters: `id` (required), `name` (optional).

#### modify-flow
Batch operations for complex flow modifications. Preferred over sequential node operations. Parameters: `id` (required), `operations` (array of modification operations).

### Flow Nodes

#### create-flow-node
Add a node to a flow. Types: "sg" (question - requires linked question via rightAsk), "offer" (CTA/lead magnet), "redirect" (URL redirect), "form" (data capture). Parameters: `flow_id` (required), `type` (required), plus type-specific parameters.

#### update-flow-node
Update a node. Parameters: `flow_id` (required), `node_id` (required), plus fields to update.

#### delete-flow-node
Remove a node. Parameters: `flow_id` (required), `node_id` (required).

#### move-flow-node
Reposition a node. Parameters: `flow_id` (required), `node_id` (required), `position` or `after_node_id`.

### Widgets

#### list-widgets
List all widgets with their types and linked flows.

#### get-widget
Get widget details. Parameters: `id` (required).

#### create-widget
Create a widget. Types: "modal", "bar", "toaster", "inline", "takeover". Parameters: `name` (required), `type` (required), `flow_id` (required), plus display rules (pages, triggers, timing).

#### update-widget
Modify widget settings. Parameters: `id` (required), plus fields to update.

#### delete-widget
Remove a widget. Parameters: `id` (required).

#### duplicate-widget
Copy a widget. Parameters: `id` (required).

### Offers & CTAs

#### list-offers
List all offers.

#### get-offer
Get offer details. Parameters: `id` (required).

#### create-offer
Create an offer for use in flows. Parameters: `name` (required), `headline`, `body`, `button_text`, `button_url`, plus form/CTA configuration.

#### update-offer
Modify an offer. Parameters: `id` (required), plus fields to update.

#### delete-offer
Remove an offer. Parameters: `id` (required).

#### duplicate-offer
Copy an offer. Parameters: `id` (required).

### Forms

#### list-forms
List all forms.

#### get-form
Get form with all fields. Parameters: `id` (required).

#### create-form
Create a form. Parameters: `name` (required), plus form configuration.

#### update-form
Modify a form. Parameters: `id` (required), plus fields to update.

#### delete-form
Remove a form. Parameters: `id` (required).

#### duplicate-form
Copy a form. Parameters: `id` (required).

#### create-form-field
Add a field to a form. Parameters: `form_id` (required), `label` (required), `type` (text, email, phone, etc.), `required` (boolean).

#### update-form-field
Update a field. Parameters: `form_id` (required), `field_id` (required), plus fields to update.

#### delete-form-field
Remove a field. Parameters: `form_id` (required), `field_id` (required).

### Phrases

#### list-phrases
List all dynamic text phrases.

#### get-phrase
Get a phrase with all segment-specific variations. Parameters: `id` (required).

#### create-phrase
Create a phrase with segment-based text variations. Note: phrases only render within the widget engine (offers, forms, questions) - not in campaign HTML or page content. Parameters: `name` (required), `default_value`, `variations` (array of segment-to-text mappings).

#### update-phrase
Update phrase variations. Parameters: `id` (required), plus fields to update.

#### delete-phrase
Remove a phrase. Parameters: `id` (required).

### Goals & Conversions

#### list-goals
List all conversion goals.

#### get-goal
Get goal with tracked events. Parameters: `id` (required).

#### create-goal
Create a goal. Events can be: click (CSS selector), pageview (URL pattern), or custom JS. Parameters: `name` (required), `events` (array of event objects).

#### update-goal
Modify a goal. Parameters: `id` (required), plus fields to update.

#### delete-goal
Remove a goal. Parameters: `id` (required).

### Personalized Emails

#### list-personalized-emails
List all email templates.

#### get-personalized-email
Get email template with Liquid content. Parameters: `id` (required).

#### create-personalized-email
Create an email template with Liquid conditionals for segment-specific content. Parameters: `name` (required), `subject`, `body` (Liquid template), `variables` (available data).

#### update-personalized-email
Modify email content. Parameters: `id` (required), plus fields to update.

#### delete-personalized-email
Remove an email template. Parameters: `id` (required).

### Split Testing

#### list-split-tests
List all A/B tests with status.

#### get-split-test
Get test configuration. Parameters: `id` (required).

#### create-split-test
Create a split test between campaign variants. Parameters: `name` (required), `campaign_ids` (required), `goal_id`, `traffic_split`.

#### update-split-test
Modify test settings. Parameters: `id` (required), plus fields to update.

#### delete-split-test
Remove a test. Parameters: `id` (required).

#### start-split-test
Activate a test. Parameters: `id` (required).

#### end-split-test
Stop a test. Parameters: `id` (required), `winner_campaign_id` (optional).

#### get-split-test-metrics
Get results with statistical confidence. Parameters: `id` (required).

### Analytics

#### get-analytics-overview
High-level stats: total visitors, personalized sessions, conversions, segment coverage. Accepts optional date range parameters.

#### get-audience-breakdown
Visitor distribution across all segment groups. Shows percentage and count per segment.

#### get-campaign-performance
Metrics for all campaigns: impressions, conversions, conversion rate, revenue impact.

#### get-offer-performance
Click-through and conversion rates for all offers.

#### get-flow-performance
Completion rates, drop-off points, and average time for all flows.

#### get-flow-engagements
Detailed engagement metrics for a specific flow. Parameters: `id` (required).

#### get-traffic-analytics
Visitor traffic patterns over time. Accepts date range and granularity parameters.

### Visitors & Data

#### search-visitors
Search by email, name, or attributes. Parameters: `query` (required), `limit`.

#### get-visitor-profile
Full profile with all segments, custom fields, and metadata. Parameters: `id` (required).

#### get-visitor-activity
Timeline of page views, form submissions, survey responses, and conversions. Parameters: `id` (required).

#### get-data-status
Overview of data collection: total visitors, segmented percentage, active flows, and integration sync status.

### Exports

#### export-answers
Start async CSV export of survey responses. Parameters: `days` (optional, default 30). Returns a job ID for polling.

#### export-leads
Start async CSV export of captured leads. Parameters: `days` (optional, default 30). Returns a job ID.

#### get-export-status
Check export job status and get download URL when complete. Parameters: `job_id` (required).

### Integrations

#### list-integrations
List all connected ESP and marketing platform integrations.

#### get-integration
Get integration details and sync status. Parameters: `id` (required).

#### create-integration
Connect a new platform. Parameters: `provider` (required - e.g., "kit", "mailchimp", "hubspot"), `credentials` (required).

#### update-integration
Update credentials or settings. Parameters: `id` (required), plus fields to update.

#### delete-integration
Disconnect an integration. Parameters: `id` (required).

#### test-integration
Verify connection health. Parameters: `id` (required). Returns success/failure with diagnostic info.

#### get-integration-data
Get available fields, tags, lists, and segments from the connected platform. Parameters: `id` (required). Useful for mapping ESP data to RightMessage segments.

### Context & Guides

#### get-project-context
Complete project overview: all segment groups, campaigns, flows, widgets, goals, and integrations with their relationships.

#### get-email-personalization-context
Context needed for building Liquid email templates: available dimensions, segments, text variables, and example Liquid syntax.

#### list-condition-sources
All available conditions for campaign/widget targeting: segment membership, page URL, referrer, UTM params, custom properties, and more.

#### get-survey-builder-guide
Best practices and step-by-step guidance for building effective survey flows.

#### get-smart-cta-builder-guide
Guide for creating segment-aware CTAs that convert better.

#### get-quiz-results-page-guide
Guide for building personalized quiz outcome pages.

#### get-optimization-playbook
AI-powered recommendations based on your current data. Analyzes segment coverage, campaign performance, and suggests specific improvements.

#### get-preview-url
Generate a shareable URL that forces specific segments for testing. Parameters: segments to force (key-value pairs).

#### get-snippet-code
Get the JavaScript tracking snippet that needs to be installed on your website.

### Publishing & Versioning

#### publish-config
Push all draft changes live to your website. This is the only way changes become visible to visitors.

#### list-config-versions
List all published config versions with timestamps and descriptions.

#### restore-config-version
Roll back to a previous published version. Parameters: `version_id` (required).

#### undo-last-change
Revert the most recent draft modification. Useful for quick corrections.

#### get-publish-history
View recent publish events with timestamps and who triggered them.

## Supported Integrations

RightMessage integrates with these ESP and marketing platforms:
- **Email Service Providers:** Kit (ConvertKit), Mailchimp, Drip, ActiveCampaign, Klaviyo, Customer.io, Bento, Encharge, Braze
- **CRM/Marketing Automation:** HubSpot, Salesforce/Pardot, Ontraport, Infusionsoft (Keap), GoHighLevel
- **Website Platforms:** WordPress, Webflow, Shopify, Squarespace, Kajabi, Teachable, and more

## Links
- Website: https://rightmessage.com
- MCP Interactive Guide: https://rightmessage.com/mcp
- Help Center: https://rightmessage.com/help
- Integrations: https://rightmessage.com/integrations