Core Concepts

This page covers the things that apply to every endpoint. Read it once and everything else gets a lot easier.

Base URL

Every endpoint lives under:

https://api-zate.azickri.com

Requests and responses are JSON. For endpoints with a body, remember to send the Content-Type: application/json header.

Sessions: id + session-id

Zate doesn't use API keys or tokens. Instead, every logged-in Telegram account has one session, identified by two values you get from Create Session:

Header	Value	Example
id	id from Create Session	68b3f0a2c1d4e5f6a7b8c9d0
session-id	sessionId from Create Session	0b2f7059-8a90-4f6d-8684-b0e1ce6f0310

Every endpoint except POST /session and media links requires both headers:

curl "https://api-zate.azickri.com/group" \
  -H "id: 68b3f0a2c1d4e5f6a7b8c9d0" \
  -H "session-id: 0b2f7059-8a90-4f6d-8684-b0e1ce6f0310"

Treat them like a password

Anyone holding your id and session-id can send messages from your Telegram account, read your groups and channels, and redirect your webhook. Keep them on your server, never in a frontend or mobile app.

One session = one Telegram login. In Telegram, a Zate session shows up as a device named Zate under Settings → Devices. To use several accounts, create several sessions.

Session Lifecycle

A session is "alive": it connects, drops, reconnects, and is eventually deleted. Here's what happens in each case:

Situation	What happens
Just created	isConnected: false. A few seconds later qrcode is filled in, and it changes roughly every 30 seconds.
QR not scanned within 3 minutes	The session is deleted automatically. The next request gets 404 session not found.
QR scanned	isConnected: true, qrcode empty, name, username, phone, and picture filled in.
QR scanned, account uses two-step verification	qrcode empty, isPasswordRequired: true. Send the password with Submit Password.
Connection drops briefly	Zate reconnects on its own with growing delays (0 s, 2 s, 4 s, and so on, up to 30 s).
You remove the Zate device from Telegram	Noticed within about 30 seconds. The login is cleared and Zate prepares a new QR right away, with the same 3-minute limit.
Disconnected for more than 30 minutes	The session is deleted automatically, including all its data. This also applies to sessions that never get their password.
You call Reset Session	The Zate device is logged out of Telegram and Zate prepares a new QR.
You call Delete Session	The Zate device is logged out of Telegram and all session data is deleted.

Keep an eye on the connection

Get Session is safe to call any time, even while the session is down. Check isConnected periodically (say, every few minutes) so you know when to scan again, before the 30 minutes run out.

Receivers

Send Message and Send Typing need a receiver. Fill in one of these fields:

Field	Value	Example	Where to get it
group	Group ID, or a public group's username	-1001234567890	Get Groups
channel	Channel ID, or a public channel's username	-1001234567890	Get Channels
user	Telegram user ID	123456789	Get Group Members, or chatId in the webhook
username	Username, with or without @, or a t.me link	@azickri	The recipient's Telegram profile
phone	Phone number in international format	6281234567890	The recipient's number

If you fill in more than one, they're used in this order: group, channel, user, username, then phone. You can only send to a channel you manage, and Send Typing doesn't accept channel.

Telegram IDs

Telegram IDs are numbers, and the prefix tells you what kind of chat it is:

Shape	Kind
123456789	User
-123456789	Basic group
-1001234567890	Supergroup or channel

An ID only works if your account already "knows" the chat: it's in your chat list, or the person just showed up in Get Group Members. If you get 400 chat not found, use a username, or call Get Group Members for their group first.

Usernames

A username can be written as azickri, @azickri, t.me/azickri, or https://t.me/azickri. Zate strips the prefix for you. If the format isn't valid (for example it has a space or doesn't start with a letter), you get 400 invalid chat.

Phone Numbers

To keep things easy, Zate tidies up the number you send, just like Zawa:

