Telegram bot monetization API

curl -X POST https://hiviews.net/sendMessage \
  -H "Authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "UserId": 123456789,
    "MessageId": 45,
    "UserFirstName": "Ivan",
    "StartPlace": true
  }'

import asyncio
import logging

import httpx
from aiogram import Bot, Dispatcher, F, Router
from aiogram.filters import CommandStart
from aiogram.types import Message

HIVIEWS_URL = "https://hiviews.net/sendMessage"
HIVIEWS_KEY = "<API_KEY>"

router = Router()
router.message.filter(F.chat.type == "private")  # private chats only
http = httpx.AsyncClient(timeout=5.0)


async def show_ad(message: Message, start_place: bool) -> None:
    # On success the API replies after ~2 s: that is the reading window for the ad.
    try:
        resp = await http.post(
            HIVIEWS_URL,
            headers={"Authorization": HIVIEWS_KEY},
            json={
                "UserId": message.from_user.id,
                "MessageId": message.message_id,
                "UserFirstName": message.from_user.first_name,
                "StartPlace": start_place,
            },
        )
        # "No posts found" means no matching ad right now; this is normal
        if resp.status_code != 200 and resp.text != "No posts found for this user":
            logging.warning("HiViews: %s %s", resp.status_code, resp.text)
    except httpx.HTTPError as e:
        logging.warning("HiViews request failed: %s", e)


@router.message(CommandStart())
async def on_start(message: Message) -> None:
    await show_ad(message, start_place=True)  # first line, wait for the reply
    await message.answer("Hi! How can I help?")          # then your own greeting


async def main() -> None:
    bot = Bot("<BOT_TOKEN>")
    dp = Dispatcher()
    dp.include_router(router)
    try:
        await dp.start_polling(bot)
    finally:
        await http.aclose()


if __name__ == "__main__":
    asyncio.run(main())

import logging

import requests

HIVIEWS_URL = "https://hiviews.net/sendMessage"
HIVIEWS_KEY = "<API_KEY>"


def show_ad(user_id: int, message_id: int, first_name: str | None,
            start_place: bool = True) -> None:
    # On success the API replies after ~2 s: that is the reading window for the ad.
    try:
        resp = requests.post(
            HIVIEWS_URL,
            headers={"Authorization": HIVIEWS_KEY},
            json={
                "UserId": user_id,
                "MessageId": message_id,
                "UserFirstName": first_name,
                "StartPlace": start_place,
            },
            timeout=5,
        )
        if resp.status_code != 200 and resp.text != "No posts found for this user":
            logging.warning("HiViews: %s %s", resp.status_code, resp.text)
    except requests.RequestException as e:
        logging.warning("HiViews request failed: %s", e)


# in your /start handler (private chat), as the first line, awaiting the reply:
# show_ad(user.id, message.message_id, user.first_name, start_place=True)
# send_greeting(user.id)  # then your own greeting

// Node.js 18+ (built-in fetch)
const HIVIEWS_URL = "https://hiviews.net/sendMessage";
const HIVIEWS_KEY = process.env.HIVIEWS_KEY; // <API_KEY>

// On success the API replies after ~2 s: that is the reading window for the ad.
async function showAd({ userId, messageId, firstName = null, startPlace = true }) {
  try {
    const res = await fetch(HIVIEWS_URL, {
      method: "POST",
      headers: { "Authorization": HIVIEWS_KEY, "Content-Type": "application/json" },
      body: JSON.stringify({
        UserId: userId,
        MessageId: messageId,
        UserFirstName: firstName,
        StartPlace: startPlace,
      }),
      signal: AbortSignal.timeout(5000),
    });
    const text = await res.text();
    if (res.status !== 200 && text !== "No posts found for this user") {
      console.warn("HiViews:", res.status, text);
    }
  } catch (err) {
    console.warn("HiViews request failed:", err.message);
  }
}

// in your /start handler (private chat), as the first line, awaiting the reply:
// await showAd({ userId: ctx.from.id, messageId: ctx.message.message_id,
//                firstName: ctx.from.first_name, startPlace: true });
// await ctx.reply("Hi! How can I help?"); // then your own greeting

<?php
const HIVIEWS_KEY = '<API_KEY>';

// On success the API replies after ~2 s: that is the reading window for the ad.
function hiviews_show_ad(int $userId, int $messageId, ?string $firstName, bool $startPlace = true): void
{
    $ch = curl_init('https://hiviews.net/sendMessage');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: ' . HIVIEWS_KEY,
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'UserId' => $userId,
            'MessageId' => $messageId,
            'UserFirstName' => $firstName,
            'StartPlace' => $startPlace,
        ]),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 5,
    ]);
    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($code !== 200 && $body !== 'No posts found for this user') {
        error_log("HiViews: $code $body");
    }
}

// in your /start handler (private chat), as the first line, awaiting the reply:
// $msg = $update['message'];
// hiviews_show_ad($msg['from']['id'], $msg['message_id'], $msg['from']['first_name'] ?? null, true);
// send_greeting($msg['chat']['id']); // then your own greeting

import asyncio, aiohttp
from aiogram import Bot
from aiogram.types import InlineKeyboardMarkup

HIVIEWS_KEY = "YOUR_API_KEY"

