Skip to main content
This guide walks you through the core integration steps to start using Chameleon programmatically.

​
Prerequisites

Your Account Token is embedded in the JavaScript snippet (client-side) and is safe to include in frontend code. Your API Secret is used for REST API authentication (server-side) — keep it secure and never expose it in client-side code.

​
Step 1: Install Chameleon

Add Chameleon to your application. Visit the Install page in your dashboard to get your personalized snippet and choose your installation method. Installation methods:
MethodBest for
npmReact, Vue, Angular, and other SPAs
JavaScriptDirect script tag in your HTML
SegmentIf you use Segment as your CDP
Google Tag ManagerIf you manage scripts via GTM
FreshpaintIf you use Freshpaint as your CDP
Using npm (recommended for SPAs): 
npm install @chamaeleonidae/chmln

import chmln from '@chamaeleonidae/chmln';
chmln.init('YOUR_ACCOUNT_TOKEN');
Using the script tag: 
<script>
!function(d,w){var t='YOUR_ACCOUNT_TOKEN',c='chmln',i=d.createElement('script');
i.src='https://fast.chameleon.io/messo/'+t+'/messo.min.js';
i.async=1;d.head.appendChild(i);w[c]=w[c]||function(){(w[c].q=w[c].q||[]).push(arguments)};
}(document,window);
</script>
Replace YOUR_ACCOUNT_TOKEN with the token from your Install page. For Segment, GTM, and Freshpaint setup, follow the instructions on the Install page.

​
Step 2: Identify your users

Once the snippet is installed, identify users so Chameleon can target them with Experiences. Call chmln.identify when the user is known (e.g., after login). 
chmln.identify(USER.ID_IN_DB, {
  email: USER.EMAIL,
  name: USER.NAME,
  created: USER.SIGN_UP_DATE,  // ISO 8601 format: "2024-01-15T10:30:00Z"
  plan: USER.PLAN,

  // Optional: company/account data
  company: {
    uid: COMPANY.ID_IN_DB,
    name: COMPANY.NAME,
    plan: COMPANY.PLAN,
  },
});
After identifying, visit your app and verify the user appears in Chameleon Dashboard → Users. For full details, see Send user properties via JS API.

​
Step 3: Make your first REST API call

Use the REST API to read data from Chameleon. Let’s list your Tours. 
curl -H "X-Account-Secret: YOUR_API_SECRET" \
  https://api.chameleon.io/v3/edit/tours
You should get a response like: 
{
  "tours": [
    {
      "id": "5f3c4232c712de665632a6d5",
      "name": "Welcome Tour",
      "style": "auto",
      "published_at": "2024-01-15T12:00:00Z"
    }
  ],
  "cursor": {
    "limit": 50,
    "before": "5f3c4232c712de665632a6d5"
  }
}
Replace YOUR_API_SECRET with your API Secret from Settings → Tokens.
For the full REST API reference, see REST API Overview.

​
Step 4: Trigger an Experience via API

Use the Deliveries API to trigger a Tour for a specific user on their next page load: 
curl -X POST \
  -H "X-Account-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "model_kind": "tour",
    "model_id": "TOUR_ID",
    "uid": "USER_UID"
  }' \
  https://api.chameleon.io/v3/edit/deliveries
The Tour will display to the user on their next page load where Chameleon is installed.

​
Step 5: Set up a webhook

Receive real-time notifications when users interact with your Experiences. Register a webhook endpoint: 
curl -X POST \
  -H "X-Account-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/chameleon",
    "topics": ["tour.completed", "response.finished"]
  }' \
  https://api.chameleon.io/v3/edit/webhooks
When a user completes a Tour or finishes a Microsurvey, Chameleon will POST a JSON payload to your endpoint. See Webhooks Overview for payload schemas and verification.

​
Next steps

JavaScript API

Send user data, track events, and show Experiences from your frontend.

REST API Reference

Full reference for all REST API endpoints.

Webhooks

Receive real-time data from Chameleon Experiences.

Filters & Segmentation

Target specific users with powerful filter expressions.