maxigo-client

Idiomatic Go HTTP client for Max Bot API (OpenAPI schema v0.0.10). Zero external dependencies.

Why This Project?

The official max-bot-api-client-go has systemic issues that make it unsuitable for production use:

maxigo-client fixes all of these.

Documentation

• English Guide — full API reference with examples
• Документация на русском — полное описание API с примерами Requires Go 1.25+.

Installation

go get github.com/maxigo-bot/maxigo-client

Quick Start

package main

import (
	"context"
	"fmt"
	"log"

	maxigo "github.com/maxigo-bot/maxigo-client"
)

func main() {
	client, err := maxigo.New("YOUR_BOT_TOKEN")
	if err != nil {
		log.Fatal(err)
	}

	bot, err := client.GetBot(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Bot: %s (ID: %d)\n", bot.FirstName, bot.UserID)
}

Features

• Zero external dependencies — only stdlib
• All methods take context.Context
• Structured error handling with errors.As
• Full Max Bot API coverage: messages, chats, uploads, webhooks, long polling
• Type-safe constructors for all button types and attachments
• Optional[T] generics for three-state fields (unset / zero / value)
• Opt-in automatic retry for rate limits and attachment processing (WithRetry)
• Testable without real API via WithBaseURL

Type-Safe Constructors

No need to remember string constants — use constructors for buttons and attachments:

Buttons:

maxigo.NewCallbackButton("Click", "payload")                        // callback
maxigo.NewCallbackButtonWithIntent("Yes", "yes", maxigo.IntentPositive) // callback with intent
maxigo.NewLinkButton("Open", "https://example.com")                 // link
maxigo.NewRequestContactButton("Share contact")                     // request contact
maxigo.NewRequestGeoLocationButton("Send location", true)           // request geo (quick=true)
maxigo.NewChatButton("Create chat", "Title")                        // create chat
maxigo.NewMessageButton("Send")                                     // message from user
maxigo.NewOpenAppButton("Open WebApp", "bot_username")               // open mini-app

Attachments:

maxigo.NewInlineKeyboardAttachment(buttons) // inline keyboard
maxigo.NewPhotoAttachment(payload)          // image
maxigo.NewVideoAttachment(payload)          // video
maxigo.NewAudioAttachment(payload)          // audio
maxigo.NewFileAttachment(payload)           // file
maxigo.NewStickerAttachment(payload)        // sticker
maxigo.NewContactAttachment(payload)        // contact card
maxigo.NewShareAttachment(payload)          // share link
maxigo.NewLocationAttachment(lat, lng)      // location

Example — inline keyboard with contact and geo buttons:

msg, err := client.SendMessage(ctx, chatID, &maxigo.NewMessageBody{
    Text: maxigo.Some("Choose an option:"),
    Attachments: []maxigo.AttachmentRequest{
        maxigo.NewInlineKeyboardAttachment([][]maxigo.Button{
            {
                maxigo.NewRequestContactButton("Share contact"),
                maxigo.NewRequestGeoLocationButton("Send location", false),
            },
            {
                maxigo.NewCallbackButtonWithIntent("Cancel", "cancel", maxigo.IntentNegative),
            },
        }),
    },
})

API Overview

// Bot
client.GetBot(ctx)
client.EditBot(ctx, patch)

// Messages
client.SendMessage(ctx, chatID, body)
client.SendMessageToUser(ctx, userID, body)
client.SendMessageToPhones(ctx, phoneNumbers, body)
client.EditMessage(ctx, messageID, body)
client.DeleteMessage(ctx, messageID)
client.AnswerCallback(ctx, callbackID, answer)

// Chats
client.GetChat(ctx, chatID)
client.GetChats(ctx, opts)
client.EditChat(ctx, chatID, patch)
client.GetMembers(ctx, chatID, opts)
client.SendAction(ctx, chatID, action)

// Phone numbers
client.CheckPhoneNumbers(ctx, phoneNumbers)

// Uploads
client.UploadPhoto(ctx, filename, reader)
client.UploadMedia(ctx, uploadType, filename, reader)

// Webhooks
client.Subscribe(ctx, url, types, secret)
client.Unsubscribe(ctx, url)

// Long Polling
client.GetUpdates(ctx, opts)

Error Handling

var e *maxigo.Error
if errors.As(err, &e) {
    fmt.Printf("[%s] %s %d: %s\n", e.Op, e.Kind, e.StatusCode, e.Message)
}

Error kinds: ErrAPI, ErrNetwork, ErrTimeout, ErrDecode. See guide for details.

Ecosystem

License

MIT