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

Background information

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


  1. Prepare a certificate.

    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. Develop a client.

    IoT Platform provides MQTT SDK for Java. You can use this client SDK and replace the URL with a URL that is used by WebSocket. For information about how to obtain MQTT SDKs for other programming languages or customize MQTT SDKs, see Open source MQTT client. Before you use MQTT SDKs, read the instructions and check whether WebSocket is supported.

  3. Establish a connection with IoT Platform.

    An MQTT over WebSocket connection has a different protocol and port number in the URL from an MQTT over TCP connection. An MQTT over WebSocket connection has the same parameters as an MQTT over TCP connection. Set the securemode parameter to 2 when you use WebSocket Secure. Set the securemode parameter to 3 when you use WebSocket.

    • Endpoint: Format: ${YourProductKey}.iot-as-mqtt.${YourRegionId}
      • Replace the ${YourProductKey} variable with the ProductKey of the product to which your device belongs. You can log on to the IoT Platform console and view the ProductKey on the Device Details page.
      • ${YourRegionId}: Replace this variable with the ID of the region where your IoT Platform device resides. For more 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. Valid values of the keep-alive time: 30 to 1,200 seconds. If the value of the Keep Alive parameter 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 network connection is unstable, we recommend that you set the keep-alive period to a higher 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 within the 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 signature method. 
      content=Parameters sent to the server (productKey,deviceName,timestamp,clientId). Sort these parameters in alphabetical order and splice the parameters and parameter values.
      The field value varies based on the following operation types:
      • clientId: the ID of the client. The client ID can be up to 64 characters in length. We recommend that you use a MAC address or serial number (SN).
      • timestamp: optional. The current time in milliseconds.
      • mqttClientId: Parameters within the vertical bars (||) are extended parameters.
      • signmethod: the signature algorithm.
      • securemode: the secure mode. Valid values: 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 a WebSocket connection:
      • Endpoint
      • Parameter
    • For a WebSocket Secure connection:
      • Endpoint
      • Parameter

    We recommend that you use Link SDK to connect devices to IoT Platform. For information about how to develop a custom device SDK for connection, see Examples of creating signatures for MQTT connections.