Sensors

Mini Apps support access to the device's accelerometer, gyroscope, and orientation sensors. All sensor APIs require Bot API 8.0+.

Accelerometer

The accelerometer measures device acceleration along three axes (including gravity). Accessed via Telegram.WebApp.Accelerometer.

Properties

Property	Type	Description
isStarted	Boolean	Whether the accelerometer is currently collecting data
x	Float	X-axis acceleration (m/s²)
y	Float	Y-axis acceleration (m/s²)
z	Float	Z-axis acceleration (m/s²)

Methods

start

Telegram.WebApp.Accelerometer.start(params, callback)

Starts collecting acceleration data.

Parameter	Type	Required	Description
params	Object	No	Start parameters
params.refresh_rate	Integer	No	Refresh rate in ms, default 1000, range 20-1000
callback	Function	No	Callback with (started) parameter

stop

Telegram.WebApp.Accelerometer.stop(callback)

Stops collecting acceleration data.

Parameter	Type	Required	Description
callback	Function	No	Callback with (stopped) parameter

Example

const accel = Telegram.WebApp.Accelerometer;

accel.start({ refresh_rate: 100 }, (started) => {
  if (started) {
    console.log('Accelerometer started');
  }
});

Telegram.WebApp.onEvent('accelerometerChanged', () => {
  console.log(`X: ${accel.x}, Y: ${accel.y}, Z: ${accel.z}`);
});

// Stop collecting
// accel.stop();

DeviceOrientation

The device orientation sensor provides information about the device's orientation in 3D space. Accessed via Telegram.WebApp.DeviceOrientation.

Properties

Property	Type	Description
isStarted	Boolean	Whether the sensor is currently collecting data
absolute	Boolean	Whether the orientation data is absolute (relative to Earth's coordinate system)
alpha	Float	Z-axis rotation angle (0-360°)
beta	Float	X-axis rotation angle (-180° to 180°)
gamma	Float	Y-axis rotation angle (-90° to 90°)

Methods

start

Telegram.WebApp.DeviceOrientation.start(params, callback)

Starts collecting device orientation data.

Parameter	Type	Required	Description
params	Object	No	Start parameters
params.refresh_rate	Integer	No	Refresh rate in ms, default 1000, range 20-1000
params.need_absolute	Boolean	No	Whether absolute orientation data is needed, default false
callback	Function	No	Callback with (started) parameter

stop

Telegram.WebApp.DeviceOrientation.stop(callback)

Stops collecting device orientation data.

Parameter	Type	Required	Description
callback	Function	No	Callback with (stopped) parameter

Example

const orientation = Telegram.WebApp.DeviceOrientation;

orientation.start({
  refresh_rate: 100,
  need_absolute: true
}, (started) => {
  if (started) {
    console.log('Device orientation sensor started');
  }
});

Telegram.WebApp.onEvent('deviceOrientationChanged', () => {
  console.log(`Alpha: ${orientation.alpha}`);
  console.log(`Beta: ${orientation.beta}`);
  console.log(`Gamma: ${orientation.gamma}`);
  console.log(`Absolute: ${orientation.absolute}`);
});

Gyroscope

The gyroscope measures the angular velocity of the device along three axes. Accessed via Telegram.WebApp.Gyroscope.

Properties

Property	Type	Description
isStarted	Boolean	Whether the gyroscope is currently collecting data
x	Float	X-axis angular velocity (rad/s)
y	Float	Y-axis angular velocity (rad/s)
z	Float	Z-axis angular velocity (rad/s)

Methods

start

Telegram.WebApp.Gyroscope.start(params, callback)

Starts collecting gyroscope data.

Parameter	Type	Required	Description
params	Object	No	Start parameters
params.refresh_rate	Integer	No	Refresh rate in ms, default 1000, range 20-1000
callback	Function	No	Callback with (started) parameter

stop

Telegram.WebApp.Gyroscope.stop(callback)

Stops collecting gyroscope data.

Parameter	Type	Required	Description
callback	Function	No	Callback with (stopped) parameter

Example

const gyro = Telegram.WebApp.Gyroscope;

gyro.start({ refresh_rate: 50 }, (started) => {
  if (started) {
    console.log('Gyroscope started');
  }
});

Telegram.WebApp.onEvent('gyroscopeChanged', () => {
  console.log(`Angular velocity X: ${gyro.x}, Y: ${gyro.y}, Z: ${gyro.z}`);
});

Notes

• All sensor APIs require Bot API 8.0+
• Not all devices support sensors. Listen for the corresponding *Failed events to handle unsupported cases
• Call stop() when done to release sensor resources and save battery
• Lower refresh_rate values mean more frequent updates but higher power consumption