Universal Zalo Bot Library

An Arduino library for interacting with the Zalo Bot API, designed to work across multiple platforms including ESP32, ESP8266, and Arduino boards with WiFi modules.

Installation

1. Open Arduino IDE

2. Go to:

   Sketch → Include Library → Manage Libraries
   

3. Search for:

   Universal Arduino Zalo Bot
   

4. Click Install

Dependencies

This library requires:

• ArduinoJson

Install it via Library Manager or manually from GitHub.

Usage

Create a Zalo bot

To generate your new Bot, you need an Access Token. Talk to Zalo Bot Manager and follow a few simple steps described here.

Setup your bot

For normal mode:

UniversalZaloBot zalo(BOT_TOKEN, client);

For FreeRTOS mode:

UniversalZaloBot zalo(BOT_TOKEN, client, true);

where BOT_TOKEN is your Zalo bot access token and client is your network client.

Example

Print received messages to console

#include <WiFi.h>
#include <WiFiClientSecure.h>
#include <UniversalZaloBot.h>

const char* ssid = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";

#define BOT_TOKEN "YOUR_ZALO_BOT_TOKEN"

WiFiClientSecure client;
UniversalZaloBot zalo(BOT_TOKEN, client);

void setup() {
  Serial.begin(115200);

  WiFi.mode(WIFI_STA);
  WiFi.begin(ssid, password);

  client.setInsecure();  // skip certificate validation

  while (WiFi.status() != WL_CONNECTED) {
    Serial.print(".");
    delay(500);
  }

  Serial.println("");
  Serial.print("Connected to Wifi. Local IP: ");
  Serial.println(WiFi.localIP());

  zalo.onText([](const Message& message) {
    String log =
      "---- New Message ----\n"
      "Chat ID: " + String(message.chatId) + "\n" +
      "User ID: " + String(message.userId) + "\n" +
      "User Name: " + String(message.userName) + "\n" +
      "Content: " + String(message.content) + "\n" +
      "---------------------";

    Serial.println(log);
    zalo.sendMessage(message.userId, log);
  });
}

void loop() {
  zalo.handleUpdate();
  delay(1);
}

More examples

You can find more examples here

Library API

Here is a list of the main features that this library covers.

Features	Description	Usage
Debug	Show logs and useful data	setDebug(bool isDebug)
Sending messages	Your bot can send messages to any Zalo account	bool sendMessage(const String &chat_id, const String &message)
Sending photos	Your bot can send photos to any Zalo account	bool sendPhoto(const String &chat_id, const String &photo_url, const String &caption = "")
Sending stickers	Your bot can send stickers to any Zalo account	bool sendSticker(const String &chat_id, const String &sticker_id)
Sending chat action	Your bot can send chat actions to any Zalo account	bool sendChatAction(const String &chat_id, const String &action)
Receive messages	Your bot can receive messages via long polling	Message getUpdates()
Handle updates	Your bot can handle incoming message updates in real time (long polling). Required for onText, etc. Should be used inside an infinite loop	void handleUpdate()
onText	Handles callbacks triggered by incoming text messages	void onText(ZaloEventCallback callback)
onPhoto	Handles callbacks triggered by incoming photo messages	void onPhoto(ZaloEventCallback callback)
onSticker	Handles callbacks triggered by incoming sticker messages	void onSticker(ZaloEventCallback callback)
onUpdate	Handles callbacks triggered by any incoming messages	void onUpdate(ZaloEventCallback callback)
onCommand	Handles callbacks triggered by any matched messenges (startswith) > ESP32 and ESP8266 only	void onCommand(const String &command, ZaloEventCallback callback)

Notes

• Zalo currently supports a limit of 3,000 sent messages per month. Please use it carefully.
• Zalo does not support long polling offsets, so messages may be lost if they are sent too quickly.
• Parallel, non-blocking mode is supported with FreeRTOS (ESP32).
• When using FreeRTOS mode, the network task (Zalo) must run on Core 0 to avoid crashes.
• Use FreeRTOS to manage tasks efficiently by using two separate instances—one for receiving and one for sending—so the receiver doesn’t block the sender with long polling.

Roadmap

• Webhook integration
• Add more FreeRTOS supported boards to the library
• Add more examples
• Reduce memory and ROM costs
• Support PlatformIO

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

This project is licensed under the Apache License 2.0.

Credits

• Maintainer: chunix64
• Inspired by Universal Arduino Telegram Bot
• Built for Arduino & ESP-based IoT projects