go-zalo-bot-api

A batteries-included Go client for the Zalo Bot API. It wraps the HTTP endpoints with typed request/response models, retry-aware transports, and ergonomic helpers so you can focus on your bot logic instead of wiring.

Features

• ✅ Lightweight, concurrency-safe Client abstraction with configurable base URL, custom HTTP client, and user agent.
• ✅ Ready-made endpoint helpers for common actions (get bot info, manage webhooks, send messages, stickers, and chat actions).
• ✅ Iterator-based long-polling helper that smooths over pagination and transient failures.
• ✅ Pluggable logging interface with structured logging support out of the box.

Installation

go get github.com/nduyhai/go-zalo-bot-api

Quick start

Create a client with your bot token and call any endpoint helper. Each request accepts per-call options such as timeouts so you can control retry and cancellation behaviour.

package main

import (
    "context"
    "log/slog"
    "time"

    zalobotapi "github.com/nduyhai/go-zalo-bot-api"
    "github.com/nduyhai/go-zalo-bot-api/endpoints"
)

func main() {
    botToken := "<your bot token>"
    chatID := "<chat id>"

    logger := zalobotapi.NewSlogLogger(slog.Default())
    client := zalobotapi.New(botToken,
        zalobotapi.WithLogger(logger),
        zalobotapi.WithUserAgent("my-bot/1.0"),
    )

    ctx := context.Background()

    // Call any endpoint helper. This example sends a message with a per-call timeout.
    _, err := endpoints.SendMessage(ctx, client, endpoints.SendMessageReq{
        ChatID: chatID,
        Text:   "Xin chào từ go-zalo-bot-api!",
    }, zalobotapi.WithTimeout(5*time.Second))
    if err != nil {
        logger.Error("send message", map[string]any{"err": err})
    }
}

Looking for a more complete example (with retries, custom transports, and long-polling for updates)? Check out cmd/example/main.go.

Environment variables

The example program expects:

• BOT_TOKEN – the access token of your Official Account bot.
• CHAT_ID – the identifier of the conversation you want to send messages to.

You can use a .env file together with godotenv to load these values during development.

Development

1. Export the required environment variables (or create a .env file) with values for BOT_TOKEN and CHAT_ID.
2. Run the example bot:

   make run

   This executes go run ./cmd/example so you can verify connectivity and explore the iterator-based long-polling helpers.

License

Distributed under the MIT License.