Version: 4.x

Helpers

Proxy Methods

When dealing with updates, sometimes you may need to access data that is nested in the update structure, which can be tedious and produce a lot of boilerplate, since the same objects can often be nested in other objects, depending on the type of update. For this reason, the framework provides a number of support methods to quickly access the most used data, no matter the update type, like this:

use SergiX44\Nutgram\Nutgram;

$bot = new Nutgram($_ENV['TOKEN']);

$bot->onCommand('help', function (Nutgram $bot) {
    // Get the Message object
    $bot->message();

    // Access the Chat object
    $bot->chat();
});

$bot->onCommand('my_chat', function (Nutgram $bot) {
    $bot->sendMessage('Your chat id is ' . $bot->chatId());
});

$bot->run();

ID Methods

userId(): ?int
The current from.id if available, null otherwise.
chatId(): ?int
The current chat.id if available, null otherwise.
updateId(): ?int
The current update_id if available, null otherwise.
messageId(): ?int
The current message.message_id if available, null otherwise.
messageThreadId(): ?int
The current message.message_thread_id if available, null otherwise.
businessConnectionId(): ?string
The current message.business_connection_id if available, null otherwise.
inlineMessageId(): ?string
The current chosen_inline_result.inline_message_id ?? callback_query.inline_message_id if available, null otherwise.
directMessagesTopicId()(): ?int
The current message.direct_messages_topic.topic_id if available, null otherwise.
managedBotId()(): ?int
The current message.managed_bot_created.bot.id ?? update.managed_bot.bot.id if available, null otherwise.
guestQueryId()(): ?string
The current message.guest_query_id if available, null otherwise.
receiverUserId()(): ?int
The current message.receiver_user.id if available, null otherwise.
ephemeralMessageId()(): ?int
The current message.ephemeral_message_id if available, null otherwise.

Object Methods

