IoT Platform supports MQTT over WebSocket. You can first use the WebSocket protocol to establish a connection, and then use the MQTT protocol to communicate on the WebSocket channel.

Background information

WebSocket provides the following benefits:
  • Allows browser-based applications to establish persistent connections to the server.
  • Uses port 433, which allows messages to pass through most firewalls.


  1. Certificate preparation

    The WebSocket protocol includes WebSocket and WebSocket Secure. WebSocket and WebSocket Secure are used for unencrypted and encrypted connections, respectively. Transport Layer Security (TLS) is used in WebSocket Secure connections. Like a TLS connection, a WebSocket Secure connection requires a root certificate.

  2. Client selection

    IoT Platform provides Java MQTT SDK. You can use this client SDK by replacing the connection URL with a URL that is used by WebSocket. For clients that use other language versions or connections without using the official SDK, see Open-source MQTT clients. Make sure that the client supports WebSocket.

  3. Connections

    An MQTT connection over WebSocket has a different protocol and port number in the connection URL from an MQTT over TCP connection. MQTT connections over WebSocket have the same parameters as MQTT connections over TCP. The securemode parameter is set to 2 and 3 for WebSocket Secure and WebSocket, respectively.

    • Endpoint:
      • To view the endpoint of the instance that you purchased, perform the following steps: Log on to the IoT Platform console. In the left-side navigation pane, click Instances. On the page that appears, click View in the Actions column of the instance. On the Instance Details page, you can view the endpoints.
      • The endpoint for public instances is ${YourProductKey}.iot-as-mqtt.${YourRegionId}
        • ${YourProductKey}: Replace this variable with the ProductKey of the product to which the device belongs. You can obtain the ProductKey on the Device Details page of the IoT Platform console.
        • ${YourRegionId}: Replace this variable with your region ID. For information about region IDs, see Regions and zones.
    • Port number: 443.
    • Variable header: Keep Alive.

      The Keep Alive parameter must be included in the CONNECT packet. The allowed range of Keep Alive value is 30 to 1,200 seconds. If the Keep Alive value is not in this range, IoT Platform rejects the connection. We recommend that you set a value that is greater than 300 seconds. If the Internet connection is not stable, set a larger value.

      In a keep-alive interval, the device must send at least one message, including ping requests.

      If IoT Platform does not receive a message in a keep-alive interval, the device is disconnected from IoT Platform and must reconnect to the server.

    • An MQTT Connect packet contains the following parameters:
      mqttClientId: clientId+"|securemode=3,signmethod=hmacsha1,timestamp=132323232|"
      mqttUsername: deviceName+"&"+productKey
      mqttPassword: sign_hmac(deviceSecret,content)sign. Sort the content parameters in alphabetical order and sign them by using the signing method.
      content=Parameters sent to the server (productKey,deviceName,timestamp,clientId). Sort these parameters in alphabetical order and splice the parameters and parameter values.
      • clientId: Specifies the client ID up to 64 characters. We recommend that you use a MAC address or SN.
      • timestamp: Optional. Specifies the current time in milliseconds.
      • mqttClientId: Parameters within || are extended parameters.
      • signmethod: Specifies a signature algorithm.
      • securemode: Specifies the secure mode. Values include 2 (WebSocket Secure) and 3 (WebSocket).

    The following examples show MQTT Connect packets with predefined parameter values:

    clientId=12345, deviceName=device, productKey=pk, timestamp=789, signmethod=hmacsha1, deviceSecret=secret
    • For WebSocket:
      • Endpoint
      • Parameter
    • For WebSocket Secure:
      • Endpoint
      • Parameter

    We recommend that you use the Link SDK to connect the device to IoT Platform. For information about how to use your own device SDK for connection, see Examples of creating signatures for MQTT connections.