initdata

README

init-data-golang

Package which provides utilities to work with Telegram Web Apps init data. To learn more, what init data is, visit its documentation.

Installation

go get github.com/telegram-web-apps/init-data-golang

Documentation

You can find full package documentation here.

Documentation

Index

• Variables
• func Sign(payload map[string]string, key string, authDate time.Time) string
• func SignQueryString(qs, key string, authDate time.Time) (string, error)
• func Validate(initData, token string, expIn time.Duration) error
• type Chat
• type ChatType
• type InitData
  • func Parse(initData string) (*InitData, error)
  • func (d *InitData) AuthDate() time.Time
  • func (d *InitData) CanSendAfter() time.Time
• type User

Variables

var (
	ErrAuthDateMissing  = errors.New("auth_date is missing")
	ErrSignMissing      = errors.New("sign is missing")
	ErrSignInvalid      = errors.New("sign is invalid")
	ErrUnexpectedFormat = errors.New("init data has unexpected format")
	ErrExpired          = errors.New("init data is expired")
)

Functions

func Sign

func Sign(payload map[string]string, key string, authDate time.Time) string

Sign signs passed payload using specified key. Function removes such technical parameters as "hash" and "auth_date".

func SignQueryString

func SignQueryString(qs, key string, authDate time.Time) (string, error)

SignQueryString signs passed query string.

func Validate

func Validate(initData, token string, expIn time.Duration) error

Validate validates passed init data. This method expects initData to be passed in the exact raw format as it could be found in window.Telegram.WebApp.initData. Returns true in case init data is signed correctly, and it is allowed to trust it.

Current code is implementation of algorithmic code described in official docs: https://core.telegram.org/bots/webapps#validating-data-received-via-the-web-app

initData - init data passed from application; token - TWA bot secret token which was used to create init data; expIn - maximum init data lifetime. It is strongly recommended to use this parameter. In case, exp duration is less than or equal to 0, function does not check if parameters are expired.

Types

type Chat

type Chat struct {
	// Unique identifier for this chat.
	ID int64 `json:"id"`

	// Optional. URL of the chat’s photo. The photo can be in .jpeg or .svg
	// formats. Only returned for Web Apps launched from the attachment menu.
	PhotoURL string `json:"photo_url"`

	// Type of chat.
	Type ChatType `json:"type"`

	// Title of the chat.
	Title string `json:"title"`

	// Optional. Username of the chat.
	Username string `json:"username"`
}

Chat describes chat information: https://core.telegram.org/bots/webapps#webappchat

type ChatType

type ChatType = string

ChatType describes type of chat.

const (
	ChatTypeGroup      ChatType = "group"
	ChatTypeSupergroup ChatType = "supergroup"
	ChatTypeChannel    ChatType = "channel"
)

type InitData

type InitData struct {
	// Init data generation date.
	AuthDateRaw int `json:"auth_date"`

	// Optional. Time in seconds, after which a message can be sent via the
	// `answerWebAppQuery` method.
	//
	// See: https://core.telegram.org/bots/api#answerwebappquery
	CanSendAfterRaw int `json:"can_send_after"`

	// An object containing data about the chat where the bot was
	// launched via the attachment menu. Returned for supergroups, channels
	// and group chats – only for Web Apps launched via the attachment menu.
	Chat *Chat `json:"chat"`

	// A hash of all passed parameters, which the bot server can use to
	// check their validity.
	//
	// See: https://core.telegram.org/bots/webapps#validating-data-received-via-the-web-app
	Hash string `json:"hash"`

	// A unique identifier for the Web App session, required for sending
	// messages via the answerWebAppQuery method.
	//
	// See: https://core.telegram.org/bots/api#answerwebappquery
	QueryID string `json:"query_id"`

	// An object containing data about the chat partner of the current user in
	// the chat where the bot was launched via the attachment menu.
	// Returned only for private chats and only for Web Apps launched
	// via the attachment menu.
	Receiver *User `json:"receiver"`

	// Optional. The value of the `startattach` parameter, passed via link. Only
	// returned for Web Apps when launched from the attachment menu via link.
	StartParam string `json:"start_param"`

	// An object containing data about the current user.
	User *User `json:"user"`
}

InitData describes parsed initial data sent from TWA application. You can find specification for all the parameters in the official documentation: https://core.telegram.org/bots/webapps#webappinitdata

func Parse

func Parse(initData string) (*InitData, error)

Parse converts passed init data presented as query string to InitData object.

func (*InitData) AuthDate

func (d *InitData) AuthDate() time.Time

AuthDate returns AuthDateRaw as time.Time.

func (*InitData) CanSendAfter

func (d *InitData) CanSendAfter() time.Time

CanSendAfter returns computed time which depends on CanSendAfterRaw and AuthDate. Originally, CanSendAfterRaw means time in seconds, after which `answerWebAppQuery` method can be called and that's why this value could be computed as time.

type User

type User struct {
	// First name of the user or bot.
	FirstName string `json:"first_name"`

	// A unique identifier for the user or bot.
	ID int64 `json:"id"`

	// Optional. True, if this user is a bot. Returned in the `receiver` field
	// only.
	IsBot bool `json:"is_bot"`

	// Optional. True, if this user is a Telegram Premium user.
	IsPremium bool `json:"is_premium"`

	// Optional. Last name of the user or bot.
	LastName string `json:"last_name"`

	// Optional. Username of the user or bot.
	Username string `json:"username"`

	// Optional. IETF language tag of the user's language. Returns in user
	// field only.
	//
	// See: https://en.wikipedia.org/wiki/IETF_language_tag
	// TODO: Specify expected values.
	LanguageCode string `json:"language_code"`

	// Optional. URL of the user’s profile photo. The photo can be in .jpeg or
	// .svg formats. Only returned for Web Apps launched from the
	// attachment menu.
	PhotoURL string `json:"photo_url"`
}

User describes user information: https://core.telegram.org/bots/webapps#webappuser