Build on Engaz

Bot API

A bot that talks with people in chats and groups

A bot is a special account with no phone number, owned by a person or a business, that speaks only through its token. People find it by username and tap “Start”.

• Every message type: text, photos, files, polls, location and product cards
• Buttons under a message, reply keyboards, and commands shown when typing /
• Updates by long polling with getUpdates, or by webhook
• Mini apps: a web page that opens inside the app with signed data
• Inline bots called with @botname in any chat
• “No-code replies”: simple rules that answer at once, even without a server
• Connect a bot to a business account to answer customers in its name

# Send a message with buttons from a bot
TOKEN='<botId>:<secret>'
curl -s "https://www.engaz.net/bot/$TOKEN/sendMessage" \
  -H 'content-type: application/json' -d '{
  "conversationId": "CONV_ID",
  "text": "Pick a size",
  "replyMarkup": {"inlineKeyboard": [[
    {"text": "Small", "callbackData": "size:s"},
    {"text": "Large", "callbackData": "size:l"}
  ]]}}'

# Answer the button press
curl -s "https://www.engaz.net/bot/$TOKEN/answerCallbackQuery" \
  -H 'content-type: application/json' \
  -d '{"callbackQueryId": "CQ_ID", "text": "Large it is"}'

Every answer is { "ok": true, "result": … } or { "ok": false, "error": "…", "message": "…" }.

Webhooks

Every event, the moment it happens

Add an https URL and choose your events. Each event is a signed POST, retried on failure after 5 seconds, 30 seconds, 2 minutes, 10 and 30 minutes.

• message.received, message.reply and message.sent
• button.pressed when a customer taps a button on an API message
• member.joined and member.left in your business’s groups
• call.ringing, call.answered, call.ended and call.missed
• A “Test event” button in the app to try the connection with automation tools

// Node.js: check the signature before accepting an event
import { createHmac, timingSafeEqual } from 'node:crypto';

const ts = req.headers['x-engaz-timestamp'];
const want = 'sha256=' + createHmac('sha256', SECRET)
  .update(`${ts}.${rawBody}`).digest('hex');
const got = String(req.headers['x-engaz-signature'] ?? '');
const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
if (!fresh || want.length !== got.length ||
    !timingSafeEqual(Buffer.from(want), Buffer.from(got))) {
  return res.status(401).end();
}
res.status(200).end(); // answer 2xx within 10 seconds