Skip to Content
Documentation
API Documentation
Our API documentation and how to authorize towards Mammotion Open APIs.
API illustration

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/sse

Response MIME Type: text/event-stream

Required Request Headers

HeaderValueRemarks
AuthorizationBearer {your-access-token}Developer platform authentication token
SSE-ClientdeveloperFixed constant, must be passed as-is
Accepttext/event-streamMandatory header to declare SSE stream acceptance

Strict Execution Sequence

Call the subscription API first, then establish the SSE connection.

  1. Invoke /v1/subscription/config to set subscriptions
  2. 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 MessageMessage TypeClient Processing Suggestion
:: Connect to server successful ::Connection initialization messageMark SSE channel ready to receive business payload
:: heartbeat ::Periodic heartbeat packetIgnore directly. Only for gateway link keep-alive
{"pushTag":"sc","pushType":1}Server-side kick-off notificationGracefully 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

  1. Idle timeout: The server actively closes the connection if no data is received for 10 consecutive minutes.
  2. 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.
  3. 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/sse

HTTP Status Codes & Connection Closing Reasons

StatusMeaning
200 OKSSE streaming connection established successfully
401 UnauthorizedToken missing, expired or authentication failed
403 ForbiddenNo 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
  • Set the read timeout longer than the heartbeat interval.
  • For normal disconnections (excluding the sc kick message), implement an exponential backoff reconnection strategy.
  • After reconnection succeeds, verify whether the subscription is still valid; re-subscribe if it has expired.
Last updated on
Logo
Mammotion Developer
2026 @MAMMOTION Technology