Tasks API

The Tasks API lets your bot show MGRAM tasks to its users itself — join a channel, enter a chat, start a bot — and earn for every completion. It's the same monetization as mandatory subscriptions, but you choose the interface and the moment.

What you need

• A bot connected to MGRAM.
• A Bot API key: “My bots” → your bot → “Settings” → “API key”. Bots connected without a token received the key at connection.
• Your bot's server that can make HTTPS requests with JSON.

How it works

1. Get tasks. When a user writes to your bot, call POST /tasks with their user_id. The response contains a list of tasks: title, link, button text, and the amount you'll earn for completion.
2. Show tasks as buttons. The link and button text are already in the response. By default you get 3 tasks; you can request 1 to 10.
3. Learn about completion. Either call POST /tasks/check on a “Check” button, or set up a webhook — MGRAM sends an event to your server when the user completes a task or unsubscribes.
4. Let the user continue. When the response has skip: true, everything is done — continue your bot's flow.

Example request

POST https://api.mgram.biz/tasks with the header Authorization: Bearer YOUR_BOT_API_KEY and the body {"user_id": 123456789}.

The response contains status, skip, and a tasks array where each task has a title, link, button_text, and reward.

How much you earn

• For a channel subscription or chat join — 70% of the task price. If the user leaves within 24 hours, the income for that subscription is taken back.
• For a bot launch — 70% of the price; it is never taken back.
• The API response shows how much has been earned and how much is still being verified.

Webhook

POST /tasks/webhook with your url turns on event delivery to your server. Each event is signed: verify the X-MGRAM-Signature header — an HMAC-SHA256 of timestamp.request_body with the secret from the response. Reply with 200 or 204. An empty url turns the webhook off.

Bots without a token

Bots connected earlier without a token work only through the Tasks API:

• joins via links from the API response are counted;
• bot launch tasks are not issued to them;
• no more than 30 new users per minute are counted.

To open broadcasts, Reply Ads, and mandatory subscriptions for such a bot, add its token in the bot card.

Rules

• Show tasks only to real users who are using the bot right now.
• Don't replace links from the API response — otherwise completions won't count.
• Actions of farms and fake accounts are not paid, and a bot with signs of fake activity can be stopped.