update(): ?Update
The current Update object.
user(): ?User
The current User (from Telegram's object) if available, null otherwise.
chat(): ?Chat
The current Chat if available, null otherwise.
message(): ?Message
The current Message if available, null otherwise.
messageReaction(): ?MessageReactionUpdated
The current MessageReaction if available, null otherwise.
messageReactionCount(): ?MessageReactionCountUpdated
The current MessageReactionCountUpdated if available, null otherwise.
businessConnection(): ?BusinessConnection
The current BusinessConnection if available, null otherwise.
deletedBusinessMessages(): ?BusinessMessagesDeleted
The current BusinessMessagesDeleted if available, null otherwise.
inlineQuery(): ?InlineQuery
The current InlineQuery if available, null otherwise.
chosenInlineResult(): ?ChosenInlineResult
The current ChosenInlineResult if available, null otherwise.
callbackQuery(): ?CallbackQuery
The current CallbackQuery if available, null otherwise.
shippingQuery(): ?ShippingQuery
The current ShippingQuery if available, null otherwise.
preCheckoutQuery(): ?PreCheckoutQuery
The current PreCheckoutQuery if available, null otherwise.
purchasedPaidMedia(): ?PaidMediaPurchased
The current PaidMediaPurchased if available, null otherwise.
poll(): ?Poll
The current Poll if available, null otherwise.
pollAnswer(): ?PollAnswer
The current PollAnswer if available, null otherwise.
chatMember(): ?ChatMemberUpdated
The current ChatMemberUpdated if available, null otherwise.
chatJoinRequest(): ?ChatJoinRequest
The current ChatJoinRequest if available, null otherwise.
chatBoost(): ?ChatBoostUpdated
The current ChatBoostUpdated if available, null otherwise.
removedChatBoost(): ?ChatBoostRemoved
The current ChatBoostRemoved if available, null otherwise.
checklist(): ?Checklist
The current Checklist if available, null otherwise.
managedBot(): ?User
The current message.managed_bot_created.bot ?? update.managed_bot.bot if available, null otherwise.

Utility Methods

isCommand(): ?bool
True, if the current update is a command.
isInlineQuery(): ?bool
True, if the current update contains an inline_query.
isCallbackQuery(): ?bool
True, if the current update contains a callback_query.
isPreCheckoutQuery(): ?bool
True, if the current update contains a pre_checkout_query.
isMyChatMember(): ?bool
True, if the current ChatMemberUpdated is in the my_chat_member.
isDirectMessagesTopic(): bool
True, if the current update is a direct messages topic.
isSuggestedPost(): bool
True, if the current update is a suggested post.

Persisting Data

The framework gives you the ability to store data in 3 different scopes:

- Data that is available in all updates and users.
- Data that is available in the current update.
- Data that is available for the current user.

tip

If you need to persist data on disk, be sure to choose an appropriate cache adapter!

Global Scope

setGlobalData(): bool
Set a global data value.
getGlobalData(): mixed
Get a global data value.
deleteGlobalData(): bool
Delete a global data value.

Update Scope

set(): mixed
Set a data value for the current update.
get(): mixed
Get a data value for the current update.
delete(): bool
Delete a data value for the current update.
clear(): void
Clear all data for the current update.

User Scope

setUserData(): bool
Set a data value for the current user.
getUserData(): mixed
Get a data value for the current user.
deleteUserData(): bool
Delete a data value for the current user.

Deep Link Builder

Nutgram provides a simple way to create deep links to use in your bot.
You can use the deepLink() function to create a deep link to your bot:

Example:

use function SergiX44\Nutgram\Support\deepLink;

$userLink = deepLink()->username('FooUser'); // https://t.me/FooUser

Available Methods

username(): bool

Public username link

contact(): string

Temporary profile link

phone(): string

Phone number links

joinChat(): string

Chat invite links

addList(): string

Chat folder links

publicMessage(): string

Public message links

privateMessage(): string

Private message links

publicForumTopic(): string

Public forum topic links

privateForumTopic(): string

Private forum topic links

share(): string

Share links

videochat(): string

Video chat links

livestream(): string

Livestream links

addStickers(): string

Stickerset links

addEmoji(): string

Custom emojiset links

story(): string

Story links

publicBoost(): string

Public boost links

privateBoost(): string

Private boost links

proxyMTP(): string

MTProxy links

proxySocks5(): string

Socks5 proxy links

addTheme(): string

Theme links

wallpaperImage(): string

Image wallpapers

wallpaperSolidFill(): string

Solid fill wallpapers

wallpaperGradientFill(): string

Gradient fill wallpapers

wallpaperFreeformGradientFill(): string

Freeform gradient fill wallpapers

wallpaperSolidPattern(): string

Solid pattern wallpapers

wallpaperGradientPattern(): string

Gradient pattern wallpapers

wallpaperFreeformGradientPattern(): string

Freeform gradient pattern wallpapers

start(): string

Bot links

startGroup(): string

Group bot links

startChannel(): string

Channel bot links

game(): string

Game links

login(): string

invoice(): string

Invoice links

setLanguage(): string

Language pack links

confirmPhone(): string

Phone confirmation links

giftcode(): string

Premium giftcode links

startApp(): string

Mini App links

miniApp(): string

Direct mini app links

startAttach(): string

Bot attachment or side menu links

attach(): string

Bot attachment or side menu links

Constants

To make it easier to use the framework, we provide a number of constants that can be used in your code.

Limits

You can use the following constants to know the limits of the Telegram Bot API:

use SergiX44\Nutgram\Telegram\Limits;

// For the moment, bots can download files of up to 20MB in size.
echo Limits::DOWNLOAD; // 20971520

// Upload file limit in Byte. (50 MB)
echo Limits::UPLOAD; // 52428800

// Caption max characters length
echo Limits::CAPTION_LENGTH; // 1024

// Text max characters length
echo Limits::TEXT_LENGTH; // 4096

// Minimum period in seconds for which the location will be updated (1 minute)
echo Limits::MIN_LIVE_PERIOD; // 60

// Maximum period in seconds for which the location will be updated (24 hours)
echo Limits::MAX_LIVE_PERIOD; // 86400

// Maximum poll question length
echo Limits::POLL_QUESTION_LENGTH; // 300

// Callback data max length in bytes
echo Limits::CALLBACK_DATA_LENGTH; // 64

ReactionTypeEmoji

You can use the following constants to set the reaction type emoji:

Example:

use SergiX44\Nutgram\Nutgram;
use SergiX44\Nutgram\Telegram\Types\Reaction\ReactionTypeEmoji;

$bot = new Nutgram($_ENV['TOKEN']);

$bot->onMessage(function (Nutgram $bot) {
    $bot->setMessageReaction([
        new ReactionTypeEmoji(ReactionTypeType::THUMBS_UP), // 👍
    ]);
});

$bot->run();

Available constants:

use SergiX44\Nutgram\Telegram\Types\Reaction\ReactionTypeEmoji;

echo ReactionTypeEmoji::THUMBS_UP;                     // 👍
echo ReactionTypeEmoji::THUMBS_DOWN;                   // 👎
echo ReactionTypeEmoji::HEART;                         // ❤️
echo ReactionTypeEmoji::FIRE;                          // 🔥
echo ReactionTypeEmoji::SMILING_FACE_WITH_HEARTS;      // 🥰
echo ReactionTypeEmoji::APPLAUSE;                      // 👏
echo ReactionTypeEmoji::BEAMING_FACE;                  // 😁
echo ReactionTypeEmoji::THINKING_FACE;                 // 🤔
echo ReactionTypeEmoji::EXPLODING_HEAD;                // 🤯
echo ReactionTypeEmoji::SCREAMING_FACE;                // 😱
echo ReactionTypeEmoji::FACE_WITH_SYMBOLS_ON_MOUTH;    // 🤬
echo ReactionTypeEmoji::CRYING_FACE;                   // 😢
echo ReactionTypeEmoji::PARTY_POPPER;                  // 🎉
echo ReactionTypeEmoji::STAR_STRUCK;                   // 🤩
echo ReactionTypeEmoji::FACE_VOMITING;                 // 🤮
echo ReactionTypeEmoji::POO;                           // 💩
echo ReactionTypeEmoji::FOLDED_HANDS;                  // 🙏
echo ReactionTypeEmoji::OK_HAND;                       // 👌
echo ReactionTypeEmoji::DOVE;                          // 🕊️
echo ReactionTypeEmoji::CLOWN_FACE;                    // 🤡
echo ReactionTypeEmoji::YAWNING_FACE;                  // 🥱
echo ReactionTypeEmoji::WOOZY_FACE;                    // 🥴
echo ReactionTypeEmoji::SMILING_FACE_WITH_HEART_EYES;  // 😍
echo ReactionTypeEmoji::WHALE;                         // 🐳
echo ReactionTypeEmoji::FIRING_HEART;                  // ❤‍🔥
echo ReactionTypeEmoji::NEW_MOON_FACE;                 // 🌚
echo ReactionTypeEmoji::HOT_DOG;                       // 🌭
echo ReactionTypeEmoji::HUNDRED_POINTS;                // 💯
echo ReactionTypeEmoji::ROLLING_ON_THE_FLOOR_LAUGHING; // 🤣
echo ReactionTypeEmoji::HIGH_VOLTAGE;                  // ⚡
echo ReactionTypeEmoji::BANANA;                        // 🍌
echo ReactionTypeEmoji::TROPHY;                        // 🏆
echo ReactionTypeEmoji::BROKEN_HEART;                  // 💔
echo ReactionTypeEmoji::FACE_WITH_RAISED_EYEBROW;      // 🤨
echo ReactionTypeEmoji::NEUTRAL_FACE;                  // 😐
echo ReactionTypeEmoji::STRAWBERRY;                    // 🍓
echo ReactionTypeEmoji::CHAMPAGNE;                     // 🍾
echo ReactionTypeEmoji::KISS;                          // 💋
echo ReactionTypeEmoji::MIDDLE_FINGER;                 // 🖕
echo ReactionTypeEmoji::SMILING_FACE_WITH_HORNS;       // 😈
echo ReactionTypeEmoji::SLEEPING_FACE;                 // 😴
echo ReactionTypeEmoji::LOUDLY_CRYING_FACE;            // 😭
echo ReactionTypeEmoji::NERD_FACE;                     // 🤓
echo ReactionTypeEmoji::GHOST;                         // 👻
echo ReactionTypeEmoji::MAN_TECHNOLOGIST;              // 👨‍💻
echo ReactionTypeEmoji::EYES;                          // 👀
echo ReactionTypeEmoji::JACK_O_LANTERN;                // 🎃
echo ReactionTypeEmoji::SEE_NO_EVIL;                   // 🙈
echo ReactionTypeEmoji::SMILING_FACE_WITH_HALO;        // 😇
echo ReactionTypeEmoji::FEARFUL_FACE;                  // 😨
echo ReactionTypeEmoji::HANDSHAKE;                     // 🤝
echo ReactionTypeEmoji::WRITING_HAND;                  // ✍️
echo ReactionTypeEmoji::HUGGING_FACE;                  // 🤗
echo ReactionTypeEmoji::SALUTING_FACE;                 // 🫡
echo ReactionTypeEmoji::SANTA_CLAUS;                   // 🎅
echo ReactionTypeEmoji::CHRISTMAS_TREE;                // 🎄
echo ReactionTypeEmoji::SNOWMAN;                       // ⛄
echo ReactionTypeEmoji::NAIL_POLISH;                   // 💅
echo ReactionTypeEmoji::ZANY_FACE;                     // 🤪
echo ReactionTypeEmoji::MOAI;                          // 🗿
echo ReactionTypeEmoji::COOL;                          // 🆒
echo ReactionTypeEmoji::HEART_WITH_ARROW;              // 💘
echo ReactionTypeEmoji::HEAR_NO_EVIL;                  // 🙉
echo ReactionTypeEmoji::UNICORN;                       // 🦄
echo ReactionTypeEmoji::KISSING_FACE;                  // 😘
echo ReactionTypeEmoji::PILL;                          // 💊
echo ReactionTypeEmoji::SPEAK_NO_EVIL;                 // 🙊
echo ReactionTypeEmoji::SMILING_FACE_WITH_SUNGLASSES;  // 😎
echo ReactionTypeEmoji::ALIEN_MONSTER;                 // 👾
echo ReactionTypeEmoji::SHRUGGING_MAN;                 // 🤷‍♂
echo ReactionTypeEmoji::SHRUGGING_NEUTRAL;             // 🤷
echo ReactionTypeEmoji::SHRUGGING_WOMAN;               // 🤷‍♀
echo ReactionTypeEmoji::ENRAGED_FACE;                  // 😡

Web Validation

The framework provides a static method to validate webapp data for third-party use.
This method validateWebAppDataForThirdParty accepts as third parameter a publicKey string, which can be one of the following:

use SergiX44\Nutgram\Nutgram;

// Production (Nutgram::PUBLICKEY_PROD is the default value)
Nutgram::validateWebAppDataForThirdParty('botid', 'data', Nutgram::PUBLICKEY_PROD);

// Test environment
Nutgram::validateWebAppDataForThirdParty('botid', 'data', Nutgram::PUBLICKEY_TEST);

Enums

To avoid remembering the exact string values of the Telegram Bot API enums, you can use the provided enums in the framework.

Here is a list of enums you can find/use using Nutgram:

ParseMode

Available values

ParseMode::MARKDOWN
ParseMode::MARKDOWN_LEGACY
ParseMode::HTML

Usage example

use SergiX44\Nutgram\Nutgram;
use SergiX44\Nutgram\Telegram\Properties\ParseMode;

$bot = new Nutgram($_ENV['TOKEN']);

$bot->onCommand('start', function (Nutgram $bot) {
    $bot->sendMessage(
        text: '<b>Hello</b> world',
        parse_mode: ParseMode::HTML,
    );
});

$bot->run();

ChatAction

Available values

ChatAction::TYPING
ChatAction::UPLOAD_PHOTO
ChatAction::RECORD_VIDEO
ChatAction::UPLOAD_VIDEO
ChatAction::RECORD_VOICE
ChatAction::UPLOAD_VOICE
ChatAction::UPLOAD_DOCUMENT
ChatAction::CHOOSE_STICKER
ChatAction::FIND_LOCATION
ChatAction::RECORD_VIDEO_NOTE
ChatAction::UPLOAD_VIDEO_NOTE

Usage example

use SergiX44\Nutgram\Nutgram;
use SergiX44\Nutgram\Telegram\Properties\ParseMode;

$bot = new Nutgram($_ENV['TOKEN']);

$bot->onCommand('start', function (Nutgram $bot) {
    $bot->sendChatAction(action: ChatAction::TYPING);
});

$bot->run();

DiceEmoji

Available values

DiceEmoji::DICE
DiceEmoji::DART
DiceEmoji::BASKETBALL
DiceEmoji::FOOTBALL
DiceEmoji::SLOT
DiceEmoji::BOWLING

Usage example

use SergiX44\Nutgram\Nutgram;
use SergiX44\Nutgram\Telegram\Properties\ParseMode;

$bot = new Nutgram($_ENV['TOKEN']);

$bot->onCommand('start', function (Nutgram $bot) {
    $bot->sendDice(emoji: DiceEmoji::DICE);
});

$bot->run();

ForumIconColor

Available values

ForumIconColor::BLUE
ForumIconColor::YELLOW
ForumIconColor::PURPLE
ForumIconColor::GREEN
ForumIconColor::RED
ForumIconColor::ORANGE

Usage example

use SergiX44\Nutgram\Nutgram;
use SergiX44\Nutgram\Telegram\Properties\ParseMode;

$bot = new Nutgram($_ENV['TOKEN']);

$bot->onCommand('create', function (Nutgram $bot) {
    $bot->createForumTopic(
        name: 'My Topic',
        icon_color: ForumIconColor::BLUE,
    );
});

$bot->run();

MaskPositionPoint

Available values

MaskPositionPoint::FOREHEAD
MaskPositionPoint::EYES
MaskPositionPoint::MOUTH
MaskPositionPoint::CHIN

Usage example

use SergiX44\Nutgram\Nutgram;
use SergiX44\Nutgram\Telegram\Properties\ParseMode;

$bot = new Nutgram($_ENV['TOKEN']);

$bot->onCommand('edit', function (Nutgram $bot) {
    $bot->setStickerMaskPosition(
        sticker: 'sticker_id',
        mask_position: new MaskPosition(
            point: MaskPositionPoint::FOREHEAD,
            x_shift: 0.5,
            y_shift: 0.5,
            scale: 1.0,
        ),
    );
});

$bot->run();

StickerType

Available values

StickerType::REGULAR
StickerType::MASK
StickerType::CUSTOM_EMOJI

Usage example

use SergiX44\Nutgram\Nutgram;
use SergiX44\Nutgram\Telegram\Properties\ParseMode;

$bot = new Nutgram($_ENV['TOKEN']);

$bot->onCommand('create', function (Nutgram $bot) {
    $bot->createNewStickerSet(
        name: 'my_sticker_pack',
        title: 'MyStickerPack',
        stickers: [
            // ...
        ],
        sticker_type: StickerType::REGULAR,
    );
});

$bot->run();

StickerFormat

Available values

StickerFormat::STATIC
StickerFormat::ANIMATED
StickerFormat::VIDEO

Usage example

use SergiX44\Nutgram\Nutgram;
use SergiX44\Nutgram\Telegram\Properties\ParseMode;

$bot = new Nutgram($_ENV['TOKEN']);

$bot->onCommand('create', function (Nutgram $bot) {
    $bot->uploadStickerFile(
        sticker: 'sticker_id',
        sticker_format: StickerFormat::STATIC,
    );
});

$bot->run();

Other Enums

For a complete list of enums, you can check the Properties folder in the source code.

Helpers

Proxy Methods​

ID Methods​

Object Methods​

Utility Methods​

Persisting Data​

Global Scope​

Update Scope​

User Scope​

Deep Link Builder​

Available Methods​

Constants​

Limits​

ReactionTypeEmoji​

Web Validation​

Enums​

ParseMode​

ChatAction​

DiceEmoji​

ForumIconColor​

MaskPositionPoint​

StickerType​

StickerFormat​

Other Enums​

Proxy Methods

ID Methods

Object Methods

Utility Methods

Persisting Data

Global Scope

Update Scope

User Scope

Deep Link Builder

Available Methods

Constants

Limits

ReactionTypeEmoji

Web Validation

Enums

ParseMode

ChatAction

DiceEmoji

ForumIconColor

MaskPositionPoint

StickerType

StickerFormat

Other Enums