SSE Long Connection Guide
This guide walks you through establishing and maintaining the SSE long connection for real-time device message push.
Endpoint
GET https://api-open.mammotion.com/developer-sse/api/client/sseResponse MIME Type: text/event-stream
Required Request Headers
| Header | Value | Remarks |
|---|---|---|
Authorization | Bearer {your-access-token} | Developer platform authentication token |
SSE-Client | developer | Fixed constant, must be passed as-is |
Accept | text/event-stream | Mandatory header to declare SSE stream acceptance |
Strict Execution Sequence
Call the subscription API first, then establish the SSE connection.
- Invoke
/v1/subscription/configto set subscriptions - Establish this SSE long connection
If you connect SSE before subscription, no device business data will be pushed.
Special SSE Messages
These are system control messages, not device attribute business messages.
| Raw Message | Message Type | Client Processing Suggestion |
|---|---|---|
:: Connect to server successful :: | Connection initialization message | Mark SSE channel ready to receive business payload |
:: heartbeat :: | Periodic heartbeat packet | Ignore directly. Only for gateway link keep-alive |
{"pushTag":"sc","pushType":1} | Server-side kick-off notification | Gracefully close current connection. DO NOT auto-reconnect. This happens when another SSE connection is created under the same developer account, to avoid infinite connection preemption loops |
All business data messages follow the unified format {"pushTag":"xxx","pushType":N,"pushData":{...}}. See the Push Message Reference for all business payload schemas.
Connection Lifecycle & Rules
- Idle timeout: The server actively closes the connection if no data is received for 10 consecutive minutes.
- Subscription push validity: After the subscription expires, the SSE TCP connection remains alive, but the server stops delivering business push data. You need to re-call the subscription API to resume data push.
- Subscription record lifetime: The subscription configuration itself is valid for 30 days. Re-subscribe before expiry.
Debug Instruction
STRICTLY FORBIDDEN to use the built-in SSE debugger on the document page. The built-in debugger will generate massive zombie idle connections on the server, and may kick out your formal SSE connection under the same developer account.
Use curl for local debugging:
curl -N \
-H "Authorization: Bearer ReplaceWithYourRealAccessToken" \
-H "SSE-Client: developer" \
-H "Accept: text/event-stream" \
https://api-open.mammotion.com/developer-sse/api/client/sseHTTP Status Codes & Connection Closing Reasons
| Status | Meaning |
|---|---|
200 OK | SSE streaming connection established successfully |
401 Unauthorized | Token missing, expired or authentication failed |
403 Forbidden | No permission to create SSE connection |
The server actively closes connections for these reasons:
- Subscription expired
- Long idle timeout
- Server-side kick-off (new connection preempted)
- Manual termination
Client Recommended Practices
- Set the read timeout longer than the heartbeat interval.
- For normal disconnections (excluding the
sckick message), implement an exponential backoff reconnection strategy. - After reconnection succeeds, verify whether the subscription is still valid; re-subscribe if it has expired.


