PassGram for developers

Build with PassGram.

Explore the Bot API format, keep tokens private, and follow service updates. The examples below describe the planned interface; they are not a live endpoint yet.

Bot API preview — service not enabled The cloud Bot API gateway is not currently deployed. These examples will return an error until that backend is published. Never place a bot token in client-side website code.

Create and manage a bot

/newbot
/mybots
/token
/revoke

Bot API request format

Planned method paths for bot integrations. Live calls are not available until the cloud gateway is deployed.

POST https://api.zpas.org/bot<TOKEN>/sendMessage

{
  "chat_id": "…",
  "text": "Hello"
}

Read the FAQ

Protect your token

Keep tokens on a trusted server. Do not commit them to source control, share them in chat, or embed them in a public website or mobile app.

Service status

The site is hosted on Firebase and does not depend on a PC being left on. Bot creation still needs the serverless gateway before it goes live.

Follow launch updates on X

Back to PassGram

Guide

Understand the API
before you build.

This page explains how PassGram bots are expected to work, how to keep them secure, and which parts exist today. We mark every planned feature as planned, so you can decide what to build on without surprises.

Authentication

Every bot receives a secret token when it is created. The token is part of the request path and identifies your bot. Treat it exactly like a password: store it in an environment variable or a secrets manager, never inside a web page, mobile app or public repository.

If a token leaks, revoke it and issue a new one immediately. Rotating a token invalidates the old one at once.

Requests and responses

Methods are called with HTTPS POST and a JSON body. Successful calls return a JSON object with an ok flag and a result, while failures return ok set to false together with an error code and a short human-readable description.

Rate limits

To keep the service fast for everyone, bots will be limited in how many messages they can send per second and per chat. When a limit is reached the response tells you how many seconds to wait, and well-behaved clients should back off instead of retrying immediately.

Webhooks and polling

You will be able to receive updates either by asking for them on a schedule or by giving us an HTTPS address to call. Webhooks are faster and use fewer resources, while polling is easier to test from a laptop.

Reference

Planned methods

The table lists the first methods we intend to offer. Names and fields may still change before the gateway is published.

Method	Purpose	Main fields
`getMe`	Returns basic information about your bot, useful for checking that a token works.	none
`sendMessage`	Sends a text message to a chat the bot is allowed to write in.	`chat_id`, `text`
`getUpdates`	Fetches new messages and events addressed to your bot.	`offset`, `limit`
`setWebhook`	Registers an HTTPS address that receives updates as they happen.	`url`

POST https://api.zpas.org/bot<TOKEN>/sendMessage Content-Type: application/json { "chat_id": "123456789", "text": "Hello from my bot" }

Best practice

Ship it safely.

Always call the API from a server you control. Browsers expose every line of script to the person using the page, so any token placed there can be copied in seconds. A small backend that holds the token and exposes only the actions your page needs is the safest pattern.

Validate everything that reaches your bot. Messages and webhook payloads are input from the outside world, so check their shape, limit their length and never run them as commands. Log failures without writing tokens into your logs.

Finally, be transparent with the people who talk to your bot. Say what it does, what it stores and how they can stop using it. Trust is the most valuable feature any integration can have.

Questions about the API?

Read the FAQ for the current status, or follow the project on X to hear when the gateway goes live.