Welcome to the Telli Health Developer Guide, which will guide you through the Telli Health integration process, and focuses on how to get data from, or send data to, Telli Health's patient monitoring devices.
Telli Health has Generation 1 and Generation 2 patient monitoring devices in circulation.
Devices that currently support Gen2 capabilities: TelliBP01
To provide a seamless transition between API versions and device generations, readings from either generation device are cross-compatible with either API version endpoint. Therefore, Gen1 device readings can be received on API v2 endpoints, and Generation 2 device readings can be received on existing API v1 endpoints.
NOTE: Other Gen2 device capabilities and data are NOT supported on API v1 endpoints.
It is easy to integrate with our hardware before purchasing Telli Health devices. The OpenAPI specification provides the information needed to develop ingestion slugs and control interfaces.
Telli Health highly recommends creating a single endpoint for all message types or a single endpoint slug for each message type, such as readings, heartbeat messages, or setting acknowledgements. The endpoint should parse and handle the inbound data based on the message type in the schema object.
For full system functionality, the platform developer must provide Telli Health with the following information:
In exchange, Telli Health provides the developer with an API key for calling the endpoint(s) on the Telli Health platform.
After you purchase Telli Health devices, you will receive an email containing the Device ID and Serial number for the device(s); you must match each device to a user on your platform.
All integrations must be able to receive readings via the readings webhook. As Telli Health’s listener receives readings, Telli Health's data gateway sends your data to the POST URL in your profile in near real-time by HTTPS POST. Telli Health’s POST will come from multiple US – East Amazon Cloud Storage IP addresses.
For high availability, data packets are replicated in a Telli Health Secure Database in the event of system outages. Contact Telli Health support if you require a playback of your device readings data.
The Telli Health platform recommends that you authenticate and secure inbound and outbound connections.
Successful authentication creates a token that grants access to protected resources. To secure your connection, request an authentication token that you can add to all headers:
x-api-key: \<token\>
Contact Telli Health support to enable authentication.
A Gen1 device delivered a new reading to the Telli Health platform.
Reading value messages are delivered when:
Reading transmission types include Blood Pressure, Blood Glucose, Weight Scale, SpO2 Pulse Oximetry, Peak Flow, Thermometer, Sleeping Mat Activity, and Sleeping Mat Duration.
Both the Sleeping Mat Activity and Sleeping Mat Duration readings provide data for Telli Health's sleep mat and resting heart monitor service.
Sleeping Mat Activity provides data collected every four hours during a fixed 12-hour interval between 8 p.m. (20:00) and 8 a.m. (08:00). Sleep mat averages are taken while the mat is in use. Sampling is paused if a user gets out of bed without the mat being active.
Sleeping Mat Duration provides data collected at the end of the sleep interval.
required | BloodPressureData (object) or BloodGlucoseData (object) or WeightData (object) or SpO2Data (object) or TemperatureData (object) or PeakFlowData (object) or SleepingMatActivityData (object) or SleepingMatDurationData (object) |
deviceId required | string Represents the device identifier mostly IMEI. |
readingType required | string Enum: "BloodPressure" "BloodGlucose" "Weight" "SpO2" "Temperature" "PeakFlow" "SleepingMatActivity" "SleepingMatDuration" Represents the reading type. |
time required | string <int64> Unix timestamp in milliseconds |
{- "data": {
- "arrhythmia": 0,
- "diastolic": 98,
- "pulse": 62,
- "systolic": 122
}, - "deviceId": "864593054464085",
- "readingType": "BloodPressure",
- "time": "1721382524000"
}
A new heartbeat was received from the device.
By default, Gen2 devices send 3 heartbeats per 24-hour period, or one heartbeat every 8 hours. The heartbeat timer resets each time a device is operated; therefore, the next heartbeat will be received +8 hours from the device's last successful operation. Currently, this behavior applies only to TelliBP01.
For example, if a user takes one reading per day, then depending on connectivity and sufficient battery, expect the device to receive one reading and two heartbeats during that day.
Gen2 devices capable of alert reminders must have the alert reminder enabled with a set start and stop time. The reminder stop time must be at least one hour later than the reminder start time. When a device is in reminder mode (for example, if the start time is 08:00 and it is now 08:05), the heartbeat message will be delayed until the reminder is cleared.
Heartbeat from the device
type required | string Value: "Heartbeat" Represents the reading type. |
deviceId required | string^\d{15}$ The IMEI of the device |
time required | string <integer> Response time from the device in epoch format |
tzOffsetMinutes required | string <integer> ^(-)?\d+$ UTC offset in minutes |
genVer required | string <string> Value: "2" The device generation version |
required | object (Devdata) Provides device metadata, including information such as battery level, signal strength, and more. |
{- "type": "Heartbeat",
- "deviceId": "864581069137614",
- "time": "string",
- "tzOffsetMinutes": "-200",
- "genVer": "2",
- "devdata": {
- "r": "1",
- "batt": "9",
- "cycles": "0"
}
}
The user manually cleared the adherence reminder on the device without taking a reading.
A manually cleared message alert is delivered to the Telli Health platform from the device when:
Cleared reminder from the device
type required | string Value: "ReminderCleared" Represents the reading type. |
deviceId required | string^\d{15}$ The IMEI of the device |
time required | string <integer> Response time from the device in epoch format |
tzOffsetMinutes required | string <integer> ^(-)?\d+$ UTC offset in minutes |
genVer required | string <string> Value: "2" The device generation version |
required | object (Devdata) Provides device metadata, including information such as battery level, signal strength, and more. |
{- "type": "ReminderCleared",
- "deviceId": "864581069137614",
- "time": "string",
- "tzOffsetMinutes": "-200",
- "genVer": "2",
- "devdata": {
- "r": "1",
- "batt": "9",
- "cycles": "0"
}
}
A device responded to a settings change request.
Gen2 devices may receive settings for reminder alerts. Since the device may be off at the time the settings are sent, this message is delivered asynchronously. The device responds during its next successful connection session. When the platform receives an acknowledgement (ACK) from the device, the platform publishes an ACK to the registered endpoint.
The device response to the settings change request
type required | string Value: "SettingsResponse" Represents the reading type. |
deviceId required | string^\d{15}$ The IMEI of the device |
time required | string <integer> Response time from the device in epoch format |
tzOffsetMinutes required | string <integer> ^(-)?\d+$ UTC offset in minutes |
genVer required | string <string> Value: "2" The device generation version |
status required | string Enum: "ACK" "NACK" ACK - means the device acknowledged the change, and NACK means it did not |
{- "type": "SettingsResponse",
- "deviceId": "864581069137614",
- "time": "string",
- "tzOffsetMinutes": "-200",
- "genVer": "2",
- "status": "ACK"
}
A Gen2 device delivered a new reading to the Telli Health platform.
Reading value messages are delivered when:
OR
Reading transmission types include Blood Pressure, Blood Glucose, Weight Scale, SpO2 Pulse Oximetry, Peak Flow, Thermometer, Sleeping Mat Activity, and Sleeping Mat Duration.
Both the Sleeping Mat Activity and Sleeping Mat Duration readings provide data for Telli Health's sleep mat and resting heart monitor service.
Sleeping Mat Activity provides data collected every four hours during a fixed 12-hour interval between 8 p.m. (20:00) and 8 a.m. (08:00). Sleep mat averages are taken while the mat is in use. Sampling is paused if a user gets out of bed without the mat being active.
Sleeping Mat Duration provides data collected at the end of the sleep interval.
required | BloodPressureData (object) or BloodGlucoseData (object) or WeightData (object) or SpO2Data (object) or TemperatureData (object) or PeakFlowData (object) or SleepingMatActivityData (object) or SleepingMatDurationData (object) Holds the reading data |
deviceId required | string Represents the device identifier mostly IMEI. |
readingType required | string Enum: "BloodPressure" "BloodGlucose" "Weight" "SpO2" "Temperature" "PeakFlow" "SleepingMatActivity" "SleepingMatDuration" Represents the reading type. |
time required | string^\d+$ Unix timestamp in milliseconds |
required | string or null UTC offset in minutes. |
genVer required | string Enum: "1" "2" The device generation version |
required | any or null Indicates if the reading if a memory |
required | Devdata (object) or null Contains device metadata like radious, battery level and cycles. It could be |
{- "data": {
- "arrhythmia": 0,
- "diastolic": 98,
- "pulse": 62,
- "systolic": 122
}, - "deviceId": "864593054464085",
- "readingType": "BloodPressure",
- "time": "1721382524000",
- "mem": "0",
- "tzOffsetMinutes": "-200",
- "genVer": "2",
- "devdata": {
- "r": "1",
- "batt": "9",
- "cycles": "0"
}
}
The device’s settings will be updated.
Gen2 devices may receive settings for the reminder alerts. Since the device may be off at the time the settings are sent, this message is delivered asynchronously. The device responds during its next successful connection session. When the platform receives an acknowledgement (ACK) from the device, the platform publishes an ACK to the registered endpoint. When the settings endpoint is called between ACK messages, the settings value updates to the newly requested value.
An alert setting will not activate for a time set in the past, but will remain inactive until it's set time is reached during the next alert timeframe. For example, if the start time is 08:00 and it is now 08:05, the alert message will be delayed until 08:00 on the following day.
deviceId required | string^\d{15}$ The IMEI of the device |
enabled required | boolean Enable or disable alarms on the device |
arstart required | string^[0-2][0-9][0-5][0-9]$ Defines when the device alarm should be started at. The format is in HH:MM |
arstop required | string^[0-2][0-9][0-5][0-9]$ Defines when the device alarm should be stopped at. The format is in HH:MM |
{- "enabled": "true",
- "arstart": "1100",
- "arstop": "1230"
}
{- "message": "Validation error",
- "errors": [
- {
- "path": "arstop",
- "message": "arstop must be at least an hour upfront then arstart"
}
]
}