Backend guide
Server API development guide
Authenticate backend requests, manage users and relationships, administer groups, send chat and push messages, upload files, and integrate AI knowledge workflows.
The Lanying server API is an HTTPS JSON API for trusted backend environments. It administers application users, contacts, groups, messages, files, push notifications, tokens, and AI workflows. Client applications must never receive the server access token.
Credentials and trust boundary
| Value | Source | Exposure |
|---|---|---|
| api_endpoint | Application information in the console | Backend configuration; clients use their SDK endpoint configuration. |
| app_id | Application information in the console | Public application identifier, but still validate it server-side. |
| access-token | Token management in the console | Backend secret only; store in a secret manager. |
| user_id | User registration or lookup | Use where an endpoint acts on behalf of a particular application user. |
| user token | Issued through the trusted backend flow | Return only to the authenticated matching client user. |
curl -X {METHOD} '{api_endpoint}/{URI}' \
-H "Content-Type: application/json" \
-H 'access-token: {access-token}' \
-H 'app_id: {app_id}' \Examples in the legacy guide contain historical hosts, paths, and credentials. Preserve samples when migrating them, but resolve the current api_endpoint and generated endpoint contract from the console/reference before production use.
Request and response rules
- Use HTTPS and Content-Type: application/json unless an upload endpoint explicitly requires another media type.
- Send app_id and access-token in the exact header names required by the endpoint; some user-scoped operations also require user_id.
- Treat transport status and the Lanying response code as separate error layers; business errors may be returned in a successful HTTP response.
- Apply timeouts, bounded retries with jitter, idempotency controls, and request correlation IDs in your backend wrapper.
- Never log access tokens, passwords, signed upload parameters, message bodies, or private file URLs.
API capability map
| Resource | Typical responsibilities |
|---|---|
| /user | Register users, update profiles/settings, look up users, and issue client authentication material. |
| /roster and user relationship routes | Add contacts, list relationships, handle applications, and administer block lists. |
| /group | Create/destroy groups; manage members, roles, invitations, applications, mute/block lists, announcements, and files. |
| /message | Send chat messages to users or groups and support AI/file message workflows. |
| /file | Obtain signed upload/download information for chat files and profile assets. |
| /push | Send notifications by all devices, tag, alias, user ID, or push token. |
| /ai | AI-agent and knowledge-base operations exposed by the active API version. |
Register users and issue client access
Create the application user from your authenticated backend account flow. Store the returned Lanying user ID beside your own user record. For client token sign-in, issue or fetch only the token belonging to the authenticated user and return it over your own protected API.
curl -X POST 'https://api.maximtop.com/user/register/v2' \
-H "Content-Type: application/json" \
-H 'app_id: welovemaxim' \
-d '{ "username": "test_user", "password": "asd"}'- Make the mapping between your user and the Lanying user ID unique and transactional.
- Do not expose registration as an unauthenticated proxy unless your abuse controls are designed for it.
- Validate username and password rules before calling the upstream endpoint, while still handling its authoritative error code.
- Rotate server access tokens independently of client user sessions.
Contacts and relationship administration
| Workflow | Backend responsibility |
|---|---|
| Add contacts | Supply the acting user ID and target list only after application-level authorization. |
| List contacts | Page/cache carefully and treat the server relationship state as authoritative. |
| Applications | Preserve request identity and prevent duplicate accept/decline handling. |
| Block list | Enforce privacy decisions in your own features as well as in chat. |
| Aliases | Treat per-user aliases as private relationship metadata. |
Groups and membership
Group APIs cover the full lifecycle and are permission-sensitive. The backend must decide whether it is acting administratively or on behalf of a user, pass the correct user context, and surface Lanying permission failures rather than bypassing product rules silently.
| Area | Operations to support |
|---|---|
| Lifecycle | Create, read, update, destroy, transfer ownership, join, and leave. |
| Membership | Invite, apply, accept/decline, list members, remove members, and manage roles. |
| Moderation | Mute list, block list, member permissions, and group policy. |
| Content | Announcements and shared files with author/uploader permission checks. |
| Scale | Pagination, capacity limits, rate limits, and batch-size constraints. |
Send chat messages
The administrator send endpoint targets either users or groups in one call; do not mix target types. Select the documented content type and attachment/config fields for the SDK version, and validate batch limits before sending.
curl -X POST 'https://api.maximtop.com/message/send' \
-H "Content-Type: application/json" \
-H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
-H 'app_id: welovemaxim' \
-d '{"targets":[2302128618880],"type":1,"content":"hello","content_type":0}'The token above is part of the historical source sample and must not be used. Replace every host, identifier, and credential with values from your own console environment.
Upload and send files safely
- Request upload and download information from the file API using the final target type and target ID.
- Upload bytes using the returned method, URL, and signed object-storage fields exactly as specified.
- Create the file or media message using the returned download URL and the required attachment metadata.
- Persist upload state so retries do not create duplicate messages; expire abandoned signed data promptly.
- Validate file type, size, content, and authorization in your application before requesting or publishing an upload.
Send push notifications
| Audience | Shape |
|---|---|
| All devices | The string all. |
| Tags | An audience object containing a tag list. |
| Aliases | An audience object containing an alias list. |
| Users | An audience object containing user_id values. |
| Device tokens | An audience object containing push_token values. |
推送文本给APP下所有设备：
curl -X POST 'https://api.maximtop.com/push/notify' \
-H "Content-Type: application/json" \
-H 'access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJhcHAiOiJkcGJkdmVrZmVjYm8iLCJzdWIiOiIyMCIsImNsdXN0ZXIiOjAsInJvbGUiOjIsImlhdCI6MTU2Nzk5NzQwOH0.U-iFpEwprrkf-mFkhHN_CWmF5nkBbRQLTjttN4Qlkzw3ET1Zke9OZdjutm90KSyDs9jjYvUSAGGsWVjLmDZlkg' \
-H 'app_id: welovemaxim' \
-d '{"audience": "all","message": {"type": "text","title": "this is push title","body": "this is push body"}}'- Use chat-message push configuration for offline chat notifications; use /push/notify for application notifications.
- Respect the documented audience batch limit and split large targeted sends safely.
- Do not put secrets or sensitive full message content in notification payloads.
- Track campaign/application IDs in ext only when clients validate and handle them safely.
AI knowledge ingestion
The historical workflow sends a web URL as a text message or uploads a document and sends it as a file message to the chatbot, with AI metadata in ext. Confirm current supported formats and AI endpoint behaviour in the generated server reference before building a production ingestion pipeline.
| Input | Workflow |
|---|---|
| HTTPS HTML URL | Send the URL as text to the chatbot with the documented AI metadata. |
| Other supported file | Get upload data, upload the file, then send a file message containing the download URL and metadata. |
| Operational controls | Record ingestion identity, status, errors, retries, and user-visible source metadata. |
Error handling and operations
- Map HTTP/network failures separately from Lanying business error codes.
- Retry only operations known to be safe; add application idempotency keys or deduplication for creation and send flows.
- Back off on rate limits and server-busy responses and expose metrics by endpoint and error code.
- Rotate access tokens through a secret manager and support overlapping rotation without downtime.
- Alert on authentication failures, elevated send errors, upload failures, and unexpected latency.
- Use least privilege for administrative APIs and audit every backend action that affects another user.
Backend release checklist
- Resolve endpoint and credentials per environment; never hard-code sample hosts or tokens.
- Validate all target IDs, batch sizes, file limits, and user authorization before upstream calls.
- Test token rotation, rate limiting, timeouts, retry storms, and partial batch failures.
- Redact request/response secrets and personal data from logs and traces.
- Contract-test the exact generated API version used in production.
- Keep clients insulated from server API changes through your own stable backend interface.