Send Message

POST /message

Zate's workhorse. Send a message to a username, user, group, channel, or phone number, in seven types: text, image, video, audio, document, location, and contact. Each type needs different fields, so check the tables below.

Endpoint Details

• Base URL: https://api-zate.azickri.com
• Headers: id, session-id, and Content-Type: application/json
• Requirement: the session must be connected (isConnected: true)

Headers

Header	Type	Required	Description
id	string	Yes	id from Create Session.
session-id	string	Yes	sessionId from Create Session.

Request Body

Field	Type	Required	Description
group	string	One of*	Group ID, like -1001234567890, or a public group's username.
channel	string	One of*	Channel ID, like -1001234567890, or a public channel's username. Your account must be allowed to post there.
user	string	One of*	Telegram user ID, like 123456789.
username	string	One of*	Recipient username: azickri, @azickri, or t.me/azickri.
phone	string	One of*	Phone number in international format, like 6281234567890. Only works if the person's privacy allows it.
type	string	Yes	Message type: text, image, video, audio, document, location, or contact.
text	string	For text	Message text. For image, video, and document, it becomes the caption (optional).
parseMode	string	No	markdown or html to format the text and caption. Leave it empty to send as is. See Text Formatting.
image	object	For image	See the image object.
video	object	For video	See the video object.
audio	object	For audio	See the audio object.
document	object	For document	See the document object.
location	object	For location	See the location object.
contact	object	For contact	See the contact object.

* Fill in one of group, channel, user, username, or phone. If more than one is filled in, they're used in this order: group, channel, user, username, then phone. The full explanation is in Receivers.

Media Objects

Media is sent by URL. Zate downloads the file, so the URL must be public and point straight at the file. See also Sending Media from a URL.

Object	Field	Type	Required	Description
image	url	string	Yes	Image URL. Re-encoded as JPEG, at most 2560 pixels.
	mimetype	string	Yes	For example image/jpeg.
	thumbnail	string	No	Not used for images. Telegram makes its own thumbnail.
video	url	string	Yes	Video URL. MP4 is the safest choice.
	mimetype	string	Yes	For example video/mp4.
	duration	number	Yes	Video length in seconds, greater than 0. If the file's real duration can be read, that one is used.
	thumbnail	string	No	Thumbnail image URL. If empty, Zate uses the video's first frame.
audio	url	string	Yes	Audio URL. MP3 is the safest choice.
	mimetype	string	Yes	For example audio/mpeg.
	duration	number	Yes	Audio length in seconds, greater than 0.
document	url	string	Yes	Document URL.
	name	string	Yes	File name shown in the chat, like invoice.pdf. Its extension decides the file type in Telegram.
	size	number	Yes	File size in bytes, greater than 0.
	mimetype	string	Yes	For example application/pdf.

Audio isn't a voice note

Audio is sent as a regular audio file that plays in Telegram's music player, not as a voice note. Audio can't have a caption either, so text is ignored.

Location and Contact Objects

Object	Field	Type	Required	Description
location	latitude	number	Yes	Latitude, must not be 0.
	longitude	number	Yes	Longitude, must not be 0.
	name	string	No	Place name, like Monas.
	address	string	No	Place address.
contact	name	string	Yes	Name of the shared contact.
	phone	string	Yes	Contact's phone number, like 6281234567890.

If name or address is filled in, the location is sent as a venue with its name and address. If both are empty, it's sent as a plain map pin.

Example Request

The simplest case: a text message to one username.

cURL

curl -X POST "https://api-zate.azickri.com/message" \
  -H "id: YOUR_ID" \
  -H "session-id: YOUR_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"username":"@azickri","type":"text","text":"Hello from Zate! 👋"}'

Axios

import axios from 'axios';

const response = await axios.post(
  'https://api-zate.azickri.com/message',
  {
    username: '@azickri',
    type: 'text',
    text: 'Hello from Zate! 👋',
  },
  {
    headers: {
      'id': 'YOUR_ID',
      'session-id': 'YOUR_SESSION_ID',
    },
  },
);

console.log(response.data);

Fetch

const response = await fetch('https://api-zate.azickri.com/message', {
  method: 'POST',
  headers: {
    'id': 'YOUR_ID',
    'session-id': 'YOUR_SESSION_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    username: '@azickri',
    type: 'text',
    text: 'Hello from Zate! 👋',
  }),
});

const data = await response.json();
console.log(data);

Example Body per Type

Swap the body in the example request above for one of these.

text

{
  "username": "@azickri",
  "type": "text",
  "text": "Hello from Zate! 👋"
}

text + format

{
  "username": "@azickri",
  "type": "text",
  "parseMode": "html",
  "text": "Order <b>#1024</b> is ready! Check it <a href=\"https://zate.azickri.com\">here</a> 🍢"
}

image

{
  "username": "@azickri",
  "type": "image",
  "text": "This is the caption, optional",
  "image": {
    "url": "https://example.com/image.jpg",
    "mimetype": "image/jpeg"
  }
}

video

{
  "username": "@azickri",
  "type": "video",
  "text": "Video caption",
  "video": {
    "url": "https://example.com/video.mp4",
    "mimetype": "video/mp4",
    "duration": 30,
    "thumbnail": "https://example.com/video-thumbnail.jpg"
  }
}

audio

{
  "username": "@azickri",
  "type": "audio",
  "audio": {
    "url": "https://example.com/audio.mp3",
    "mimetype": "audio/mpeg",
    "duration": 30
  }
}

document

{
  "username": "@azickri",
  "type": "document",
  "text": "This month's invoice",
  "document": {
    "url": "https://example.com/invoice.pdf",
    "name": "invoice.pdf",
    "size": 102400,
    "mimetype": "application/pdf"
  }
}

location

{
  "username": "@azickri",
  "type": "location",
  "location": {
    "name": "Monas",
    "address": "Gambir, Central Jakarta",
    "latitude": -6.175392,
    "longitude": 106.827153
  }
}

contact

{
  "username": "@azickri",
  "type": "contact",
  "contact": {
    "name": "Azickri",
    "phone": "6281234567890"
  }
}

to a group

{
  "group": "-1001234567890",
  "type": "text",
  "text": "Hi everyone! 👋"
}

to a channel

{
  "channel": "-1001234567890",
  "type": "text",
  "text": "Fresh update!"
}

to a user

{
  "user": "123456789",
  "type": "text",
  "text": "Thanks for your order! 🙏"
}

to a phone

{
  "phone": "6281234567890",
  "type": "text",
  "text": "Hi! This is from Zate."
}

Response

200

{
  "messageId": "1024"
}

400

// No receiver
{
  "statusCode": 400,
  "message": "invalid phone, username, user, group or channel"
}

// Username or ID not found
{
  "statusCode": 400,
  "message": "chat not found"
}

// Phone number can't be looked up
{
  "statusCode": 400,
  "message": "phone is not on telegram or hidden by its privacy settings"
}

// A required field for that type is empty
{
  "statusCode": 400,
  "message": "image should not be empty"
}

404

{
  "statusCode": 404,
  "message": "session not found"
}

500

// Session isn't connected
{
  "statusCode": 500,
  "message": "session not connected"
}

// Media couldn't be downloaded
{
  "statusCode": 500,
  "message": "error parser file from url 404 Not Found"
}

// Refused by Telegram
{
  "statusCode": 500,
  "message": "403: CHAT_WRITE_FORBIDDEN (caused by messages.SendMessage)"
}

Field	Type	Description
messageId	string	ID of the message in the receiving chat.

Messages from the API skip the webhook

Messages sent through this endpoint aren't echoed to your webhook, since the response already gives you the messageId.