async def show_ad(bot: Bot, user, start: bool = False) -> None:
    payload = {"UserId": user.id, "UserFirstName": user.first_name, "Username": user.username,
               "Language": user.language_code, "StartPlace": start}
    try:
        async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=5)) as s:
            async with s.post("https://hiviews.net/api/partner/ad", json=payload,
                              headers={"Authorization": HIVIEWS_KEY}) as r:
                ad = (await r.json()).get("ad")
        if not ad:
            return
        kw = {"parse_mode": "HTML", "reply_markup": InlineKeyboardMarkup.model_validate(ad["reply_markup"])}
        if ad.get("photo"):
            msg = await bot.send_photo(user.id, ad["photo"], caption=ad["text"], **kw)
        elif ad.get("video"):
            msg = await bot.send_video(user.id, ad["video"], caption=ad["text"], **kw)
        elif ad.get("animation"):
            msg = await bot.send_animation(user.id, ad["animation"], caption=ad["text"], **kw)
        else:
            msg = await bot.send_message(user.id, ad["text"], **kw)  # keep link previews on
        if ad.get("delete_after"):
            asyncio.get_running_loop().call_later(
                ad["delete_after"], lambda: asyncio.ensure_future(quiet_delete(bot, user.id, msg.message_id)))
    except Exception:
        pass

async def quiet_delete(bot: Bot, chat_id: int, message_id: int) -> None:
    try:
        await bot.delete_message(chat_id, message_id)
    except Exception:
        pass

// HiViews without a token: the bot sends the ad itself, paid for confirmed impressions and clicks. Node.js 18+, Telegraf.
// Send the post as is: Telegram confirms the delivery to us through the hidden link in the text.
const HIVIEWS_KEY = "YOUR_API_KEY";

async function showAd(ctx, start = false) {
  // Call showAd(ctx, true) on /start and showAd(ctx, false) after delivering the result.
  try {
    const u = ctx.from;
    const res = await fetch("https://hiviews.net/api/partner/ad", {
      method: "POST",
      headers: { Authorization: HIVIEWS_KEY, "Content-Type": "application/json" },
      body: JSON.stringify({ UserId: u.id, UserFirstName: u.first_name, Username: u.username,
                             Language: u.language_code, StartPlace: start }),
      signal: AbortSignal.timeout(5000),
    });
    const { ad } = await res.json();
    if (!ad) return; // no ad for this person right now
    const extra = { parse_mode: "HTML", reply_markup: ad.reply_markup };
    let msg;
    if (ad.photo) msg = await ctx.telegram.sendPhoto(u.id, ad.photo, { caption: ad.text, ...extra });
    else if (ad.video) msg = await ctx.telegram.sendVideo(u.id, ad.video, { caption: ad.text, ...extra });
    else if (ad.animation) msg = await ctx.telegram.sendAnimation(u.id, ad.animation, { caption: ad.text, ...extra });
    else msg = await ctx.telegram.sendMessage(u.id, ad.text, extra); // keep link previews on
    if (ad.delete_after) {
      setTimeout(() => ctx.telegram.deleteMessage(u.id, msg.message_id).catch(() => {}), ad.delete_after * 1000);
    }
  } catch (e) { /* an ad must never break the bot */ }
}

// Example:  bot.start(async (ctx) => { await showAd(ctx, true); /* your greeting */ });

<?php
// HiViews without a token: the bot sends the ad itself, paid for confirmed impressions and clicks.
// Send the post as is: Telegram confirms the delivery to us through the hidden link in the text.
const HIVIEWS_KEY = 'YOUR_API_KEY';

/** $user is the `from` array of the Telegram update. On /start: $start = true, after the result: false.
 *  Returns [message_id, delete_after]: if delete_after is not null, delete the message after that many seconds. */
function hiviews_show_ad(string $botToken, array $user, bool $start = false): ?array
{
    $ch = curl_init('https://hiviews.net/api/partner/ad');
    curl_setopt_array($ch, [
        CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 5,
        CURLOPT_HTTPHEADER => ['Authorization: ' . HIVIEWS_KEY, 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode([
            'UserId' => $user['id'], 'UserFirstName' => $user['first_name'] ?? '',
            'Username' => $user['username'] ?? null, 'Language' => $user['language_code'] ?? null,
            'StartPlace' => $start,
        ]),
    ]);
    $ad = json_decode((string) curl_exec($ch), true)['ad'] ?? null;
    curl_close($ch);
    if (!$ad) {
        return null; // no ad for this person right now
    }
    $params = ['chat_id' => $user['id'], 'parse_mode' => 'HTML', 'reply_markup' => json_encode($ad['reply_markup'])];
    if (!empty($ad['photo'])) {
        $method = 'sendPhoto'; $params += ['photo' => $ad['photo'], 'caption' => $ad['text']];
    } elseif (!empty($ad['video'])) {
        $method = 'sendVideo'; $params += ['video' => $ad['video'], 'caption' => $ad['text']];
    } elseif (!empty($ad['animation'])) {
        $method = 'sendAnimation'; $params += ['animation' => $ad['animation'], 'caption' => $ad['text']];
    } else {
        $method = 'sendMessage'; $params += ['text' => $ad['text']]; // keep link previews on
    }
    $ch = curl_init('https://api.telegram.org/bot' . $botToken . '/' . $method);
    curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10,
                            CURLOPT_POSTFIELDS => $params]);
    $sent = json_decode((string) curl_exec($ch), true);
    curl_close($ch);
    return [$sent['result']['message_id'] ?? null, $ad['delete_after'] ?? null];
}

// Example:  hiviews_show_ad($botToken, $update['message']['from'], true);   // in the /start handler