• Anything that isn't a digit is removed, so +62 812-3456-7890 still works.
• A leading 0 is replaced with 62, so 081234567890 becomes 6281234567890.
• After tidying, the number must have at least 8 digits. Otherwise you get 400 invalid receiver.

Phone numbers don't always work

Unlike WhatsApp, Telegram lets people hide from phone number lookups (Settings → Privacy and Security → Phone Number → Who can find me by my number). If the number isn't on Telegram or is hidden, you get 400 phone is not on telegram or hidden by its privacy settings. A username or user ID is always more reliable.

Text Formatting

By default, text is sent as is. Characters like * and _ aren't turned into any formatting. For bold, italic, or links, set parseMode:

parseMode	Supported	Example
(empty)	Plain text	Hello *everyone* shows exactly like that
markdown	**bold**, __italic__, ~~strike~~, `code`, ```code block```	Hello **everyone**
html	<b>, <i>, <u>, <s>, <code>, <pre>, <a href>, <blockquote>, <spoiler>	Hello <b>everyone</b>, <a href="https://zate.azickri.com">Zate</a>

Telegram's markdown is not regular Markdown: for example, *single asterisks* don't make italics. For links, underline, spoilers, or quotes, use html. parseMode also applies to image, video, and document captions.

Sending Media from a URL

Zate doesn't accept file uploads. You just pass a URL, and Zate downloads the file and sends it to Telegram. To keep things smooth:

• The URL must be public and point straight at the file, reachable without logging in. Preview pages (like a Google Drive share page) won't work.
• Images are re-encoded as JPEG. Zate shrinks them so the longest side is at most 2560 pixels, to stay within Telegram's photo limits.
• Videos are sent as streamable MP4. Their size and duration are read from the file itself. thumbnail is optional: if it's empty, Zate uses the first frame of the video.
• Audio is sent as a regular audio file, not a voice note. The file name in the URL becomes its title when the file has no tags.
• Documents show the name from name, and its extension decides the file type in Telegram. So make sure name has an extension, like invoice.pdf.
• mimetype is still required, like image/jpeg, video/mp4, audio/mpeg, or application/pdf, so the request matches Zawa exactly.

There are also time limits:

Limit	Value
File server must start sending data	60 seconds
Stalled download (no data coming in)	30 seconds
Video thumbnail download	30 seconds
Total time to send one message or story	4 minutes
JSON body size	25 MB

Public Media Links

Telegram media has no public URL. To keep it easy to use, every media file Zate hands you, from Get Channel Messages or from the webhook, is a link to Get Media:

https://api-zate.azickri.com/media/68b3f0a2c1d4e5f6a7b8c9d0/-1001234567890/100/photo/Xk3d9QmPz0aB1cD2eF3gH4.jpg

The link opens without headers, works directly in <img> or <video>, and is streamed from Telegram bit by bit. The details are in Get Media.

Unlike media, the picture of a session, group, or channel comes as a data URI (data:image/jpeg;base64,...), so you can use it without another request.

Response Format

On success you get status 200 with a JSON object. Endpoints that return a list always wrap it in docs:

{
  "docs": [
    { "id": "-1001234567890", "name": "Zate Community" }
  ]
}

On failure, the shape is always the same:

{
  "statusCode": 400,
  "message": "invalid header"
}

If several fields are wrong at once, the messages are joined with newlines (\n) in message. Errors coming straight from Telegram are passed along in the format code: ERROR_NAME (caused by ...). The full list of errors and how to fix them is in Errors & Fixes.

Other Limits to Keep in Mind

• The typing indicator from Send Typing only shows for 5 seconds.
• Get Channel Messages returns 100 messages per page.
• Get Group Members returns at most 10,000 members.
• created for groups and channels is the date your account joined, not the date the group or channel was created. Telegram only gives the creation date to non-members.
• Group descriptions are cached for 5 minutes, so a changed description can take a while to show up.
• Free Telegram accounts have a daily story limit. Once it's reached, Telegram rejects further stories.