Integration of MAX with business systems via max.botservice

Integrating MAX into Business Systems: A Practical Guide to max.botservice

MAX is becoming a key communication channel for businesses in Russia, but integrations often end up as fragile scripts. The max.botservice solves this by providing a unified infrastructure for working with the MAX API via HTTP interfaces, data storage, and security features.

Architecture and Functionality

max.botservice is a Go-based HTTP service that acts as a bridge between the MAX API and your internal systems. It handles events from MAX—like user messages and chat updates—and exposes endpoints for sending notifications from CRM, ERP, or monitoring systems. It's not just a bot; it's an infrastructure layer that simplifies integrations without needing a bunch of custom utilities.

For users, the bot offers an intuitive button menu in direct messages, letting them view chat IDs, manage groups, set up notifications, and link phone numbers. In group chats, the bot only activates with admin rights, keeping things quiet and focused on work.

Event Handling and Data Storage

The service supports two ways to receive events from MAX:

• Webhook: MAX pushes events to your external URL—perfect for production with HTTPS access.
• Long polling: The service polls MAX via GET /updates—great for testing or local dev without public endpoints.

Data is stored in SQLite for easy setup without managing separate databases. Key entities include:

• Contacts: Linking phone numbers to MAX users.
• Group chats: IDs, names, and flags like sending welcome menus.

The service auto-refreshes the group list on startup and periodically, adapting to changes without manual tweaks.

External API and Use Cases

For integrating with other systems, the service offers an HTTP API with core methods:

• POST /send-message: Send messages to direct chats by chat ID.
• POST /send-by-phone: Send messages by phone number using the local contacts table.
• POST /send-to-group-by-chatid: Send messages to group chats.

Extra utility methods handle group cache updates, chat lists, and performance metrics. This makes it easy to hook MAX into existing setups, like order status alerts or monitoring incident notifications.

Security and Deployment

Security is handled via environment variables, keeping it simple:

• WEBHOOK_SECRET: Validates X-Webhook-Secret headers for webhooks.
• API_KEY: Secures admin methods with X-API-Key headers.
• Rate limiting: Caps requests per minute to prevent abuse and errors.

Deployment is straightforward:

• Clone the GitHub repo.
• Set up your .env file with BOT_TOKEN.
• Run with go run ./cmd or build a Docker image.
• Use docker-compose for orchestration if needed.

Default port is 8080, configurable via PORT. Logs support JSON format with LOG_FORMAT=json, and verbosity via LOG_LEVEL.

Key Takeaways

• max.botservice consolidates scattered MAX integrations into one service, cutting maintenance hassle.
• Webhook and long polling support adapts to dev, test, and prod environments.
• SQLite keeps deployment simple—no extra infra needed.
• Built-in security like auth and rate limiting guards against abuse.
• Ideal for teams needing quick bot launches, notifications, and chat management without major architecture changes.

— Editorial Team