diff --git a/README.md b/README.md index eee3104..8da788b 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,40 @@ # Chameleon API Docs -A descriptions of the routing and endpoints available on the Chameleon API +Documentation for the Chameleon API routing and endpoints. -The documentation can be viewed locally by running any webserver in the `docs` directory. - -For example, the following command will start a WEBrick server available on http://localhost:8000: +The documentation can be viewed locally by running any webserver in the `docs` directory: ``` ruby -run -e httpd docs -p 8000 -``` \ No newline at end of file +``` + +## Status & Guidelines + +### Outstanding Work +- Complete remaining 4 webhook examples: `tour.snoozed`, `survey.snoozed`, `helpbar.item.error`, `alert.triggered` + +### Example Data Standards +When updating documentation, follow these standards: + +#### **Dates**: Use 2029 dates consistently in ISO 8601 format (`2029-MM-DDTHH:mm:ss.sssZ`) + +#### **Privacy**: Never use real user data - use fictional but realistic examples: +- Email format: `user@example.com`, `firstname.lastname@company.tld` +- Use example.com, example.io domains for fictional companies + +#### **IDs**: Use consistent 24-character hex patterns: `5f3c4232c712de665632****` + +### Suggested Improvements +**High Priority:** +- Add navigation and "Back to Overview" links +- Add visual callouts for warnings/tips +- Complete cURL examples for all endpoints + +**Medium Priority:** +- Add troubleshooting sections +- Enhance schema tables with "Required" column +- Create quick start guide + +**Future Considerations:** +- Interactive API explorer +- Multi-language SDK examples \ No newline at end of file diff --git a/docs/apis/companies.md b/docs/apis/companies.md index c5acf1c..242bd8a 100644 --- a/docs/apis/companies.md +++ b/docs/apis/companies.md @@ -39,9 +39,9 @@ Retrieve a single Company. #### HTTP Request ``` -GET https://api.trychameleon.com/v3/analyze/companies/:id +GET https://api.chameleon.io/v3/analyze/companies/:id # OR -GET https://api.trychameleon.com/v3/analyze/company?uid=:uid +GET https://api.chameleon.io/v3/analyze/company?uid=:uid ``` | param | - | description | @@ -54,12 +54,8 @@ GET https://api.trychameleon.com/v3/analyze/company?uid=:uid { "company": { "id": "5f3c4232c712de665632a2a1", - "created_at": "2029-04-07T12:38:00Z", - "uid": "1868", - "domain": "example.com", - "plan": "custom-92", - "clv": 231902.42, - ... + "created_at": "2029-01-10T08:00:00.000Z", + "uid": "company_abc123" } } ``` @@ -89,7 +85,7 @@ GET|POST https://api.chameleon.io/v3/analyze/companies # As a URL parameter expand[profile]=min&expand[company]=skip -# In the Reqeust body +# In the Request body {"expand":{"profile":"min","company":"skip"}} ``` @@ -176,7 +172,7 @@ curl -H "X-Account-Secret: ACCOUNT_SECRET" \ -H "Content-Type: application/json" \ -X POST \ -d '{"filters":[{"kind":"property","prop":"uid","op":"eq","value":"123"}]}' \ - https://api.trychameleon.com/v3/analyze/companies + https://api.chameleon.io/v3/analyze/companies ``` ## Delete a Company :id=companies-delete @@ -195,9 +191,9 @@ The associated profiles can also be removed by passing `cascade=profiles` with t Either `id` or `uid` is required. ``` -DELETE https://api.trychameleon.com/v3/edit/companies/:id +DELETE https://api.chameleon.io/v3/edit/companies/:id # OR -DELETE https://api.trychameleon.com/v3/edit/company?uid=:uid +DELETE https://api.chameleon.io/v3/edit/company?uid=:uid ``` #### HTTP Response @@ -217,9 +213,9 @@ The Deletion is an internal Chameleon record that can be referenced as proof of Deleting a company and all profiles associated with it can be done by passing `cascade=profiles`: ``` -DELETE https://api.trychameleon.com/v3/edit/companies/:id?cascade=profiles +DELETE https://api.chameleon.io/v3/edit/companies/:id?cascade=profiles # OR -DELETE https://api.trychameleon.com/v3/edit/company?uid=:uid&cascade=profiles +DELETE https://api.chameleon.io/v3/edit/company?uid=:uid&cascade=profiles ``` #### HTTP Response diff --git a/docs/apis/profiles-search.md b/docs/apis/profiles-search.md index ff7d142..adc355f 100644 --- a/docs/apis/profiles-search.md +++ b/docs/apis/profiles-search.md @@ -301,7 +301,7 @@ Notes: { "id": "5f3c4232c712de665632a6d5", "uid": 18821, - "email": "leon@chmln.co", + "email": "user1@example.com", "role": "admin", "invited_users_count": 4, ... @@ -309,7 +309,7 @@ Notes: { "id": "5f3c4232c712de665632a6d6", "uid": 18829, - "email": "prehensile@chmln.co", + "email": "user2@example.com", "role": "admin", "invited_users_count": 6, ... diff --git a/docs/apis/profiles.md b/docs/apis/profiles.md index f713184..df3ab91 100644 --- a/docs/apis/profiles.md +++ b/docs/apis/profiles.md @@ -76,7 +76,7 @@ When using a **GET** request with parameters: ``` ?id=5f3c4232c712de665632a6d5 ?uid=18821 -?email=leon@chmln.co +?email=user@example.com ``` When using a **POST** request send one of these properties: @@ -85,7 +85,7 @@ When using a **POST** request send one of these properties: { "id": "5f3c4232c712de665632a6d5", "uid": 18821, - "email": "leon@chmln.co" + "email": "user@example.com" } ``` @@ -97,13 +97,27 @@ When using a **POST** request send one of these properties: { "profile": { "id": "5f3c4232c712de665632a6d5", - "uid": 18821, - "email": "leon@chmln.co", - "first_name": "Leon", - "role": "admin", - "last_import_at": "2029-04-07T12:18:00Z", - "invited_users_count": 4, - ... + "created_at": "2029-03-15T10:30:00.000Z", + "updated_at": "2029-04-07T12:18:00.000Z", + "uid": "user_18821", + "company_id": "5f3c4232c712de665632a6e8", + "browser_x": 1920, + "browser_tz": -8, + "browser_l": "en-US", + "browser_n": "chrome", + "browser_k": "desktop", + "percent": 42.87, + "last_seen_at": "2029-04-07T11:45:00.000Z", + "last_seen_session_count": 23, + "delivery_ids": [ + "5f3c4232c712de665632a6f1", + "5f3c4232c712de665632a6f2" + ], + "company": { + "id": "5f3c4232c712de665632a6e8", + "created_at": "2029-01-10T08:00:00.000Z", + "uid": "company_abc123" + } } } ``` diff --git a/docs/apis/segments.md b/docs/apis/segments.md index ba9193c..4f1caa3 100644 --- a/docs/apis/segments.md +++ b/docs/apis/segments.md @@ -30,7 +30,7 @@ With the Chameleon API for Segments, you can: > For a full list of your User / Company Properties see the [Properties API](apis/properties.md) -## Listing Segments :id=segments-index +## List Segments :id=segments-index Retrieve a list of segments according to the specified parameters. @@ -190,3 +190,46 @@ GET https://api.chameleon.io/v3/edit/segments/:id/:kind } } ``` + +------ + +## Listing Related Experiences :id=segment-experiences-index + +A Segment can be configured to be attached to many Chameleon Experiences, including [Microsurveys](apis/surveys.md), [Tours](apis/tours.md) and [Launchers](apis/launchers.md) and [Rate Limit Groups](apis/limit-groups.md). This endpoint allows you to list any of these items that are currently attached to the Segment given with the ID + +#### HTTP Request + +``` +GET https://api.chameleon.io/v3/edit/segments/:id/:kind +``` + +| param | - | description | +|---|---|---| +| `id` | required | A Segment ID to lookup +| `kind` | required | One of `tour`, `survey` or `launcher` + +#### HTTP Response + +```json +{ + "segment": { + "id": "5f3c4232c712de665632a6d7", + "name": "Admins", + ... + }, + "tours": [ + { + "id": "5f3c4232c712de665632a6d5", + "name": "Revamped Dashboard Launch", + "style": "auto", + "position": 4, + "published_at": "2029-04-07T12:18:00Z", + ... + }, + ], + "cursor": { + "limit": 50, + "before": "5f3c4232c712de665632a2a1" + } +} +``` diff --git a/docs/apis/surveys.md b/docs/apis/surveys.md index 27aac9c..11744ec 100644 --- a/docs/apis/surveys.md +++ b/docs/apis/surveys.md @@ -62,22 +62,47 @@ GET https://api.chameleon.io/v3/edit/surveys "surveys": [ { "id": "5f3c4232c712de665632a6d5", - "name": "Task #2 completion CES", + "created_at": "2029-03-10T11:20:00.000Z", + "updated_at": "2029-04-05T09:30:00.000Z", + "name": "Product Satisfaction Survey", "position": 1, - "published_at": "2029-04-07T12:18:00Z", - ... + "segment_id": "5f3c4232c712de665632a6d9", + "published_at": "2029-03-15T08:00:00.000Z", + "tag_ids": ["5f3c4232c712de665632a6f8", "5f3c4232c712de665632a6f9"], + "stats": { + "started_count": 234, + "last_started_at": "2029-04-05T08:45:00.000Z", + "completed_count": 187, + "last_completed_at": "2029-04-05T08:30:00.000Z", + "exited_count": 47, + "last_exited_at": "2029-04-05T08:20:00.000Z" + }, + "rate_unlimit_at": null, + "last_dropdown_items": ["Very Satisfied", "Satisfied", "Neutral", "Dissatisfied"] }, { "id": "5f3c4232c712de665632a2a3", - "name": "Admin account setup #1 completion question", - "position": 0, - "published_at": "2029-04-07T12:38:00Z", - ... - }, - ... + "created_at": "2029-02-20T14:15:00.000Z", + "updated_at": "2029-03-25T16:22:00.000Z", + "name": "Feature Request Collection", + "position": 2, + "segment_id": "5f3c4232c712de665632a6e1", + "published_at": "2029-02-25T10:00:00.000Z", + "tag_ids": ["5f3c4232c712de665632a6fa"], + "stats": { + "started_count": 89, + "last_started_at": "2029-03-24T15:10:00.000Z", + "completed_count": 73, + "last_completed_at": "2029-03-24T14:55:00.000Z", + "exited_count": 16, + "last_exited_at": "2029-03-24T15:20:00.000Z" + }, + "rate_unlimit_at": "2029-04-15T00:00:00.000Z", + "last_dropdown_items": ["Better Analytics", "Mobile App", "API Improvements", "More Integrations"] + } ], "cursor": { - "limit": 50, + "limit": 2, "before": "5f3c4232c712de665632a2a3" } } @@ -146,11 +171,24 @@ GET https://api.chameleon.io/v3/edit/surveys/:id ```json { "survey": { - "id": "5f3c4232c712de665632a2a1", - "name": "Admin Self-serve menu", - "position": 0, - "published_at": "2029-04-07T12:38:00Z", - ... + "id": "5f3c4232c712de665632a6d5", + "created_at": "2029-03-10T11:20:00.000Z", + "updated_at": "2029-04-05T09:30:00.000Z", + "name": "Product Satisfaction Survey", + "position": 1, + "segment_id": "5f3c4232c712de665632a6d9", + "published_at": "2029-03-15T08:00:00.000Z", + "tag_ids": ["5f3c4232c712de665632a6f8", "5f3c4232c712de665632a6f9"], + "stats": { + "started_count": 234, + "last_started_at": "2029-04-05T08:45:00.000Z", + "completed_count": 187, + "last_completed_at": "2029-04-05T08:30:00.000Z", + "exited_count": 47, + "last_exited_at": "2029-04-05T08:20:00.000Z" + }, + "rate_unlimit_at": null, + "last_dropdown_items": ["Very Satisfied", "Satisfied", "Neutral", "Dissatisfied"] } } ``` diff --git a/docs/apis/tours.md b/docs/apis/tours.md index 3e54f11..3c19877 100644 --- a/docs/apis/tours.md +++ b/docs/apis/tours.md @@ -30,7 +30,7 @@ With the Chameleon API for Tours, you can: | `updated_at` | timestamp | The last time any property was updated | | `archived_at` | timestamp | The time when this was archived | | `name` | string | The name given by an administrator of Chameleon | -| `style` | string | The delivery method of this Tour: One of `auto` or `manual` | +| `style` | string | The delivery method of this Tour: `auto` (triggers automatically based on conditions) or `manual` (requires manual triggering via URL or API) | | `position` | number | The order that these appear in lists (starting from 0) | | `tour_link_url` | string | When `style=manual` this URL is loaded to start the Tour | | `experiment_at` | timestamp | When [Experimentation](https://help.chameleon.io/en/articles/1069709-a-b-testing-chameleon-tours) was turned on. | @@ -72,24 +72,55 @@ GET https://api.chameleon.io/v3/edit/tours "tours": [ { "id": "5f3c4232c712de665632a6d5", - "name": "Revamped Dashboard Launch", + "created_at": "2029-03-01T14:20:00.000Z", + "updated_at": "2029-04-07T12:18:00.000Z", + "archived_at": null, + "name": "Dashboard Onboarding Tour", "style": "auto", - "position": 4, - "published_at": "2029-04-07T12:18:00Z", - ... + "position": 1, + "tour_link_url": null, + "experiment_at": "2029-03-15T10:00:00.000Z", + "experiment_range": "0,50", + "segment_id": "5f3c4232c712de665632a6d9", + "published_at": "2029-03-05T09:00:00.000Z", + "tag_ids": ["5f3c4232c712de665632a6f5", "5f3c4232c712de665632a6f6"], + "stats": { + "started_count": 1247, + "last_started_at": "2029-04-07T11:30:00.000Z", + "completed_count": 892, + "last_completed_at": "2029-04-07T11:15:00.000Z", + "exited_count": 355, + "last_exited_at": "2029-04-07T10:45:00.000Z" + }, + "rate_unlimit_at": null }, { "id": "5f3c4232c712de665632a2a1", - "name": "Growth plan upsell banner 2029-02", - "style": "auto", - "position": 3, - "published_at": "2029-04-07T12:18:00Z", - ... - }, - ... + "created_at": "2029-02-15T16:45:00.000Z", + "updated_at": "2029-03-20T13:22:00.000Z", + "archived_at": null, + "name": "Feature Announcement - New Analytics", + "style": "manual", + "position": 2, + "tour_link_url": "https://app.example.com/tours/feature-announcement", + "experiment_at": null, + "experiment_range": null, + "segment_id": "5f3c4232c712de665632a6e1", + "published_at": "2029-02-20T08:00:00.000Z", + "tag_ids": ["5f3c4232c712de665632a6f7"], + "stats": { + "started_count": 456, + "last_started_at": "2029-03-19T15:20:00.000Z", + "completed_count": 387, + "last_completed_at": "2029-03-19T14:55:00.000Z", + "exited_count": 69, + "last_exited_at": "2029-03-19T16:10:00.000Z" + }, + "rate_unlimit_at": "2029-04-01T00:00:00.000Z" + } ], "cursor": { - "limit": 50, + "limit": 2, "before": "5f3c4232c712de665632a2a1" } } @@ -167,12 +198,28 @@ GET https://api.chameleon.io/v3/edit/tours/:id ```json { "tour": { - "id": "5f3c4232c712de665632a2a1", - "name": "Growth plan upsell banner 2029-02", + "id": "5f3c4232c712de665632a6d5", + "created_at": "2029-03-01T14:20:00.000Z", + "updated_at": "2029-04-07T12:18:00.000Z", + "archived_at": null, + "name": "Dashboard Onboarding Tour", "style": "auto", - "position": 3, - "published_at": "2029-04-07T12:18:00Z", - ... + "position": 1, + "tour_link_url": null, + "experiment_at": "2029-03-15T10:00:00.000Z", + "experiment_range": "0,50", + "segment_id": "5f3c4232c712de665632a6d9", + "published_at": "2029-03-05T09:00:00.000Z", + "tag_ids": ["5f3c4232c712de665632a6f5", "5f3c4232c712de665632a6f6"], + "stats": { + "started_count": 1247, + "last_started_at": "2029-04-07T11:30:00.000Z", + "completed_count": 892, + "last_completed_at": "2029-04-07T11:15:00.000Z", + "exited_count": 355, + "last_exited_at": "2029-04-07T10:45:00.000Z" + }, + "rate_unlimit_at": null } } ``` diff --git a/docs/concepts/authentication.md b/docs/concepts/authentication.md index d9da850..d16a9da 100644 --- a/docs/concepts/authentication.md +++ b/docs/concepts/authentication.md @@ -6,7 +6,7 @@ ## Basics -Every request uses the base URL of `api.trychameleon`, is authenticated with either the `X-Account-Secret` header or `account_secret` parameter and uses `https://`. Endpoints return singular/plural top-level resource names depending on the requested resource. +Every request uses the base URL of `https://api.chameleon.io` (recommended) or `https://api.trychameleon.com`, is authenticated with either the `X-Account-Secret` header or `account_secret` parameter. Endpoints return singular/plural top-level resource names depending on the requested resource. Your secret token can be [generated here](https://app.chameleon.io/settings/tokens). All tokens are account-specific and can only be downloaded once. Make sure you keep your secret token secure. Do not share it in public accessible areas, as it represents the right to access your data. To check your Account Secret token simply make this request: @@ -20,10 +20,10 @@ To receive: ```json { "account": { - "id": "5f3c4232c712de665632a6d4" + "id": "54fe3b303533320003070000" }, "user": { - "id": "5f3c4232c712de665632a6d9" + "id": "5490e42d6535370002000000" } } ``` diff --git a/docs/concepts/errors.md b/docs/concepts/errors.md index 26d60f7..bcaf9ce 100644 --- a/docs/concepts/errors.md +++ b/docs/concepts/errors.md @@ -4,8 +4,9 @@ --- -## Status Code 403 :id=code-403 -Account token is not valid or has been revoked +## HTTP 403 Forbidden :id=code-403 + +**Account token is not valid or has been revoked** ```json { @@ -14,11 +15,11 @@ Account token is not valid or has been revoked } ``` -## Status Code 404 :id=code-404 +## HTTP 404 Not Found :id=code-404 -Endpoint or Resource not found +**Endpoint or Resource not found** -404's happen for a couple of reasons: +404 errors happen for a couple of reasons: - The URL was not pasted correctly from these docs. URLs have an environment specifier directly after the version, make sure to include this - A resource/collection you tried to access is not found for this Secret token @@ -30,9 +31,9 @@ Endpoint or Resource not found } ``` -## Status Code 409 :id=code-409 +## HTTP 409 Conflict :id=code-409 -Conflicting state of the Resource +**Conflicting state of the Resource** - The Tour is not live when trying to create a Delivery - The specified update is not compatible with the current state of the Model @@ -45,9 +46,9 @@ Conflicting state of the Resource } ``` -## Status Code 422 :id=code-422 +## HTTP 422 Unprocessable Entity :id=code-422 -The request parameters cannot be processed as-is +**The request parameters cannot be processed as-is** - The parameter that is specifies a timestamp cannot be parsed/interpreted as a timestamp - The identifier is missing when looking up a User Profile @@ -59,9 +60,9 @@ The request parameters cannot be processed as-is } ``` -## Status Code 429 :id=code-429 +## HTTP 429 Too Many Requests :id=code-429 -You have made too many concurrent or bucketed requests and exceeded your Rate limit. +**You have made too many concurrent or bucketed requests and exceeded your rate limit.** See also [Rate limiting](concepts/rate-limiting.md) @@ -82,11 +83,11 @@ X-Ratelimit-Limit: 2 } ``` -## Status Code 500 :id=code-500 +## HTTP 500 Internal Server Error :id=code-500 -Server error +**Server error** -An Internal server error occurred (one that we otherwise had not planned on receiving). Typically these issues stem from downstream issues such as when a database is in the middle of failing over, an External dependency cannot be met temporarily or less often our code is not working +An internal server error occurred (one that we otherwise had not planned on receiving). Typically these issues stem from downstream issues such as when a database is in the middle of failing over, an External dependency cannot be met temporarily or less often our code is not working ```json { @@ -95,9 +96,11 @@ An Internal server error occurred (one that we otherwise had not planned on rece } ``` -## Status Code 503 :id=code-503 +## HTTP 503 Service Unavailable :id=code-503 + +**Server not available or backend didn't respond in time** -Server not available or backend didn't respond in time -- possibly not a JSON response depending on the origin of the 503 +Possibly not a JSON response depending on the origin of the 503. Unexpected maintenance, API downtime or the inability to shed enough load with [Rate limiting](rate-limiting.md) @@ -108,9 +111,9 @@ Unexpected maintenance, API downtime or the inability to shed enough load with [ } ``` -## Status Code 504 :id=code-504 +## HTTP 504 Gateway Timeout :id=code-504 -The Server contacted or proxied your request to a different Service which took too long to respond +**The server contacted or proxied your request to a different service which took too long to respond** This can happen when a request is too complex or the system load is too high. You may retry your request again after a suitable delay. diff --git a/docs/js/profiles.md b/docs/js/profiles.md index d28e9e8..830851b 100644 --- a/docs/js/profiles.md +++ b/docs/js/profiles.md @@ -110,16 +110,15 @@ Here are some more examples of what you might send (in Ruby, Javascript, Ajax an <% end %> ``` -**Javascript:** +**JavaScript:** -``` +```javascript // Add the snippet here with account id (i.e. config.chameleonAccountId) // Assuming you preload your page with a current user -(function() { - if(currentUser.id) { - chmln.identify({ - uid: currentUser.id, +(() => { + if (currentUser.id) { + chmln.identify(currentUser.id, { created: currentUser.createdAt, email: currentUser.email, plan: currentUser.planName, @@ -131,12 +130,12 @@ Here are some more examples of what you might send (in Ruby, Javascript, Ajax an **Ajax:** -```JavaScript +```javascript // Add the snippet here with account id (i.e. config.chameleonAccountId) // Assuming you call `currentUserLoaded` after fetching the user -(function() { - var currentUserLoaded = function(currentUser) { +(() => { + const currentUserLoaded = (currentUser) => { chmln.identify(currentUser.id, { created: currentUser.createdAt, email: currentUser.email, @@ -145,12 +144,18 @@ Here are some more examples of what you might send (in Ruby, Javascript, Ajax an }); }; - var xhr = $.get('/user.json'); - xhr.done(function(data) { - // Setup other aspects of the environment - - currentUserLoaded(data.user); - }); + // Using fetch API (modern) + fetch('/user.json') + .then(response => response.json()) + .then(data => { + // Setup other aspects of the environment + currentUserLoaded(data.user); + }) + .catch(error => console.error('Error fetching user:', error)); + + // Or using jQuery (legacy) + // const xhr = $.get('/user.json'); + // xhr.done(data => currentUserLoaded(data.user)); })(); ``` @@ -178,7 +183,7 @@ Use this function to de-identify the user and stop Chameleon from operating on t - When the user is logged out of a single page app that does not perform a full-page refresh - When your application enters a "mode" where automatic delivery of Chameleon Experiences should no longer happen (i.e. in full-screen mode) -```JavaScript +```javascript chmln.clear(); ``` diff --git a/docs/webhooks/automation-guide.md b/docs/webhooks/automation-guide.md new file mode 100644 index 0000000..029153b --- /dev/null +++ b/docs/webhooks/automation-guide.md @@ -0,0 +1,357 @@ +# Webhook Automation Guide for Non-Technical Users + +**Transform Chameleon webhook data into actionable insights using no-code automation tools** + +## Overview + +This guide shows you how to use webhook data from Chameleon to create powerful automations without writing code. Whether you want alerts when tours go live, reports on user engagement, or notifications about survey responses, you can build these workflows using tools like Zapier, Make.com, Pipedream, or Microsoft Power Automate. + +## What You Can Build + +### 🚨 **Smart Monitoring & Alerts** +- Get notified when high-value customers complete onboarding tours +- Alert when tours fail to display due to technical issues +- Monitor API-triggered tours that might need manual review +- Track completion rates dropping below thresholds + +### πŸ“Š **Automated Reporting** +- Weekly digest of tour performance across different user segments +- Survey response summaries with sentiment analysis +- User engagement reports by department or plan type +- Onboarding funnel analysis with completion metrics + +### 🎯 **Targeted Follow-ups** +- Send personalized emails based on survey responses +- Create support tickets for users who exit critical tours +- Add high-engagement users to special segments in your CRM +- Trigger sales outreach for users showing product interest + +### πŸ“ˆ **Data Integration** +- Send engagement data to your analytics platform +- Update customer profiles in your CRM with tour completion status +- Create custom events in your product analytics tool +- Sync user behavior data with marketing automation platforms + +--- + +## Platform-Specific Setup Guides + +### Zapier (Beginner-Friendly) +**Best for:** Simple workflows, pre-built integrations with popular tools +**Cost:** Free plan available, paid plans start at $20/month + +### Make.com (Most Powerful) +**Best for:** Complex logic, data transformation, advanced filtering +**Cost:** Free plan available, paid plans start at $9/month + +### Pipedream (Developer-Friendly) +**Best for:** Custom logic, API integrations, data processing +**Cost:** Generous free tier, paid plans start at $19/month + +### Microsoft Power Automate (Enterprise) +**Best for:** Office 365 integration, enterprise workflows +**Cost:** Included with many Office 365 plans + +--- + +## Use Case #1: Smart Tour Monitoring with Digest Alerts + +**Problem:** Getting overwhelmed by individual tour notifications, need summarized insights +**Solution:** Collect tour events during the day, send intelligent daily/weekly summaries + +### What You'll Build +- Filters tours that need attention (API-triggered, missing URL rules, low completion rates) +- AI-powered analysis that prioritizes issues and provides recommendations +- Digest-style notifications that prevent alert fatigue +- Direct links to review tours in Chameleon dashboard + +### Implementation Overview +1. **Data Collection:** Store relevant tour events in a temporary database +2. **Smart Filtering:** Only capture tours meeting specific criteria (API-triggered, configuration issues) +3. **Scheduled Analysis:** Daily/weekly AI analysis of collected data +4. **Intelligent Notifications:** Send curated summaries with action items + +**Expected Results:** 5-10 meaningful alerts per week instead of hundreds of individual events + +--- + +## Use Case #2: Survey Response Analysis & Follow-up + +**Problem:** Need to act quickly on survey feedback and identify trends +**Solution:** Automatically analyze responses and trigger appropriate follow-up actions + +### What You'll Build +- Instant alerts for negative feedback or low NPS scores +- Automatic sentiment analysis of open-text responses +- CRM updates based on user satisfaction levels +- Support ticket creation for users reporting issues + +### Key Webhook Topics +- `survey.completed` - Full survey submissions +- `response.finished` - Individual question responses + +### Sample Workflow +1. **Survey Completion Trigger:** User completes satisfaction survey +2. **Sentiment Analysis:** AI analyzes text responses for mood/issues +3. **Smart Routing:** + - High satisfaction β†’ Add to "Champions" segment in CRM + - Low satisfaction β†’ Create support ticket with response details + - Neutral β†’ Add to nurture email sequence + +### Implementation Steps +1. Set up webhook for `survey.completed` events +2. Add OpenAI integration for sentiment analysis +3. Configure conditional logic based on scores/sentiment +4. Connect to your CRM, support system, or email platform + +**Expected Results:** Immediate follow-up on critical feedback, automated customer success workflows + +--- + +## Use Case #3: Onboarding Completion Tracking + +**Problem:** Need visibility into which users complete onboarding and where they drop off +**Solution:** Track tour progression and automatically update user records with completion status + +### What You'll Build +- Completion tracking across multi-step onboarding flows +- Automatic user tagging based on progress +- Alerts for users who exit before completing critical steps +- Weekly reports on onboarding funnel performance + +### Key Webhook Topics +- `tour.started` - Track onboarding initiation +- `tour.completed` - Mark successful completion +- `tour.exited` - Identify drop-off points + +### Sample Workflow +1. **Tour Start:** User begins "Product Setup Tour" +2. **Progress Tracking:** Store completion status in CRM/database +3. **Exit Analysis:** If user exits early, categorize by step and reason +4. **Completion Celebration:** Send congratulations email with next steps + +### Data You'll Capture +- User demographics (role, company size, plan type) +- Completion rates by user segment +- Common exit points and reasons +- Time-to-completion metrics + +**Expected Results:** Clear onboarding funnel insights, reduced drop-off through targeted intervention + +--- + +## Use Case #4: High-Value User Engagement Alerts + +**Problem:** Want to personally follow up with important prospects or customers +**Solution:** Get real-time notifications when VIP users engage with key content + +### What You'll Build +- Real-time alerts for enterprise prospects viewing pricing tours +- Notifications when existing customers explore new features +- Sales team alerts for high-engagement trial users +- Customer success notifications for at-risk accounts showing renewed interest + +### Sample Workflow +1. **VIP User Activity:** Enterprise prospect starts "Advanced Features Tour" +2. **Enrichment:** Look up user details and account information +3. **Smart Notification:** Send personalized Slack message to account owner +4. **CRM Update:** Log engagement event with tour details + +### Implementation Logic +``` +IF user.plan = "enterprise" OR user.team_size > 50 +AND tour.name contains "pricing" OR "advanced" +THEN notify account_owner via Slack +AND update CRM with engagement details +``` + +**Expected Results:** Never miss high-value engagement opportunities, personalized follow-up at scale + +--- + +## Use Case #5: Product Adoption Insights + +**Problem:** Need to understand which features users discover and adopt through tours +**Solution:** Analyze tour completion patterns to identify successful feature introductions + +### What You'll Build +- Feature adoption tracking based on tour completions +- User segmentation by features explored +- Product team insights on tour effectiveness +- Automatic feature usage reports + +### Key Webhook Topics +- `tour.completed` - Feature tour completion +- `tour.button.clicked` - Specific feature interactions +- `embed.completed` - Feature callout engagement + +### Sample Analysis +- Which features are most/least discovered through tours? +- What user segments engage most with feature education? +- Which tour formats drive highest feature adoption? +- How does tour completion correlate with long-term product usage? + +**Expected Results:** Data-driven insights for product team, improved feature adoption strategies + +--- + +## General Implementation Framework + +### Step 1: Choose Your Automation Platform + +**For Beginners:** Start with Zapier - easiest setup, good for simple workflows +**For Power Users:** Use Make.com - more control, better for complex logic +**For Developers:** Try Pipedream - code-friendly, powerful data processing +**For Enterprise:** Consider Power Automate - integrates well with Microsoft ecosystem + +### Step 2: Set Up Chameleon Webhook + +1. **Go to Chameleon Dashboard:** Integrations β†’ Webhooks +2. **Create New Webhook:** Add your automation platform's webhook URL +3. **Select Topics:** Choose relevant webhook topics for your use case +4. **Configure Security:** Set webhook secret for verification +5. **Test Connection:** Send test event to verify setup + +### Step 3: Build Your Automation Logic + +**Basic Structure:** +1. **Trigger:** Receive webhook from Chameleon +2. **Filter:** Apply conditions to only process relevant events +3. **Transform:** Extract and format the data you need +4. **Action:** Send to your destination system (Slack, email, CRM, etc.) + +**Advanced Features:** +- **Data Storage:** Store events temporarily for batch processing +- **AI Analysis:** Use OpenAI/Claude for intelligent insights +- **Conditional Logic:** Route different events to different actions +- **Error Handling:** Retry failed operations, log issues + +### Step 4: Test and Refine + +1. **Start Simple:** Begin with basic notifications, add complexity gradually +2. **Monitor Volume:** Adjust filters to prevent notification overload +3. **Gather Feedback:** Ask your team what information is most valuable +4. **Iterate:** Refine logic based on real-world usage patterns + +--- + +## Best Practices + +### 🎯 **Start Focused** +- Choose one specific use case to begin with +- Get that working perfectly before adding complexity +- Gradually expand to additional scenarios + +### πŸ“Š **Filter Intelligently** +- Not every webhook event needs an action +- Use user segments, tour types, or completion rates as filters +- Batch similar events together to reduce noise + +### πŸ€– **Leverage AI for Insights** +- Use AI to summarize batches of events instead of individual alerts +- Generate actionable recommendations, not just data dumps +- Analyze sentiment and priority levels automatically + +### πŸ”„ **Plan for Scale** +- Consider data storage limits and cleanup strategies +- Build in error handling for API rate limits +- Design workflows that won't break as your user base grows + +### πŸ“ˆ **Measure Success** +- Track automation performance (alerts acted on vs ignored) +- Monitor time saved vs manual processes +- Gather feedback from users receiving notifications + +--- + +## Common Webhook Data Fields + +Understanding the data available in each webhook helps you build more effective automations: + +### User Profile Data +```json +{ + "profile": { + "email": "user@company.com", + "role": "product_manager", + "plan": "professional", + "team_size": 25, + "department": "Product", + "last_seen_session_count": 47, + "feature_flags": ["advanced_analytics"] + } +} +``` + +**Use for:** User segmentation, personalized notifications, CRM enrichment + +### Experience Data +```json +{ + "tour": { + "name": "Dashboard Onboarding Tour", + "published_at": "2029-07-15T09:00:00Z", + "stats": { + "started_count": 1247, + "completed_count": 892, + "exited_count": 355 + } + } +} +``` + +**Use for:** Performance monitoring, completion rate analysis, content optimization + +### Interaction Data +```json +{ + "button": { + "text": "Get Started", + "action_url": "https://app.example.com/setup", + "position": "bottom_right" + } +} +``` + +**Use for:** Feature adoption tracking, conversion analysis, A/B testing insights + +--- + +## Troubleshooting Common Issues + +### **Webhook Not Firing** +- Verify webhook URL is correct in Chameleon settings +- Check that webhook topics are properly selected +- Confirm your automation platform is receiving requests + +### **Too Many Notifications** +- Add more specific filters to reduce noise +- Switch from individual alerts to digest/batch processing +- Use user segment filters to focus on relevant users + +### **Missing Data in Payload** +- Check which webhook topic provides the data you need +- Some fields may be null for certain user types or scenarios +- Use conditional logic to handle missing fields gracefully + +### **Automation Timing Out** +- Simplify complex logic or break into multiple steps +- Add error handling for external API calls +- Consider using data storage for multi-step workflows + +--- + +## Next Steps + +1. **Choose Your First Use Case:** Pick one scenario from the examples above +2. **Select Your Platform:** Sign up for Zapier, Make.com, or your preferred tool +3. **Set Up Webhook:** Configure the connection in Chameleon +4. **Build Basic Version:** Start with simple notifications, add features gradually +5. **Test Thoroughly:** Verify the workflow with real data before going live +6. **Scale Gradually:** Add more sophisticated logic and additional use cases over time + +Remember: The goal is to make your team more effective, not to create more work. Start simple, measure impact, and iterate based on what actually helps your team make better decisions. + +--- + +*For technical implementation details and advanced webhook configurations, see our [Webhook Overview Documentation](webhooks/overview.md).* \ No newline at end of file diff --git a/docs/webhooks/overview.md b/docs/webhooks/overview.md index 71b0ba9..b467321 100644 --- a/docs/webhooks/overview.md +++ b/docs/webhooks/overview.md @@ -164,54 +164,101 @@ Every Microsurvey that is finished will send a webhook to this topic. ```json { - "id": "5fb70dcbc39330000325a81a", + "id": "5f3c4232c712de665632d7a1", "kind": "response.finished", - "sent_at": "2029-12-11T00:28:59.651Z", + "sent_at": "2029-05-05T16:22:18.456Z", "data": { "profile": { - "id": "5f885a88e7daf3000e3eb4f6", - "email": "jane@example.com", - "uid": "92340834", - "name": "Jane E", - "last_seen_at": "2029-12-11T00:21:59.109Z", - "last_seen_session_count": 83, - ... + "id": "5f3c4232c712de665632d7a2", + "created_at": "2029-04-12T10:30:00.000Z", + "updated_at": "2029-05-05T16:22:00.000Z", + "uid": "feedback_user_888", + "company_id": "5f3c4232c712de665632d7a3", + "email": "rachel.green@designstudio.co", + "browser_l": "fr-FR", + "browser_n": "firefox", + "browser_k": "desktop", + "browser_x": 1680, + "browser_tz": 1, + "percent": 67.89, + "last_seen_at": "2029-05-05T16:22:00.000Z", + "last_seen_session_count": 24, + "delivery_ids": [ + "5f3c4232c712de665632d7a4" + ], + "role": "ux_designer", + "plan": "professional", + "onboarding_completed": true, + "feature_flags": ["design_tools", "collaboration_features"], + "signup_source": "dribbble_ad", + "team_size": 7, + "subscription_status": "active", + "department": "Design" }, "response": { - "id": "5fb7afb5ea19724169374269", - "survey_id": "5fb7936edee1f70011bfc4c9", - "profile_id": "5f884e1e03d9f4000ebcbb59", - "href": "https://app.acme.co/setup/tough-thing-to-do", - "button_text": "Very Easy", + "id": "5f3c4232c712de665632d7a5", + "created_at": "2029-05-05T16:22:18.000Z", + "updated_at": "2029-05-05T16:22:18.234Z", + "survey_id": "5f3c4232c712de665632d7a6", + "profile_id": "5f3c4232c712de665632d7a2", + "href": "https://app.example.com/dashboard/projects", + "button_text": "Submit Feedback", "button_order": 0, - "input_text": "I was able to figure it out quickly.", - "finished_at": "2029-12-11T00:28:59.641Z" + "button_id": "5f3c4232c712de665632d7a7", + "input_text": "The new design collaboration features are excellent! The real-time commenting system makes it so much easier to work with developers. Would love to see version history for design assets.", + "finished_at": "2029-05-05T16:22:18.000Z", + "rating": 5, + "nps_score": 9 }, "survey": { - "id": "5fb7936edee1f70011bfc4c9", - "name": "2029-11 Role question", - "segment_id": "5f885a88e7daf3000e3eb4f7", - "published_at": "2029-11-11T00:12:59.002Z", - ... + "id": "5f3c4232c712de665632d7a6", + "created_at": "2029-04-28T14:00:00.000Z", + "updated_at": "2029-05-03T11:20:00.000Z", + "name": "New Feature Feedback - Design Collaboration", + "position": 8, + "segment_ids": [ + "5f3c4232c712de665632d7a8", + "5f3c4232c712de665632d7a9" + ], + "published_at": "2029-05-01T08:00:00.000Z", + "rate_unlimit_at": null, + "last_dropdown_items": [ + "Excellent", + "Very Good", + "Good", + "Fair", + "Poor" + ], + "kind": "survey", + "stats": { + "started_count": 134, + "completed_count": 98, + "response_rate": 0.731 + }, "steps": [ { - "id": "5fb7936d566535d75a87507c", - "body": "How was that?", + "id": "5f3c4232c712de665632d7b1", + "body": "How would you rate the new design collaboration features?", "preset": "survey_five", "dropdown_items": [ + "Excellent", + "Very Good", + "Good", + "Fair", + "Poor" ] }, { - "id": "5fb7936d566535d75a87507e", - "body": "Thanks so much for your feedback! πŸ™", + "id": "5f3c4232c712de665632d7b2", + "body": "Any additional feedback or suggestions?", + "preset": "response" + }, + { + "id": "5f3c4232c712de665632d7b3", + "body": "Thank you for your feedback! 🎨", "preset": "thank_you" } - ], - "user": { - "id": "5490e42d65353700020030fa", - "email": "jim@acme.co", - "name": "Jim B" - } + ] } } } @@ -227,29 +274,56 @@ This is the most important HelpBar webhook; it can directly inform your roadmap - Seeing a `results_count` less than 3 is an important metric to track - Use `references` to know where to make improvements - ```json { - "id": "5eb7c393300000dcb381a25a", + "id": "5f3c4232c712de665632c4d1", "kind": "helpbar.answer", - "sent_at": "2029-12-11T00:28:59.651Z", + "sent_at": "2029-04-28T13:45:22.567Z", "data": { "action": { - "id": "5f885a88e7daf3000e3eb4f6", - "query": "What is a widget?", - "answer": "A widget is the generic name for the work product of a production run. One might use this term to describe something generic as an example in place of an unimportant specific item.", + "id": "5f3c4232c712de665632c4d2", + "query": "How do I integrate with Slack?", + "answer": "To integrate Chameleon with Slack, you can set up webhook notifications to send tour completions, survey responses, and other events directly to your Slack channels. First, create a Slack webhook URL in your Slack workspace settings, then configure it in your Chameleon dashboard under Integrations. You can customize which events trigger notifications and format the messages to include relevant user and experience data. This helps keep your team informed about user engagement in real-time.", + "url": "https://app.example.com/helpbar", "results_count": 7, - "references": ["https://help.your-product.com/hc/articles/925844-widgets-galore", "https://help.your-product.com/hc/articles/559284-widgets-n-more"], - "url": "https://app.your-product.com/widgets/start" + "references": [ + { + "title": "Slack Integration Guide", + "url": "https://help.example.com/integrations/slack" + }, + { + "title": "Webhook Configuration", + "url": "https://help.example.com/webhooks/setup" + } + ] }, "profile": { - "id": "5f885a88e7daf3000e3eb4f6", - "email": "jane@example.com", - "uid": "92340834", - "name": "Jane E", - "last_seen_at": "2029-12-11T00:21:59.109Z", - "last_seen_session_count": 83, - ... + "id": "5f3c4232c712de665632c4d3", + "created_at": "2029-03-20T12:30:00.000Z", + "updated_at": "2029-04-28T13:44:00.000Z", + "uid": "integration_user_999", + "company_id": "5f3c4232c712de665632c4d4", + "email": "david.kim@saas-company.com", + "browser_l": "ko-KR", + "browser_n": "chrome", + "browser_k": "desktop", + "browser_x": 1600, + "browser_tz": 9, + "percent": 44.67, + "last_seen_at": "2029-04-28T13:44:00.000Z", + "last_seen_session_count": 18, + "delivery_ids": [ + "5f3c4232c712de665632c4d5", + "5f3c4232c712de665632c4d6" + ], + "role": "integration_specialist", + "plan": "enterprise", + "onboarding_completed": true, + "feature_flags": ["advanced_integrations", "custom_webhooks"], + "signup_source": "partner_referral", + "team_size": 50, + "subscription_status": "active", + "department": "Engineering" } } } @@ -258,55 +332,46 @@ This is the most important HelpBar webhook; it can directly inform your roadmap ##### Example: `helpbar.search` :id=example-helpbar-search -When a User searches for `"data importing"` only 0 results were found. This indicates a gap in your Help center. +When a User searches for `"tell me about webhooks"` and 10 results were found. ```json { - "id": "5eb7c393300000dcb381a25a", + "id": "5f3c4232c712de665632c5e1", "kind": "helpbar.search", - "sent_at": "2029-12-11T00:29:59.651Z", + "sent_at": "2029-04-30T09:20:15.432Z", "data": { "action": { - "id": "5f885a88e7daf3000e3eb4f7", - "query": "data importing", - "results_count": 2, - "url": "https://app.your-product.com/widgets/import" + "id": "5f3c4232c712de665632c5e2", + "query": "export user data", + "results_count": 5 }, "profile": { - "id": "5f885a88f30e7da00e3eb4f6", - "email": "jane@example.com", - "uid": "92340834", - "name": "Jane E", - "last_seen_at": "2029-12-11T00:21:59.109Z", - "last_seen_session_count": 85, - ... - } - } -} -``` - -When a User searches for `"widget categories"` only 7 results were found. - -```json -{ - "id": "5eb7c393300000dcb381a25a", - "kind": "helpbar.search", - "sent_at": "2029-12-11T00:28:30.651Z", - "data": { - "action": { - "id": "5f885a8af30008e7de3eb4f9", - "query": "widget categories", - "results_count": 7, - "url": "https://app.your-product.com/widgets/import" - }, - "profile": { - "id": "5f885a88e7daf3000e3eb4f6", - "email": "jane@example.com", - "uid": "92340834", - "name": "Jane E", - "last_seen_at": "2029-12-11T00:21:59.109Z", - "last_seen_session_count": 93, - ... + "id": "5f3c4232c712de665632c5e3", + "created_at": "2029-04-25T14:15:00.000Z", + "updated_at": "2029-04-30T09:19:00.000Z", + "uid": "admin_user_111", + "company_id": "5f3c4232c712de665632c5e4", + "email": "emma.taylor@compliance-corp.org", + "browser_l": "en-AU", + "browser_n": "safari", + "browser_k": "desktop", + "browser_x": 1440, + "browser_tz": 10, + "percent": 78.12, + "last_seen_at": "2029-04-30T09:19:00.000Z", + "last_seen_session_count": 6, + "delivery_ids": [ + "5f3c4232c712de665632c5e5" + ], + "role": "compliance_officer", + "plan": "enterprise", + "onboarding_completed": true, + "feature_flags": ["data_export", "compliance_tools", "audit_logging"], + "signup_source": "enterprise_sales", + "team_size": 8, + "subscription_status": "active", + "department": "Legal", + "permissions": ["admin", "data_export", "user_management"] } } } @@ -319,24 +384,48 @@ When a helpbar search result item is clicked (or actioned) ```json { - "id": "5eb7c393300000dcb381a25a", + "id": "5f3c4232c712de665632c6f1", "kind": "helpbar.item.action", - "sent_at": "2029-12-11T00:28:18.651Z", + "sent_at": "2029-05-02T14:35:42.891Z", "data": { "action": { - "id": "5f885a8af30008e7de3eb4f9", - "item_uid": "data-onboarding", - "href": "https://help.your-product.com/hc/articles/559284-data-onboarding", - "kinds": ["url"] + "id": "5f3c4232c712de665632c6f2", + "query": "setup analytics tracking", + "item_uid": "analytics-setup-guide-v2", + "title": "Analytics Integration Setup Guide", + "href": "https://help.example.com/analytics/setup-guide", + "kinds": ["url", "tutorial"] }, "profile": { - "id": "5f885a88e7daf3000e3eb4f6", - "email": "jane@example.com", - "uid": "92340834", - "name": "Jane E", - "last_seen_at": "2029-12-11T00:21:59.109Z", - "last_seen_session_count": 93, - ... + "id": "5f3c4232c712de665632c6f3", + "created_at": "2029-04-18T11:00:00.000Z", + "updated_at": "2029-05-02T14:34:00.000Z", + "uid": "analytics_user_777", + "company_id": "5f3c4232c712de665632c6f4", + "email": "priya.patel@datadriven.startup", + "browser_l": "hi-IN", + "browser_n": "chrome", + "browser_k": "desktop", + "browser_x": 1920, + "browser_tz": 5.5, + "percent": 33.44, + "last_seen_at": "2029-05-02T14:34:00.000Z", + "last_seen_session_count": 12, + "delivery_ids": [ + "5f3c4232c712de665632c6f5", + "5f3c4232c712de665632c6f6", + "5f3c4232c712de665632c6f7" + ], + "role": "data_analyst", + "plan": "growth", + "onboarding_completed": true, + "feature_flags": ["advanced_analytics", "custom_events", "cohort_analysis"], + "signup_source": "content_marketing", + "team_size": 15, + "subscription_status": "active", + "department": "Product", + "time_zone": "Asia/Kolkata", + "preferred_language": "en" } } } @@ -378,35 +467,209 @@ In the example below, the `script` item is not working properly and should be ch A Tour is started, runs through a sequence of 1 or more Steps and finishes by being Exited or Completed. Tours by default show once to any one User but can, depending on their settings, show multiple times. +**Example: `tour.started`** ```json { - "id": "5fb70dcbc39330000325a818", + "id": "5f3c4232c712de665632a6d5", "kind": "tour.started", - "sent_at": "2029-12-11T00:28:59.652Z", + "sent_at": "2029-04-15T14:30:22.150Z", "data": { + "action": { + "id": "5f3c4232c712de665632a6d6" + }, "profile": { - "id": "5f885a88e7daf3000e3eb4f6", - "email": "jane@example.com", - "uid": "92340834", - "name": "Jane E", - "last_seen_at": "2029-12-11T00:21:59.109Z", - "last_seen_session_count": 83, - ... + "id": "5f3c4232c712de665632a6d7", + "created_at": "2029-03-10T09:15:00.000Z", + "updated_at": "2029-04-15T14:25:00.000Z", + "uid": "user_12345", + "company_id": "5f3c4232c712de665632a6d8", + "email": "sarah.johnson@techstartup.io", + "browser_l": "en-US", + "browser_n": "chrome", + "browser_k": "desktop", + "browser_x": 1920, + "browser_tz": -8, + "percent": 72.45, + "last_seen_at": "2029-04-15T14:25:00.000Z", + "last_seen_session_count": 15, + "delivery_ids": [ + "5f3c4232c712de665632a6e1", + "5f3c4232c712de665632a6e2" + ], + "role": "product_manager", + "plan": "professional", + "onboarding_completed": false, + "feature_flags": ["new_dashboard", "analytics_beta"], + "signup_source": "organic_search" }, "tour": { - "id": "5fb6e4ab8af58a00073f0d98", - "name": "Usage upsell banner - A", - "segment_id": "5f885a88e7daf3000e3eb4f7", - "published_at": "2029-11-11T00:12:59.002Z", - ... + "id": "5f3c4232c712de665632a6d9", + "created_at": "2029-02-20T10:00:00.000Z", + "updated_at": "2029-04-10T16:30:00.000Z", + "name": "Dashboard Onboarding Tour", + "position": 1, + "segment_ids": [ + "5f3c4232c712de665632a6da" + ], + "published_at": "2029-04-01T08:00:00.000Z", + "rate_unlimit_at": null, + "kind": "tour", + "style": "auto", + "urls": { + "dashboard": "https://app.chameleon.io/tours/5f3c4232c712de665632a6d9" + }, + "stats": { + "started_count": 1247, + "completed_count": 892, + "exited_count": 355 + } }, "step": { - "id": "5fb6e4ab8af58a00073f0d99", - "body": "You've grown beyond your current plan by {{mau_blocks fallback='a lot'}}! πŸŽ‰ -- Next billing cycle, you will be charged for the additional users or pre-pay to save", - ... + "id": "5f3c4232c712de665632a6db", + "created_at": "2029-02-20T10:00:00.000Z", + "updated_at": "2029-04-10T16:30:00.000Z", + "body": "Welcome to your new dashboard! Let's take a quick tour to help you get started with the key features.", + "preset": "tooltip_bottom" + } + } +} +``` + +**Example: `tour.exited`** +```json +{ + "id": "5f3c4232c712de665632a2a1", + "kind": "tour.exited", + "sent_at": "2029-04-18T16:45:12.890Z", + "data": { + "action": { + "id": "5f3c4232c712de665632a2a2" + }, + "profile": { + "id": "5f3c4232c712de665632a2a3", + "created_at": "2029-01-15T11:30:00.000Z", + "updated_at": "2029-04-18T16:44:00.000Z", + "uid": "dev_user_789", + "company_id": "5f3c4232c712de665632a2a4", + "email": "mike.chen@enterprise-corp.com", + "browser_l": "en-CA", + "browser_n": "firefox", + "browser_k": "desktop", + "browser_x": 1440, + "browser_tz": -5, + "percent": 28.91, + "last_seen_at": "2029-04-18T16:44:00.000Z", + "last_seen_session_count": 45, + "delivery_ids": [ + "5f3c4232c712de665632a2a5" + ], + "role": "developer", + "plan": "enterprise", + "onboarding_completed": true, + "feature_flags": ["advanced_analytics", "api_access"], + "signup_source": "referral", + "team_size": 12 + }, + "tour": { + "id": "5f3c4232c712de665632a2a6", + "created_at": "2029-03-01T14:00:00.000Z", + "updated_at": "2029-04-15T09:20:00.000Z", + "name": "New Feature Announcement - API v2", + "position": 3, + "segment_ids": [ + "5f3c4232c712de665632a2a7", + "5f3c4232c712de665632a2a8" + ], + "published_at": "2029-04-01T12:00:00.000Z", + "rate_unlimit_at": "2029-05-01T00:00:00.000Z", + "kind": "tour", + "style": "manual", + "tour_link_url": "https://app.example.com/tours/api-v2-announcement", + "urls": { + "dashboard": "https://app.chameleon.io/tours/5f3c4232c712de665632a2a6" + }, + "stats": { + "started_count": 324, + "completed_count": 198, + "exited_count": 126 + } }, + "step": { + "id": "5f3c4232c712de665632a2a9", + "created_at": "2029-03-01T14:00:00.000Z", + "updated_at": "2029-04-15T09:20:00.000Z", + "body": "πŸŽ‰ Introducing API v2 with enhanced performance and new endpoints. Click here to explore the updated documentation.", + "preset": "banner_top" + } + } +} +``` + +**Example: `tour.completed`** +```json +{ + "id": "5f3c4232c712de665632a3b1", + "kind": "tour.completed", + "sent_at": "2029-05-12T14:25:45.123Z", + "data": { "action": { - "id": "5f885a88e7daf3000e3eb4f6" + "id": "5f3c4232c712de665632a3b2" + }, + "profile": { + "id": "5f3c4232c712de665632a3b3", + "created_at": "2029-05-10T11:15:00.000Z", + "updated_at": "2029-05-12T14:25:00.000Z", + "uid": "design_user_202", + "company_id": "5f3c4232c712de665632a3b4", + "email": "lisa.wang@creativestudio.design", + "browser_l": "en-US", + "browser_n": "chrome", + "browser_k": "desktop", + "browser_x": 1920, + "browser_tz": -8, + "percent": 56.78, + "last_seen_at": "2029-05-12T14:25:00.000Z", + "last_seen_session_count": 7, + "delivery_ids": [ + "5f3c4232c712de665632a3b5", + "5f3c4232c712de665632a3b6" + ], + "role": "senior_designer", + "plan": "professional", + "onboarding_completed": false, + "feature_flags": ["theme_templates", "custom_styling", "design_library"], + "signup_source": "behance_integration", + "team_size": 6, + "subscription_status": "active", + "department": "Creative", + "trial_converted": true + }, + "tour": { + "id": "5f3c4232c712de665632a3b7", + "created_at": "2029-03-20T09:00:00.000Z", + "updated_at": "2029-05-10T16:30:00.000Z", + "name": "Theme Templates & Custom Styling Guide", + "position": 4, + "segment_ids": [], + "published_at": "2029-04-15T12:00:00.000Z", + "rate_unlimit_at": null, + "kind": "tour", + "style": "auto", + "urls": { + "dashboard": "https://app.chameleon.io/tours/5f3c4232c712de665632a3b7" + }, + "stats": { + "started_count": 89, + "completed_count": 71, + "exited_count": 18 + } + }, + "step": { + "id": "5f3c4232c712de665632a3b8", + "created_at": "2029-03-20T09:00:00.000Z", + "updated_at": "2029-05-10T16:30:00.000Z", + "body": "🎨 You can also create your own Templates that follow the style of specific Themes!\n\n1. Create a new Experience as usual\n2. Pick the Theme you want to add a new Template to\n3. Adjust it in the Builder\n4. Use the **'Templatize'** option to save your new Template.", + "preset": "tooltip_right" } } } @@ -461,42 +724,274 @@ When a Tour is snoozed it is set to come back after a certain amount of time has Every Button that is clicked in a Tour / Microsurvey will send a webhook to this topic. It includes the Step and the Button configuration. +**Example: `tour.button.clicked`** ```json { - "id": "5fb70dcbc39330000325a819", + "id": "5f3c4232c712de665632f9c1", "kind": "tour.button.clicked", - "sent_at": "2029-12-11T00:28:59.653Z", + "sent_at": "2029-05-15T11:40:18.456Z", "data": { + "action": { + "id": "5f3c4232c712de665632f9c2" + }, "profile": { - "id": "5f885a88e7daf3000e3eb4f6", - "email": "jane@example.com", - "uid": "92340834", - "name": "Jane E", - "last_seen_at": "2029-12-11T00:21:59.109Z", - "last_seen_session_count": 83, - ... + "id": "5f3c4232c712de665632f9c3", + "created_at": "2029-04-28T15:20:00.000Z", + "updated_at": "2029-05-15T11:39:00.000Z", + "uid": "content_user_444", + "company_id": "5f3c4232c712de665632f9c4", + "email": "maria.gonzalez@contentcorp.es", + "browser_l": "es-MX", + "browser_n": "safari", + "browser_k": "desktop", + "browser_x": 1440, + "browser_tz": -6, + "percent": 73.21, + "last_seen_at": "2029-05-15T11:39:00.000Z", + "last_seen_session_count": 16, + "delivery_ids": [ + "5f3c4232c712de665632f9c5" + ], + "role": "content_manager", + "plan": "growth", + "onboarding_completed": true, + "feature_flags": ["content_templates", "multilingual_support"], + "signup_source": "linkedin_ad", + "team_size": 12, + "subscription_status": "active", + "department": "Marketing", + "preferred_language": "es" }, - "tour": { // or "survey" or "embed" - "id": "5fb6e4ab8af58a00073f0d98", - "name": "Usage upsell banner - A", - "segment_id": "5f885a88e7daf3000e3eb4f7", - "published_at": "2029-11-11T00:12:59.002Z", - ... + "tour": { + "id": "5f3c4232c712de665632f9c6", + "created_at": "2029-04-22T14:00:00.000Z", + "updated_at": "2029-05-12T10:30:00.000Z", + "name": "Content Templates & Styling Guide", + "position": 7, + "segment_ids": [], + "published_at": "2029-05-05T09:00:00.000Z", + "rate_unlimit_at": null, + "kind": "tour", + "style": "auto", + "urls": { + "dashboard": "https://app.chameleon.io/tours/5f3c4232c712de665632f9c6" + }, + "stats": { + "started_count": 142, + "completed_count": 108, + "exited_count": 34 + } }, "step": { - "id": "5fb6e4ab8af58a00073f0d99", - "body": "You've grown beyond your current plan by {{mau_blocks fallback='a lot'}}! πŸŽ‰ -- Next billing cycle, you will be charged for the additional users or pre-pay to save", - ... + "id": "5f3c4232c712de665632f9c7", + "created_at": "2029-04-22T14:00:00.000Z", + "updated_at": "2029-05-12T10:30:00.000Z", + "body": "Explore the Templates Gallery and pick a specific Theme when saving new Templates on your account to leverage your style.", + "preset": "tooltip_bottom" }, "button": { - "id": "5fb6e4ab8af58a00073f0d9a", - "text": "Check pricing", - "tour_action": "next", - "position": "bottom_right", - ... + "id": "5f3c4232c712de665632f9c8", + "text": "Next", + "style_color_fill": "2563EB", + "style_color_text": "FFFFFF", + "style_color_border": "2563EB", + "style_button_roundness": "6px", + "style_border_width": "1px", + "action_new_window": false, + "position": "bottom_right", + "tour_action": "next", + "order": 1 + } + } +} +``` + +**Example: `survey.button.clicked`** +```json +{ + "id": "5f3c4232c712de665632e8b1", + "kind": "survey.button.clicked", + "sent_at": "2029-05-08T12:15:30.789Z", + "data": { + "action": { + "id": "5f3c4232c712de665632e8b2" }, + "profile": { + "id": "5f3c4232c712de665632e8b3", + "created_at": "2029-05-01T09:45:00.000Z", + "updated_at": "2029-05-08T12:14:00.000Z", + "uid": "power_user_555", + "company_id": "5f3c4232c712de665632e8b4", + "email": "tom.harrison@productteam.io", + "browser_l": "en-US", + "browser_n": "chrome", + "browser_k": "desktop", + "browser_x": 2560, + "browser_tz": -8, + "percent": 89.34, + "last_seen_at": "2029-05-08T12:14:00.000Z", + "last_seen_session_count": 41, + "delivery_ids": [ + "5f3c4232c712de665632e8b5", + "5f3c4232c712de665632e8b6" + ], + "role": "product_owner", + "plan": "enterprise", + "onboarding_completed": true, + "feature_flags": ["beta_features", "power_user_tools", "advanced_permissions"], + "signup_source": "word_of_mouth", + "team_size": 35, + "subscription_status": "active", + "department": "Product", + "seniority": "senior" + }, + "survey": { + "id": "5f3c4232c712de665632e8b7", + "created_at": "2029-05-05T13:00:00.000Z", + "updated_at": "2029-05-07T16:45:00.000Z", + "name": "Beta Feature Feedback - Advanced Workflows", + "position": 15, + "segment_ids": [ + "5f3c4232c712de665632e8b8" + ], + "published_at": "2029-05-06T10:00:00.000Z", + "rate_unlimit_at": null, + "last_dropdown_items": [ + "Extremely useful", + "Very useful", + "Somewhat useful", + "Not very useful", + "Not useful at all" + ], + "kind": "survey", + "stats": { + "started_count": 67, + "completed_count": 52, + "response_rate": 0.776 + }, + "steps": [ + { + "id": "5f3c4232c712de665632e8b9", + "body": "How useful do you find the new advanced workflow automation features?", + "preset": "survey_rating", + "dropdown_items": [ + "Extremely useful", + "Very useful", + "Somewhat useful", + "Not very useful", + "Not useful at all" + ] + }, + { + "id": "5f3c4232c712de665632e8bb", + "body": "Thank you for helping us improve! πŸš€", + "preset": "thank_you" + } + ] + }, + "step": { + "id": "5f3c4232c712de665632e8b9", + "created_at": "2029-05-05T13:00:00.000Z", + "updated_at": "2029-05-07T16:45:00.000Z", + "body": "How useful do you find the new advanced workflow automation features?", + "preset": "survey_rating" + }, + "button": { + "id": "5f3c4232c712de665632e8ba", + "text": "Extremely useful", + "style_color_fill": "4F46E5", + "style_color_text": "FFFFFF", + "style_color_border": "4F46E5", + "style_button_roundness": "8px", + "action_new_window": false, + "position": "center", + "tour_action": "next", + "order": 0, + "value": 5 + } + } +} +``` + +**Example: `embed.button.clicked`** +```json +{ + "id": "5f3c4232c712de665632e5e1", + "kind": "embed.button.clicked", + "sent_at": "2029-06-15T16:32:18.890Z", + "data": { "action": { - "id": "5f885a88e7daf3000e3eb4f6" + "id": "5f3c4232c712de665632e5e2" + }, + "profile": { + "id": "5f3c4232c712de665632e1a3", + "created_at": "2029-05-20T14:15:00.000Z", + "updated_at": "2029-06-15T16:32:00.000Z", + "uid": "embed_user_789", + "company_id": "5f3c4232c712de665632e1a4", + "email": "jennifer.clark@creativecorp.io", + "browser_l": "en-US", + "browser_n": "chrome", + "browser_k": "desktop", + "browser_x": 1920, + "browser_tz": -8, + "percent": 85.42, + "last_seen_at": "2029-06-15T16:32:00.000Z", + "last_seen_session_count": 47, + "delivery_ids": [ + "5f3c4232c712de665632e1a5", + "5f3c4232c712de665632e1a6" + ], + "role": "creative_director", + "plan": "professional", + "onboarding_completed": true, + "feature_flags": ["embed_builder", "advanced_analytics", "custom_branding"], + "signup_source": "product_hunt", + "team_size": 12, + "subscription_status": "active", + "department": "Creative" + }, + "embed": { + "id": "5f3c4232c712de665632e1a7", + "created_at": "2029-06-10T10:00:00.000Z", + "updated_at": "2029-06-14T15:20:00.000Z", + "name": "Interactive Demo Showcase", + "position": 8, + "segment_ids": [ + "5f3c4232c712de665632e1a8" + ], + "published_at": "2029-06-12T09:00:00.000Z", + "rate_unlimit_at": null, + "kind": "embed", + "urls": { + "dashboard": "https://app.chameleon.io/embeddables/5f3c4232c712de665632e1a7" + }, + "stats": { + "started_count": 234, + "completed_count": 187, + "exited_count": 47 + } + }, + "step": { + "id": "5f3c4232c712de665632e1a9", + "created_at": "2029-06-10T10:00:00.000Z", + "updated_at": "2029-06-14T15:20:00.000Z", + "body": "Discover how to create interactive demos that showcase your product's key features and engage potential customers.", + "preset": "embed_tooltip" + }, + "button": { + "id": "5f3c4232c712de665632e5e3", + "text": "Try Demo", + "style_color_fill": "0084FF", + "style_color_text": "FFFFFF", + "style_color_border": "0084FF", + "style_button_roundness": "6px", + "style_border_width": "1px", + "action_new_window": false, + "position": "bottom_right", + "tour_action": "open_url", + "action_url": "https://app.chameleon.io/demos/interactive-showcase", + "order": 1 } } } @@ -507,35 +1002,208 @@ Every Button that is clicked in a Tour / Microsurvey will send a webhook to this An Embed is started, runs through a sequence of 1 or more Steps and finishes by being Exited or Completed. Embeds by default show once to any one User but can, depending on their settings, show multiple times. +**Example: `embed.started`** ```json { - "id": "5fb70dcbc39330000325a818", + "id": "5f3c4232c712de665632e1a1", "kind": "embed.started", - "sent_at": "2029-12-11T00:28:59.652Z", + "sent_at": "2029-06-15T16:30:45.234Z", "data": { + "action": { + "id": "5f3c4232c712de665632e1a2" + }, "profile": { - "id": "5f885a88e7daf3000e3eb4f6", - "email": "jane@example.com", - "uid": "92340834", - "name": "Jane E", - "last_seen_at": "2029-12-11T00:21:59.109Z", - "last_seen_session_count": 83, - ... + "id": "5f3c4232c712de665632e1a3", + "created_at": "2029-05-20T14:15:00.000Z", + "updated_at": "2029-06-15T16:30:00.000Z", + "uid": "embed_user_789", + "company_id": "5f3c4232c712de665632e1a4", + "email": "jennifer.clark@creativecorp.io", + "browser_l": "en-US", + "browser_n": "chrome", + "browser_k": "desktop", + "browser_x": 1920, + "browser_tz": -8, + "percent": 85.42, + "last_seen_at": "2029-06-15T16:30:00.000Z", + "last_seen_session_count": 47, + "delivery_ids": [ + "5f3c4232c712de665632e1a5", + "5f3c4232c712de665632e1a6" + ], + "role": "creative_director", + "plan": "professional", + "onboarding_completed": true, + "feature_flags": ["embed_builder", "advanced_analytics", "custom_branding"], + "signup_source": "product_hunt", + "team_size": 12, + "subscription_status": "active", + "department": "Creative" }, "embed": { - "id": "5fb6e4ab8af58a00073f0d98", - "name": "Usage upsell banner - A", - "segment_id": "5f885a88e7daf3000e3eb4f7", - "published_at": "2029-11-11T00:12:59.002Z", - ... + "id": "5f3c4232c712de665632e1a7", + "created_at": "2029-06-10T10:00:00.000Z", + "updated_at": "2029-06-14T15:20:00.000Z", + "name": "Interactive Demo Showcase", + "position": 8, + "segment_ids": [ + "5f3c4232c712de665632e1a8" + ], + "published_at": "2029-06-12T09:00:00.000Z", + "rate_unlimit_at": null, + "kind": "embed", + "urls": { + "dashboard": "https://app.chameleon.io/embeddables/5f3c4232c712de665632e1a7" + }, + "stats": { + "started_count": 234, + "completed_count": 187, + "exited_count": 47 + } }, "step": { - "id": "5fb6e4ab8af58a00073f0d99", - "body": "You've grown beyond your current plan by {{mau_blocks fallback='a lot'}}! πŸŽ‰ -- Next billing cycle, you will be charged for the additional users or pre-pay to save", - ... + "id": "5f3c4232c712de665632e1a9", + "created_at": "2029-06-10T10:00:00.000Z", + "updated_at": "2029-06-14T15:20:00.000Z", + "body": "Discover how to create interactive demos that showcase your product's key features and engage potential customers.", + "preset": "embed_tooltip" + } + } +} +``` + +**Example: `embed.completed`** +```json +{ + "id": "5f3c4232c712de665632e2b1", + "kind": "embed.completed", + "sent_at": "2029-06-15T16:35:22.567Z", + "data": { + "action": { + "id": "5f3c4232c712de665632e2b2" }, + "profile": { + "id": "5f3c4232c712de665632e1a3", + "created_at": "2029-05-20T14:15:00.000Z", + "updated_at": "2029-06-15T16:35:00.000Z", + "uid": "embed_user_789", + "company_id": "5f3c4232c712de665632e1a4", + "email": "jennifer.clark@creativecorp.io", + "browser_l": "en-US", + "browser_n": "chrome", + "browser_k": "desktop", + "browser_x": 1920, + "browser_tz": -8, + "percent": 85.42, + "last_seen_at": "2029-06-15T16:35:00.000Z", + "last_seen_session_count": 47, + "delivery_ids": [ + "5f3c4232c712de665632e1a5", + "5f3c4232c712de665632e1a6" + ], + "role": "creative_director", + "plan": "professional", + "onboarding_completed": true, + "feature_flags": ["embed_builder", "advanced_analytics", "custom_branding"], + "signup_source": "product_hunt", + "team_size": 12, + "subscription_status": "active", + "department": "Creative" + }, + "embed": { + "id": "5f3c4232c712de665632e1a7", + "created_at": "2029-06-10T10:00:00.000Z", + "updated_at": "2029-06-14T15:20:00.000Z", + "name": "Interactive Demo Showcase", + "position": 8, + "segment_ids": [ + "5f3c4232c712de665632e1a8" + ], + "published_at": "2029-06-12T09:00:00.000Z", + "rate_unlimit_at": null, + "kind": "embed", + "urls": { + "dashboard": "https://app.chameleon.io/embeddables/5f3c4232c712de665632e1a7" + }, + "stats": { + "started_count": 234, + "completed_count": 188, + "exited_count": 46 + } + }, + "step": { + "id": "5f3c4232c712de665632e2b3", + "created_at": "2029-06-10T10:00:00.000Z", + "updated_at": "2029-06-14T15:20:00.000Z", + "body": "πŸŽ‰ Excellent! You've completed the interactive demo showcase. You now understand how to create engaging product demonstrations.", + "preset": "embed_success" + } + } +} +``` + +**Example: `embed.exited`** +```json +{ + "id": "5f3c4232c712de665632e3c1", + "kind": "embed.exited", + "sent_at": "2029-06-15T16:28:45.890Z", + "data": { "action": { - "id": "5f885a88e7daf3000e3eb4f6" + "id": "5f3c4232c712de665632e3c2" + }, + "profile": { + "id": "5f3c4232c712de665632e3c3", + "created_at": "2029-06-10T11:20:00.000Z", + "updated_at": "2029-06-15T16:28:00.000Z", + "uid": "trial_user_456", + "company_id": "5f3c4232c712de665632e3c4", + "email": "miguel.santos@startuptech.es", + "browser_l": "es-ES", + "browser_n": "firefox", + "browser_k": "desktop", + "browser_x": 1440, + "browser_tz": 1, + "percent": 23.67, + "last_seen_at": "2029-06-15T16:28:00.000Z", + "last_seen_session_count": 8, + "delivery_ids": [], + "role": "developer", + "plan": "growth", + "onboarding_completed": false, + "feature_flags": ["basic_embeds"], + "signup_source": "google_ads", + "team_size": 5, + "subscription_status": "trial", + "department": "Engineering" + }, + "embed": { + "id": "5f3c4232c712de665632e1a7", + "created_at": "2029-06-10T10:00:00.000Z", + "updated_at": "2029-06-14T15:20:00.000Z", + "name": "Interactive Demo Showcase", + "position": 8, + "segment_ids": [ + "5f3c4232c712de665632e1a8" + ], + "published_at": "2029-06-12T09:00:00.000Z", + "rate_unlimit_at": null, + "kind": "embed", + "urls": { + "dashboard": "https://app.chameleon.io/embeddables/5f3c4232c712de665632e1a7" + }, + "stats": { + "started_count": 234, + "completed_count": 187, + "exited_count": 48 + } + }, + "step": { + "id": "5f3c4232c712de665632e1a9", + "created_at": "2029-06-10T10:00:00.000Z", + "updated_at": "2029-06-14T15:20:00.000Z", + "body": "Discover how to create interactive demos that showcase your product's key features and engage potential customers.", + "preset": "embed_tooltip" } } } @@ -549,38 +1217,74 @@ When an Embed is snoozed it is set to come back after a certain amount of time h ```json { - "id": "5fb70dcbc39330000325a818", + "id": "5f3c4232c712de665632e4d1", "kind": "embed.snoozed", - "sent_at": "2029-12-11T00:28:59.652Z", + "sent_at": "2029-06-15T17:15:45.678Z", "data": { "action": { - "id": "5f885a88e7daf3000e3eb4f6", - "deferred_until": "2029-12-14T00:28:58.622Z", - "deferred_hours": 72, - "deferred_count": 2 + "id": "5f3c4232c712de665632e4d2", + "deferred_until": "2029-06-17T09:15:44.567Z", + "deferred_hours": 40, + "deferred_count": 1 }, "profile": { - "id": "5f885a88e7daf3000e3eb4f6", - "email": "jane@example.com", - "uid": "92340834", - "name": "Jane E", - "last_seen_at": "2029-12-11T00:21:59.109Z", - "last_seen_session_count": 83, - ... + "id": "5f3c4232c712de665632e4d3", + "created_at": "2029-06-12T14:30:00.000Z", + "updated_at": "2029-06-15T17:15:00.000Z", + "uid": "mobile_user_234", + "company_id": "5f3c4232c712de665632e4d4", + "email": "lucia.hernandez@mobilecorp.mx", + "browser_l": "es-MX", + "browser_n": "safari", + "browser_k": "mobile", + "browser_x": 375, + "browser_tz": -6, + "percent": 62.18, + "last_seen_at": "2029-06-15T17:15:00.000Z", + "last_seen_session_count": 19, + "delivery_ids": [ + "5f3c4232c712de665632e4d5" + ], + "role": "product_manager", + "plan": "startup", + "onboarding_completed": true, + "feature_flags": ["mobile_embeds", "snooze_options"], + "signup_source": "referral", + "team_size": 3, + "subscription_status": "active", + "department": "Product", + "preferred_language": "es" }, "embed": { - "id": "5fb6e4ab8af58a00073f0d98", - "name": "Usage upsell banner - A", - "segment_id": "5f885a88e7daf3000e3eb4f7", - "published_at": "2029-11-11T00:12:59.002Z", - ... + "id": "5f3c4232c712de665632e1a7", + "created_at": "2029-06-10T10:00:00.000Z", + "updated_at": "2029-06-14T15:20:00.000Z", + "name": "Interactive Demo Showcase", + "position": 8, + "segment_ids": [ + "5f3c4232c712de665632e1a8" + ], + "published_at": "2029-06-12T09:00:00.000Z", + "rate_unlimit_at": null, + "kind": "embed", + "urls": { + "dashboard": "https://app.chameleon.io/embeddables/5f3c4232c712de665632e1a7" + }, + "stats": { + "started_count": 234, + "completed_count": 187, + "exited_count": 47, + "snoozed_count": 15 + } }, "step": { - "id": "5fb6e4ab8af58a00073f0d99", - "body": "You've grown beyond your current plan by {{mau_blocks fallback='a lot'}}! πŸŽ‰ -- Next billing cycle, you will be charged for the additional users or pre-pay to save", - ... + "id": "5f3c4232c712de665632e1a9", + "created_at": "2029-06-10T10:00:00.000Z", + "updated_at": "2029-06-14T15:20:00.000Z", + "body": "Discover how to create interactive demos that showcase your product's key features and engage potential customers.", + "preset": "embed_tooltip" } - }, + } } ``` @@ -678,7 +1382,6 @@ The primary use case for this is to notify the person in charge of the Experienc ##### Example: `survey.started`, `survey.completed`, `survey.exited` :id=example-survey-all - These three topics are considered lifecycle events and occur when the user is presented with or interacts with a Chameleon Microsurvey. The `response.finished` Webhook is only sent when we consider the user **done** with the Microsurvey and will no longer interact with it. A [Microsurvey Response](apis/survey-responses.md) is generated when the Survey Step + associated @@ -689,52 +1392,277 @@ branches through a sequence of optional _Response_ Steps and finishes with an op > The Steps corresponding to a _Response_ Step have `preset=response`; The _Thank You_ Steps have `preset=thank_you` - +**Example: `survey.started`** ```json { - "id": "5fb70dcbc39330000325a818", - "kind": "survey.completed", - "sent_at": "2029-12-11T00:28:59.652Z", + "id": "5f3c4232c712de665632b1a1", + "kind": "survey.started", + "sent_at": "2029-04-20T10:15:30.245Z", "data": { + "action": { + "id": "5f3c4232c712de665632b1a2" + }, "profile": { - "id": "5f885a88e7daf3000e3eb4f6", - "email": "jane@example.com", - "uid": "92340834", - "name": "Jane E", - "last_seen_at": "2029-12-11T00:21:59.109Z", - "last_seen_session_count": 83, - ... + "id": "5f3c4232c712de665632b1a3", + "created_at": "2029-02-12T08:45:00.000Z", + "updated_at": "2029-04-20T10:10:00.000Z", + "uid": "marketing_user_456", + "company_id": "5f3c4232c712de665632b1a4", + "email": "alex.rivera@startup-inc.com", + "browser_l": "es-ES", + "browser_n": "safari", + "browser_k": "mobile", + "browser_x": 375, + "browser_tz": 2, + "percent": 64.33, + "last_seen_at": "2029-04-20T10:10:00.000Z", + "last_seen_session_count": 8, + "delivery_ids": [ + "5f3c4232c712de665632b1a5", + "5f3c4232c712de665632b1a6", + "5f3c4232c712de665632b1a7" + ], + "role": "marketing_manager", + "plan": "startup", + "onboarding_completed": true, + "feature_flags": ["mobile_optimization", "multilingual_support"], + "signup_source": "product_hunt", + "team_size": 4, + "subscription_status": "trial" }, "survey": { - "id": "5fb7936edee1f70011bfc4c9", - "name": "2029-11 Role question", - "segment_id": "5f885a88e7daf3000e3eb4f7", - "published_at": "2029-11-11T00:12:59.002Z", + "id": "5f3c4232c712de665632b1a8", + "created_at": "2029-03-15T12:00:00.000Z", + "updated_at": "2029-04-18T14:30:00.000Z", + "name": "Product Feedback - Mobile Experience", + "position": 5, + "segment_ids": [ + "5f3c4232c712de665632b1a9" + ], + "published_at": "2029-04-15T09:00:00.000Z", + "rate_unlimit_at": null, + "last_dropdown_items": [ + "Excellent", + "Good", + "Fair", + "Poor" + ], + "kind": "survey", + "stats": { + "started_count": 156, + "completed_count": 98, + "response_rate": 0.628 + }, "steps": [ { - "id": "5fb7936d566535d75a87507c", - "body": "How was that?", - "preset": "survey_five", - ... + "id": "5f3c4232c712de665632b1aa", + "body": "How would you rate your mobile experience?", + "preset": "survey_four", + "dropdown_items": [ + "Excellent", + "Good", + "Fair", + "Poor" + ] }, { - "id": "5fb7936d566535d75a87507d", - "body": "Why specifically did you struggle?", - "preset": "response", - ... + "id": "5f3c4232c712de665632b1ab", + "body": "Thanks for your feedback! πŸ“±", + "preset": "thank_you" } - ... - ], - ... + ] }, "step": { - "id": "5fb7936d566535d75a87507c", - "body": "How was that?", - "preset": "survey_five", - ... + "id": "5f3c4232c712de665632b1aa", + "created_at": "2029-03-15T12:00:00.000Z", + "updated_at": "2029-04-18T14:30:00.000Z", + "body": "How would you rate your overall experience using our mobile app?", + "preset": "survey_five" + } + } +} +``` + +**Example: `survey.completed`** +```json +{ + "id": "5f3c4232c712de665632b2b1", + "kind": "survey.completed", + "sent_at": "2029-04-22T15:25:45.678Z", + "data": { + "action": { + "id": "5f3c4232c712de665632b2b2" + }, + "profile": { + "id": "5f3c4232c712de665632b2b3", + "created_at": "2029-03-05T14:20:00.000Z", + "updated_at": "2029-04-22T15:25:00.000Z", + "uid": "support_user_321", + "company_id": "5f3c4232c712de665632b2b4", + "email": "jessica.wong@techsolutions.co", + "browser_l": "zh-CN", + "browser_n": "edge", + "browser_k": "tablet", + "browser_x": 768, + "browser_tz": 8, + "percent": 91.27, + "last_seen_at": "2029-04-22T15:25:00.000Z", + "last_seen_session_count": 32, + "delivery_ids": [ + "5f3c4232c712de665632b2b5" + ], + "role": "customer_success", + "plan": "business", + "onboarding_completed": true, + "feature_flags": ["asian_localization", "advanced_reporting"], + "signup_source": "sales_demo", + "team_size": 25, + "subscription_status": "active", + "last_login_at": "2029-04-22T08:00:00.000Z" }, + "survey": { + "id": "5f3c4232c712de665632b2b6", + "created_at": "2029-04-01T10:00:00.000Z", + "updated_at": "2029-04-20T16:45:00.000Z", + "name": "Customer Support Satisfaction Survey", + "position": 12, + "segment_ids": [ + "5f3c4232c712de665632b2b7", + "5f3c4232c712de665632b2b8" + ], + "published_at": "2029-04-10T09:00:00.000Z", + "rate_unlimit_at": "2029-05-10T00:00:00.000Z", + "last_dropdown_items": [ + "Very Satisfied", + "Satisfied", + "Neutral", + "Dissatisfied", + "Very Dissatisfied" + ], + "kind": "survey", + "stats": { + "started_count": 89, + "completed_count": 67, + "response_rate": 0.753 + }, + "steps": [ + { + "id": "5f3c4232c712de665632b2b8", + "body": "How satisfied are you with our customer service?", + "preset": "survey_five", + "dropdown_items": [ + "Very Satisfied", + "Satisfied", + "Neutral", + "Dissatisfied", + "Very Dissatisfied" + ] + }, + { + "id": "5f3c4232c712de665632b2b9", + "body": "Thank you for completing our survey! Your feedback helps us improve our service.", + "preset": "thank_you" + } + ] + }, + "step": { + "id": "5f3c4232c712de665632b2b9", + "created_at": "2029-04-01T10:00:00.000Z", + "updated_at": "2029-04-20T16:45:00.000Z", + "body": "Thank you for completing our survey! Your feedback helps us improve our service.", + "preset": "thank_you" + } + } +} +``` + +**Example: `survey.exited`** +```json +{ + "id": "5f3c4232c712de665632b3c1", + "kind": "survey.exited", + "sent_at": "2029-04-25T11:30:18.234Z", + "data": { "action": { - "id": "5f885a88e7daf3000e3eb4f6" + "id": "5f3c4232c712de665632b3c2" + }, + "profile": { + "id": "5f3c4232c712de665632b3c3", + "created_at": "2029-04-10T16:00:00.000Z", + "updated_at": "2029-04-25T11:29:00.000Z", + "uid": "trial_user_654", + "company_id": "5f3c4232c712de665632b3c4", + "email": "carlos.mendez@freelancer.dev", + "browser_l": "pt-BR", + "browser_n": "opera", + "browser_k": "desktop", + "browser_x": 1366, + "browser_tz": -3, + "percent": 15.88, + "last_seen_at": "2029-04-25T11:29:00.000Z", + "last_seen_session_count": 3, + "delivery_ids": [], + "role": "freelancer", + "plan": "free", + "onboarding_completed": false, + "feature_flags": ["basic_features"], + "signup_source": "google_ads", + "team_size": 1, + "subscription_status": "trial", + "trial_ends_at": "2029-05-10T00:00:00.000Z", + "utm_campaign": "latam_expansion", + "integration_connected": false + }, + "survey": { + "id": "5f3c4232c712de665632b3c5", + "created_at": "2029-04-20T13:00:00.000Z", + "updated_at": "2029-04-24T10:15:00.000Z", + "name": "Early User Feedback - Feature Requests", + "position": 2, + "segment_ids": [ + "5f3c4232c712de665632b3c6" + ], + "published_at": "2029-04-22T08:00:00.000Z", + "rate_unlimit_at": null, + "last_dropdown_items": [ + "Integrations", + "Analytics", + "Collaboration Tools", + "API Access", + "Other" + ], + "kind": "survey", + "stats": { + "started_count": 45, + "completed_count": 12, + "response_rate": 0.267 + }, + "steps": [ + { + "id": "5f3c4232c712de665632b3c7", + "body": "What feature would be most valuable for your workflow? Help us prioritize our roadmap!", + "preset": "survey_multiple_choice", + "dropdown_items": [ + "Integrations", + "Analytics", + "Collaboration Tools", + "API Access", + "Other" + ] + }, + { + "id": "5f3c4232c712de665632b3c8", + "body": "Thank you! We'll use your input to guide our development. πŸ› οΈ", + "preset": "thank_you" + } + ] + }, + "step": { + "id": "5f3c4232c712de665632b3c7", + "created_at": "2029-04-20T13:00:00.000Z", + "updated_at": "2029-04-24T10:15:00.000Z", + "body": "What feature would be most valuable for your workflow? Help us prioritize our roadmap!", + "preset": "survey_multiple_choice" } } } @@ -811,42 +1739,44 @@ Demos can also [sync Contact data](apis/demos.md?id=demos-in-the-crm) into the C ```json { - "id": "6fb70330dcbc39000325a94a", + "id": "5f3c4232c712de665632f1a1", "kind": "demo.started", - "sent_at": "2029-12-11T00:28:59.331Z", + "sent_at": "2029-07-15T14:25:30.890Z", "data": { - "action" : { - "id": "6f885a88e7daf34f6000e3eb" - }, - "profile": { - "id": "5f885a88e7daf3000e3eb4f6", - "email": "jane@example.com", - "uid": "92340834", - "name": "Jane E", - "last_seen_at": "2029-12-11T00:21:59.109Z", - "last_seen_session_count": 83, - ... + "action": { + "id": "5f3c4232c712de665632f1a2" }, + "profile": null, "demo_run": { - "id": "5fb7afb5ea19724169374269", - "referrer": "https://www.acme.co/products/analytics", - "created_what": "Chrome 191.0 (Mac)", - "created_where": "Oakland CA, US πŸ‡ΊπŸ‡Έ", - "anonymous_id": "5fb7afb5ea19724169374269", + "id": "5f3c4232c712de665632f1a3", + "created_at": "2029-07-15T14:20:00.000Z", + "updated_at": "2029-07-15T14:25:27.308Z", + "anonymous_id": "5f3c4232c712de665632f1a4", + "email": null, + "created_what": "Chrome 138 - Mac", + "created_where": "Calgary Alberta, CA πŸ‡¨πŸ‡¦", "consent_mode": "granted", - ... + "first_run": true, + "referrer": null }, "demo": { - "id": "5fb7936edee1f70011bfc4c9", - "name": "Demo of Analysis quickstart", - "description": "Our analysis goes deeper than you'd typically see in a trial", - "href": "https://app.acme.co/setup/tough-thing-to-do", - "page_title": "Analytics", - ... - "user": { - "id": "5490e42d65353700020030fa", - "email": "jim@acme.co", - "name": "Jim B" + "id": "6883d663cd779100179d6899", + "created_at": "2025-07-25T19:09:23.000Z", + "updated_at": "2025-07-25T19:10:50.463Z", + "name": "ClickHouse Console Overview", + "description": "Explore ClickHouse console, navigate clusters, and view tables. Learn how to manage huge data sets like Profiles EEV with 15 billion rows.", + "position": 1, + "href": "https://console.clickhouse.cloud/", + "page_title": "Services", + "urls": { + "dashboard": "https://app.chameleon.io/demos/6883d663cd779100179d6899" + }, + "created_user": { + "id": "630fbe394c27640010814ccb", + "created_at": "2022-08-31T20:02:01.000Z", + "updated_at": "2025-07-29T18:15:04.229Z", + "email": "anton@example.com", + "name": "Anton Kolmakov" } } } @@ -867,60 +1797,59 @@ It will be sent when the last step of the Demo is reached with `finished_kind=la ```json { - "id": "6fb70330dcbc39000325a94b", + "id": "688916adf1fd8340659b3221", "kind": "demo.finished", - "sent_at": "2029-12-11T00:28:59.331Z", + "sent_at": "2025-07-29T18:45:01.935Z", "data": { - "action" : { - "id": "6f885a88e7daf34f6000e3eb" + "action": { + "id": null }, + "profile": null, "demo_run": { - ..., - "finished_kind": "last_step", + "id": "68890d3304dc0e002da0ed68", + "created_at": "2025-07-29T18:04:35.000Z", + "updated_at": "2025-07-29T18:45:01.832Z", + "anonymous_id": "68890d331d5eca09f6b22846", + "email": null, + "created_what": "Mobile Safari 18 - iOS", + "created_where": "Mexico City Distrito Federal, MX πŸ‡²πŸ‡½", + "consent_mode": "granted", + "first_run": true, + "referrer": "https://www.chameleon.io/", + "finished_kind": "timeout_30m", "actions": [ { - "id": "", + "id": "68890d331d5eca09f6b22847", "name": "Demo Started", - ... + "timestamp": "2025-07-29T18:04:35.000Z" }, { - "id": "", - "name": "Demo Step Started", - ... - }, - ... - ], - "submissions": [ - { - "id": "6f885a84f600b0e38e7daf3e", - "step_id": "5fb7936edee1f70011bfc4c9", - "data": [ - { - "field": { - "id": "6fa88e7daf34f6000e3eb885", - "type": "email", - "name": "Email address", - "description": "" - }, - "value": "jane@example.io" - }, - { - "field": { - "id": "6fa88e7daf34f6000e3eb885", - "type": "select", - "name": "Urgency", - "description": "Knowing how quickly you want to evaluate Acme helps us mirror your urgency" - }, - "value": "this week" - }, - ... - ] + "id": "68890d451d5eca09f6b22859", + "name": "Demo Step Viewed", + "timestamp": "2025-07-29T18:15:12.000Z" } ], + "submissions": [] }, "demo": { - "id": "5fb7936edee1f70011bfc4c9", - ... + "id": "687a5a17a15837001bb7bae4", + "created_at": "2025-07-18T14:28:39.000Z", + "updated_at": "2025-07-21T18:18:21.844Z", + "name": "Chameleon Demos", + "description": "Discover how to enhance user engagement through tailored onboarding experiences using Chameleon's powerful features.", + "position": 9, + "href": "https://app.chameleon.io/demos", + "page_title": "Demos", + "urls": { + "dashboard": "https://app.chameleon.io/demos/687a5a17a15837001bb7bae4" + }, + "created_user": { + "id": "6257c12532625b000f6ba77b", + "created_at": "2022-04-14T06:37:25.000Z", + "updated_at": "2025-07-29T14:07:20.979Z", + "email": "sonia@example.com", + "name": "Sonia Schiau" + } } } } @@ -939,23 +1868,48 @@ It will be sent when the following conditions are met ```json { - "id": "6fb70330dcbc39000325a94b", + "id": "68894c22f288e43bc9d7e567", "kind": "demo.reveal", - "sent_at": "2029-12-11T00:28:59.331Z", + "sent_at": "2025-07-29T22:15:45.678Z", "data": { - "action" : { - "id": "6f885a88e7daf34f6000e3eb" + "action": { + "id": "68894c1fd5b8f67ad2e3c234" }, + "profile": null, "demo_run": { - ..., - "reveal_domain": "zenflex.io", - "reveal_name": "Zen Flexing Aura Ltd.", - "clearbit_uid": "f47ac10b-58cc-4372-a567-0e02b2c3d479", - "consent_mode": "granted" + "id": "68894c1b04dc0e002da0f123", + "created_at": "2025-07-29T22:12:35.000Z", + "updated_at": "2025-07-29T22:15:44.832Z", + "anonymous_id": "68894c1b1d5eca09f6b22890", + "email": null, + "created_what": "Chrome 138 - Windows", + "created_where": "Toronto Ontario, CA πŸ‡¨πŸ‡¦", + "consent_mode": "granted", + "first_run": true, + "referrer": "https://www.google.com/", + "reveal_domain": "techstartup.ca", + "reveal_name": "Toronto Tech Startups Inc.", + "clearbit_uid": "a47bc20c-68dd-4372-b567-1e02c3d4e890" }, "demo": { - "id": "5fb7936edee1f70011bfc4c9", - ... + "id": "6883d663cd779100179d6899", + "created_at": "2025-07-25T19:09:23.000Z", + "updated_at": "2025-07-25T19:10:50.463Z", + "name": "ClickHouse Console Overview", + "description": "Explore ClickHouse console, navigate clusters, and view tables. Learn how to manage huge data sets like Profiles EEV with 15 billion rows.", + "position": 1, + "href": "https://console.clickhouse.cloud/", + "page_title": "Services", + "urls": { + "dashboard": "https://app.chameleon.io/demos/6883d663cd779100179d6899" + }, + "created_user": { + "id": "630fbe394c27640010814ccb", + "created_at": "2022-08-31T20:02:01.000Z", + "updated_at": "2025-07-29T18:15:04.229Z", + "email": "anton@example.com", + "name": "Anton Kolmakov" + } } } } @@ -972,44 +1926,87 @@ each data item has a `field` as [DemoFormField](apis/demos.md?id=schema-demo-for ```json { - "id": "6fb70330dcbc39000325a94b", + "id": "68895d33f288e43bc9d7e678", "kind": "demo.form.submitted", - "sent_at": "2029-12-11T00:28:59.331Z", + "sent_at": "2025-07-29T23:25:18.456Z", "data": { - "action" : { - "id": "6f885a88e7daf34f6000e3eb", + "action": { + "id": "68895d30d5b8f67ad2e3c345", "submission": { - "id": "6f885a84f600b0e38e7daf3e", - "step_id": "5fb7936edee1f70011bfc4c9", + "id": "68895d2cf600b0e38e7daf89", + "step_id": "6883d663cd779100179d689a", "data": [ { "field": { - "id": "6fa88e7daf34f6000e3eb885", + "id": "68895d25af34f6000e3eb567", "type": "email", - "name": "Email address", - "description": "" + "name": "Work Email", + "description": "We'll use this to send you demo access" }, - "value": "jane@example.io" + "value": "sarah.thompson@datacompany.io" }, { "field": { - "id": "6fa88e7daf34f6000e3eb885", + "id": "68895d26af34f6000e3eb568", + "type": "text", + "name": "Company Name", + "description": "What company do you work for?" + }, + "value": "DataFlow Analytics" + }, + { + "field": { + "id": "68895d27af34f6000e3eb569", "type": "select", - "name": "Urgency", - "description": "Knowing how quickly you want to evaluate Acme helps us mirror your urgency" + "name": "Company Size", + "description": "How many employees work at your company?" }, - "value": "this week" + "value": "51-200" }, - ... - } - ], + { + "field": { + "id": "68895d28af34f6000e3eb570", + "type": "select", + "name": "Timeline", + "description": "When are you looking to implement a solution?" + }, + "value": "Within 1 month" + } + ] + } }, + "profile": null, "demo_run": { - ..., + "id": "68895d1b04dc0e002da0f234", + "created_at": "2025-07-29T23:20:35.000Z", + "updated_at": "2025-07-29T23:25:17.832Z", + "anonymous_id": "68895d1b1d5eca09f6b22901", + "email": "sarah.thompson@datacompany.io", + "created_what": "Chrome 138 - Mac", + "created_where": "San Francisco California, US πŸ‡ΊπŸ‡Έ", + "consent_mode": "granted", + "first_run": true, + "referrer": "https://www.linkedin.com/" }, "demo": { - "id": "5fb7936edee1f70011bfc4c9", - ... + "id": "6883d663cd779100179d6899", + "created_at": "2025-07-25T19:09:23.000Z", + "updated_at": "2025-07-25T19:10:50.463Z", + "name": "ClickHouse Console Overview", + "description": "Explore ClickHouse console, navigate clusters, and view tables. Learn how to manage huge data sets like Profiles EEV with 15 billion rows.", + "position": 1, + "href": "https://console.clickhouse.cloud/", + "page_title": "Services", + "urls": { + "dashboard": "https://app.chameleon.io/demos/6883d663cd779100179d6899" + }, + "created_user": { + "id": "630fbe394c27640010814ccb", + "created_at": "2022-08-31T20:02:01.000Z", + "updated_at": "2025-07-29T18:15:04.229Z", + "email": "anton@example.com", + "name": "Anton Kolmakov" + } } } } @@ -1037,20 +2034,46 @@ The flow can be arbitrarily complex but typically follows one of these paths: ```json { - "id": "6fb70330dcbc39000325a94b", + "id": "68896e44f288e43bc9d7e789", "kind": "demo.email.added", - "sent_at": "2029-12-11T00:28:59.331Z", + "sent_at": "2025-07-30T00:35:28.678Z", "data": { - "action" : { - "id": "6f885a88e7daf34f6000e3eb", - "email": "jane@acme.co" + "action": { + "id": "68896e41d5b8f67ad2e3c456", + "email": "michael.chang@techcorp.sg" }, + "profile": null, "demo_run": { - ..., + "id": "68896e2b04dc0e002da0f345", + "created_at": "2025-07-30T00:30:15.000Z", + "updated_at": "2025-07-30T00:35:27.832Z", + "anonymous_id": "68896e2b1d5eca09f6b22012", + "email": "michael.chang@techcorp.sg", + "created_what": "Chrome 138 - Mac", + "created_where": "Singapore Singapore, SG πŸ‡ΈπŸ‡¬", + "consent_mode": "granted", + "first_run": false, + "referrer": "https://www.chameleon.io/demos" }, "demo": { - "id": "5fb7936edee1f70011bfc4c9", - ... + "id": "687a5a17a15837001bb7bae4", + "created_at": "2025-07-18T14:28:39.000Z", + "updated_at": "2025-07-21T18:18:21.844Z", + "name": "Chameleon Demos", + "description": "Discover how to enhance user engagement through tailored onboarding experiences using Chameleon's powerful features.", + "position": 9, + "href": "https://app.chameleon.io/demos", + "page_title": "Demos", + "urls": { + "dashboard": "https://app.chameleon.io/demos/687a5a17a15837001bb7bae4" + }, + "created_user": { + "id": "6257c12532625b000f6ba77b", + "created_at": "2022-04-14T06:37:25.000Z", + "updated_at": "2025-07-29T14:07:20.979Z", + "email": "sonia@example.com", + "name": "Sonia Schiau" + } } } } diff --git a/docs/webhooks/profiles.md b/docs/webhooks/profiles.md index ea61203..bcb879c 100644 --- a/docs/webhooks/profiles.md +++ b/docs/webhooks/profiles.md @@ -33,7 +33,7 @@ POST https://api.chameleon.io/v3/observe/hooks/:account_secret/profiles ```json { "uid": 18821, - "email": "leon@chmln.co", + "email": "user@example.com", "first_name": "Leon", "role": "admin", "last_import_at": "2029-04-07T12:18:00Z",