--- title: Message events slug: technical-docs-v1/message-events icon: 💽 docTags: createdAt: 2023-12-27T14:37:35.823Z --- # Introduction To keep your app informed about the user's progress within the plug-in, we transmit data via **message events** at various stages. This document describes the different types of events, when they are sent, and their data format. The events are in JSON format and contain information about the health check's progress and the final results. # Prerequisites Make sure you've gone through the following documentation: - [Request plug-in URL](docId\:ODjXiFncpcGWMtTWd6J1C) - [Embed plug-in](docId\:vywPZGYZObqqSWUsjQy_4) To learn how to listen for these data messages in web apps, refer to the [Listening to message events](docId\:w5RBnpznDXL8rZKEO-PjI) page. # Overview We currently distinguish the following events: - StartNewMeasurement - RecordingStarted - RecordingStopped - Results - Buckets - BucketSummaries - UserFinished - Dismiss - Error (informative) ## Summary of event occurrences When the user clicks the 'Perform Measurement' button on the welcome screen, a `Start New Measurement` event is sent. Upon reaching the recording screen, users encounter the camera stream along with a start button. Pressing the start button initiates the quality-checking process. If the conditions are favourable and the check passes, the actual recording starts and a `Recording Started` event is sent. The timer begins counting down, and upon reaching zero, the measurement concludes, prompting a `Recording Stopped` event. The subsequent events depend on the outcome of the measurement. If the measurement is successful, three events containing the health check results are sent: `Results`, `Buckets` and `BucketSummaries`. However, there might be instances where the quality deteriorates too much during the health check, rendering an accurate assessment unfeasible. For instance, this could occur if the lighting abruptly dims. In such cases, an '`Error`' event is sent and users are presented with two choices: they can restart the health check by selecting the ‘*try again*’ option, or they can opt to conclude the health check without completing it successfully by clicking the ‘*continue*’ button. Choosing the 'try again' option brings them back to the start of the health check process. If they select the 'continue' option, no biomarker results will be generated, and a `userFinished` event will be sent. The `dismiss` event is sent whenever the web plugin should be closed. The event types are further explained in detail below. # Event types The diagram below illustrates the different stages within the plug-in and the corresponding events triggered. ![](https://api.archbee.com/api/optimize/_0R_DnpmBBLLXmaoWvG2u/RkEh3iTUCD2eJT8ghc10K_image.png) ## Start New Measurement :::hint{type="info"} Sent when the user clicks on the 'Perform Measurement' button on the Welcome screen. ::: **Event Data** :::CodeblockTabs Success ```json { "stage": "startNewMeasurement", "data": { "onboarding": true } } ``` ::: - `stage`: "startNewMeasurement" - `data`: Additional details - `onboarding`: boolean; when *True*, the user first landed on the onboarding screen. When *False*, the user immediately advanced to the recording screen. ## Recording Started :::hint{type="info"} Sent when the user clicks the record button and the timer starts. ::: **Event Data** :::CodeblockTabs Success ```json { "stage": "recordingStarted", "uuid": "380cae2a32ed4023be60a63c3ee97e95", } ``` ::: - `stage`: "recordingStarted" - `uuid`: health check UUID ## Recording Stopped :::hint{type="info"} Sent when the recording stopped, i.e. the recording timer ends. ::: **Event Data** :::CodeblockTabs Success ```json { "stage": "recordingStopped", "uuid": "380cae2a32ed4023be60a63c3ee97e95", } ``` ::: - `stage`: "recordingStopped" - `uuid`: health check UUID ## Results The results of the health check in their most basic form, listing the extracted biomarker values. :::hint{type="info"} Sent after the recording is completed. This takes between 1 to a maximum of 20 seconds after the *recordingStopped* event. ::: IntelliProve calculates the following biomarkers: - `heart_rate`: Heart rate in beats per minute - `respiratory_rate`: Respiratory rate in breaths per minute (nullable) - `heart_rate_variability`: Heart Rate Variability or HRV in milliseconds - `ans_balance`: Balance of autonomous nervous system, dimensionless - `resonant_breathing_score`: Resonant Breathing score in percentage - `morning_readiness`: Morning Readiness score, dimensionless (only available between morning hours) - `acute_mental_stress_score`: Acute Mental Stress Score, dimensionless - `mental_health_risk`: Mental Health Risk as enumerator 1 ("low"), 2 ("medium") or 3 ("high") For more info on how to interpret these values, please refer to our [Insights & biomarkers](docId:3PRUszMjT22MzXVKUFpWd) documentation. :::hint{type="warning"} Please note that one or more biomarker values may be unavailable if the measurement quality is insufficient or if not relevant for the current time of the day (e.g. morning readiness). Biomarkers of such are set to *null*. ::: In addition to the biomarkers we also provide the `timestamp` and `epoch` properties representing both an ISO and integer (UTC) representation of the time of the measurement. **Event Data** :::CodeblockTabs Success ```json { "stage": "results", "uuid": "380cae2a32ed4023be60a63c3ee97e95", "patient": "5jb54ojlk23m", "performer": "083lna91utnz4v", "data": { "epoch": "1692282217", "timestamp": "2023-08-17T16:23:37+02:00", "heart_rate": "54", "respiratory_rate": "6", "heart_rate_variability": "87", "ans_balance": "2", "resonant_breathing_score": "99", "morning_readiness": "8", "acute_mental_stress_score": "3", "mental_health_risk": null } } ``` ::: - `stage`: "results" - `uuid`: health check UUID - `patient`: (nullable) Patient reference, initially passed in the web plug-in URL - `performer`: (nullable) Performer reference, initially passed in the web plug-in URL - `data`: Results data object ## Buckets The biomarker buckets provide the results in an alternative format, grouping them in logical sets and providing more context to the values in each set (bucket). :::hint{type="info"} Sent after the recording is completed. This takes between 1 to a maximum of 20 seconds after the timer ends. ::: IntelliProve offers a holistic approach to well-being by organizing information into distinct buckets; i.e. **physical health**, **mental health, sleep and energy, and mindfulness**. Each **`bucket`** has the following properties: - The **`name`** distinguishes the specific bucket. A list of the currently available buckets: "physical", "mental", "energy\_sleep", "mindfulness". - The **`timestamp`** and **`timestamp_epoch`** properties present both an ISO and integer (UTC) representation with the time of the measurement. - The **`biomarkers`** represent a list of selected biomarkers relevant to the specific bucket. - The **`status`** indicates the overall users' health state for the current bucket, based on the biomarker values. We define three different states: "good", "neutral" and "bad". Each **`biomarker`** consists of the following properties: - The **`value`** is the actual numerical value obtained for the biomarker during the health check. It can be an integer or a floating point number. - The **`range`** represents the entire span of possible values for that the biomarker, indicated by minimum and a maximum. - The **`zone`** indicates where the biomarker value falls among three categories "good," "neutral," and "bad", which relates to health condition. - The **`optimum`** defines how the range should be interpreted and visualized. There are three possible values for optimum: "low," "high," and "middle." - For "low": Lower values are categorized as "good" (green color), while higher values are categorized as "bad" (red color) - For "high": Higher values are categorized as "good" (green color), while lower values are categorized as "bad" (red color). - For "middle": The "good" zone (green color) is centered around the middle of the range. Values lower or higher than this midpoint are categorized as "bad" (red color). ::Image[]{src="https://api.archbee.com/api/optimize/_0R_DnpmBBLLXmaoWvG2u/d15PzMYiUOFLIHC4qJEoc_group-123.png" size="50" width="1093" height="1015" position="center" showCaption="false"} :::hint{type="info"} For each bucket, we provide **personalised** **feedback** **and tips** tailored to their specific values. Learn more about this in the next event type. ::: **Event Data** :::CodeblockTabs Success ```json { "stage": "buckets", "uuid": "380cae2a32ed4023be50a63c3ee97e95", "patient": "test-patient", "performer": "test-performer", "data": { "buckets": [ { "name": "physical", "timestamp_epoch": 1692282217, "timestamp": "2023-08-17T16:23:37+02:00", "status": "good", "biomarkers": [ { "name": "heart_rate", "value": 54.0, "zone": "good", "unit": "bpm", "range": [ 36.0, 216.0 ], "optimum": "low" }, { "name": "respiratory_rate", "value": 6.0, "zone": "good", "unit": "brpm", "range": [ 4.0, 48.0 ], "optimum": "middle" } ] }, ... // Other buckets ] } } ``` ::: - `stage`: "buckets" - `uuid`: health check UUID - `patient`: (nullable) Patient reference, initially passed in the web plug-in URL - `performer`: (nullable) Performer reference, initially passed in the web plug-in URL - `data`: Buckets data object ## Bucket Summaries For each bucket, we also provide a human-readable representation of the results in the format of personalised feedback (summary) and tips. :::hint{type="info"} Sent after the recording is completed. Since feedback and tips are generated on the fly, it takes some additional time before this event is sent. Expect up to 5 seconds extra. ::: **Event Data** ```json { "stage": "bucketSummaries", "uuid": "380cae2a32ed4023be60a63c3ee97e95", "patient": "test-patient", "performer": "test-performer", "data": { "summaries": [ { "name": "physical", "summary": "Your heart rate is very low, suggesting a state of rest or recovery. Your respiratory rate is slow, indicating a relaxed and calm state.", "tip": "Based on your heart rate and respiratory rate, it appears that you are in a state of deep relaxation and calmness. This suggests that you are in good physical and mental health. It is important to continue practicing stress management techniques to maintain this state of wellbeing." }, { "name": "mindfulness", "summary": "Congratulations! Your mindfulness exercise is highly effective. Your resonant breathing score of 99 indicates a strong synchronization between your breathing frequency and heart rate variability. Additionally, your low respiratory rate and heart rate suggest that you are in a state of deep relaxation and good cardio health. Keep up the excellent work!", "tip": "To further improve your mindfulness exercise, you can try incorporating longer exhales during your breathing practice. This can help enhance the relaxation response and promote even greater synchronization between your breathing and heart rate variability. Keep up the great work!" }, // ... Other buckets ] } } ``` - `stage`: "bucketSummaries" - `uuid`: health check UUID - `patient`: (nullable) Patient reference, initially passed in the web plug-in URL - `performer`: (nullable) Performer reference, initially passed in the web plug-in URL - `data`: (nullable) Buckets summaries data object ## UserFinished Occasionally, the conditions may deteriorate while performing the health check, making an accurate health assessment unfeasible. For instance, this might happen if the lighting suddenly gets very dim. In such instances, users are presented with two choices: they can restart the health check by selecting the ‘*try again*’ option, or they can opt to conclude the health check without completing it successfully by clicking the ‘*continue*’ button. If they select the latter option, no biomarker results will be generated. We will notify you of this outcome with a “userFinished” event. This event is also sent when the user's device does not have a camera or when the necessary permissions to access the camera have not been granted. :::hint{type="info"} Sent in the situation where the user ends the health scan without successfully performing a measurement. ::: **Event Data** :::CodeblockTabs JSON ```json { "stage": "userFinished", "data": { } // RFU } ``` ::: - `stage`: "userFinished" - `data`: *Reserved for future use* ## Dismiss We will notify you with a "dismiss" event when the web plugin can be closed. This can be because of the following reasons: - The user chose to abort the health check without starting it, i.e. by clicking the "return" button - The measurement is finished and the results are sent via the "results" event *(only sent when not using the built-in results screen)* - The user chose to continue without performing the health scan :::hint{type="info"} Sent when the web plugin should be closed. ::: **Event Data** :::CodeblockTabs JSON ```json { "stage": "dismiss", "data": { } // RFU } ``` ::: - `stage`: "dismiss" - `data`: *Reserved for future use* ## Error (informative) If the health check did not complete successfully, we handle the error and retry internally. For full transparency, we forward this error as an event in case your app needs to keep track of this. :::hint{type="info"} Sent to inform the platform that a health check. The actual error handling is managed internally in the web plugin app. ::: **Event Data** ```json { "stage": "error", "uuid": "380cae2a32ed4023be50a63c3ee97e95", "patient": "test-patient", "performer": "test-performer", "data": { "code": 10, "description": "", "fatal": False } } ``` - `stage`: "error" - `uuid`: health check UUID - `patient`: (nullable) Patient reference, initially passed in the web plug-in URL - `performer`: (nullable) Performer reference, initially passed in the web plug-in URL - `data`: (nullable) Error data object ##