Server API
The Server API is called by an app backend. First read the Integration guide for common requests and error handling, then complete Authentication and signing. In-container web apps must also follow Passwordless sign-in to exchange an authorization code for the current user's identity.
Integration and authentication
| Documentation | Entry point | Description |
|---|---|---|
| Integration guide | https://{gateway_host} | Unified responses, common request rules, errors, and retries |
| Authentication and signing | /auth/v1/oauth/token | Obtain an app access_token and understand Webhook signing rules |
| Passwordless sign-in | SDK obtains code, /auth/v1/oauth/userinfo | Exchange a page authorization code for the user's identity |
API list
| API | Request entry point |
|---|---|
| Get enterprise information | /open/v1/enterprise/info |
| List departments | /open/v1/contact/department/list |
| Get department details | /open/v1/contact/department/get |
| List department members | /open/v1/contact/user/list |
| Get member details | /open/v1/contact/user/get |
| Send application robot messages | /open/v1/robot/messages |
| Card button callbacks | After a click, the platform sends a signed POST to the button's action URL |
| Group robot | /webhook/robot/send |
| Event subscription | HTTPS URL configured for the app |
Version compatibility
The new card api buttons, value parameter, and display-only empty actions require a self-hosted version > 1.1.13. Version 1.1.13 and earlier do not support these new features; use the existing url button approach on older versions.
Calling conventions
- All examples use
https://{gateway_host},app_xxx, andaccess-token-xxxas placeholders. - Query and sending APIs include Shell, PHP, Golang, and C++ examples; example secrets must remain on the server.
- Member IDs and department IDs are strings. See the Integration guide for unified responses and error handling.
- Robot write APIs should include
Idempotency-Key; keep the same idempotency key and request body when retrying.