Design goals

No runtime overhead
As close to 1:1 with original API
Only encode what is documented

Usage

Install the package via npm:

npm install rescript-telegram-webapp

In your rescript.json, add the dependency:

{
  "dependencies": [
+   "rescript-telegram-webapp"
  ]
}

As per Telegram's documentation, include the Telegram Web App script in your HTML:

<script src="https://telegram.org/js/telegram-web-app.js?59"></script>

Get a reference to the telegramWebApp record in your ReScript code:

open TelegramWebApp.Global

Fields of telegramWebApp can be accessed directly, e.g. telegramWebApp.initData
Methods are available in modules named after the objects in the original API, e.g. TelegramWebApp.WebAppAPI, TelegramWebApp.MainButtonAPI, etc.

telegramWebApp->TelegramWebApp.WebAppAPI.ready
telegramWebApp.hapticFeedback->TelegramWebApp.HapticFeedbackAPI.impactOccurred(Medium)
telegramWebApp.mainButton.text = "Press me"
telegramWebApp.mainButton.isVisible = true

Difference in APIs

Applying methods

Object oriented APIs are modeled as record types, and functions that act on those records. For example:

window.Telegram.WebApp.ready();

Becomes

open TelegramWebApp.Global
TelegramWebApp.WebAppAPI.ready(telegramWebApp)

Or, using pipe operator:

telegramWebApp->TelegramWebApp.WebAppAPI.ready

All enumerable strings are Variants

It is now possible to switch on errors or statuses and expect exhaustiveness checking.

open TelegramWebApp.Global
open TelegramWebApp.WebAppAPI
telegramWebApp
->openInvoice("invoice_12345", ~callback=status => {
  switch status {
  | Paid => Console.log("Paid")
  | Cancelled => Console.log("Cancelled")
  | Failed => Console.log("Failed")
  | Pending => Console.log("Pending")
  | UndocumentedStatus(value) => Console.log(value)
  }
})

Note the UndocumentedStatus(value) case, for compatibility with future additions to Bot API.

A subscription method per event type

Every event has its dedicated on<EventName> and off<EventName> functions, to provide better type safety. For example, subscribing to the fullscreenChanged event looks like this:

open TelegramWebApp.Global
open TelegramWebApp.WebAppAPI
let handleFullscreenChanged: Events.fullscreenChanged = event => {
  if event.isFullscreen {
    Console.log("Entered fullscreen")
  } else {
    Console.log("Exited fullscreen")
  }
}
telegramWebApp->onFullscreenChanged(handleFullscreenChanged)
telegramWebApp->offFullscreenChanged(handleFullscreenChanged)

WebAppAPI.Events contains type definitions for all event handler signatures.

Submodules

In the original API, some methods are grouped into nested objects. For example, Telegram.WebApp.MainButton. In ReScript, the data structure is preserved, and the methods are grouped into modules. For example, accessing the main button's text is straightforward:

open TelegramWebApp.Global
let mainButtonText = telegramWebApp.mainButton.text

And setting the main button's text looks like this:

open TelegramWebApp.Global
open TelegramWebApp.MainButtonAPI
telegramWebApp.mainButton
->setText("New Button Text")
->ignore

Most of the submodule methods return the object they operate on, to allow method chaining. In ReScript, you can use ->ignore to discard the return value when it's not needed.