tencent cloud

All product documents
Tencent Cloud Super App as a Service
DocumentationTencent Cloud Super App as a ServiceGuildlines for Mini Game DevelopmentAPINetworkWebsocket
Websocket
Download PDF
Last updated: 2025-04-10 18:18:33
Websocket
Last updated: 2025-04-10 18:18:33
Download PDF
Note:
It is advisable to utilize the SocketTask method to manage WebSocket connections, as it provides greater control over the lifecycle of each link. In scenarios where multiple WebSocket connections exist, the use of methods with a wx prefix may result in situations that deviate from expectations.

sendSocketMessage

The usage of this API is as follows: wx.sendSocketMessage(Object object)
Function Description: This feature allows data transmission via WebSocket connection. It requires an initial wx.connectSocket, and can only transmit data after the wx.onSocketOpen callback.
Parameters and Description: Object object.
Attributes
Types
Default value
Required
Note
data
string/ArrayBuffer
-
Supported
Content to be dispatched
success
function
-
Not required
Callback function for successful interface invocation
fail
function
-
Not required
Callback function for unsuccessful interface invocation
complete
function
-
Not required
Callback function executed upon the completion of the interface invocation (both successful and unsuccessful invocations)
Sample Code:
let socketOpen = false
let socketMsgQueue = []
wx.connectSocket({
  url: 'test.php'
})

wx.onSocketOpen(function(res) {
  socketOpen = true
  for (let i = 0; i < socketMsgQueue.length; i++){
    sendSocketMessage(socketMsgQueue[i])
  }
  socketMsgQueue = []
})

function sendSocketMessage(msg) {
  if (socketOpen) {
    wx.sendSocketMessage({
      data:msg
    })
  } else {
    socketMsgQueue.push(msg)
  }
}

onSocketOpen

The usage method for this API is wx.onSocketOpen(function listener)
Function Description: Monitors the WebSocket connection opening event.
Parameters and Description: function listener, the monitoring function for the WebSocket connection opening event.
Attributes
Types
Note
header
object
HTTP response Header upon successful connection

onSocketMessage

The usage method for this API is wx.onSocketMessage(function listener)
Function Description: Monitors the event of WebSocket receiving a message from the server.
Parameters and Description: function listener, the monitoring function for the event of WebSocket receiving a message from the server.
Attributes
Types
Note
data
string/ArrayBuffer
Message returned by the server

onSocketError

The usage method for this API is wx.onSocketError(function listener)
Function Description: Monitors the WebSocket error event.
Parameters and Description: function listener, the monitoring function for the WebSocket error event.
Attributes
Types
Note
errMsg
string
Error Message

onSocketClose

The usage method for this API is wx.onSocketClose(function listener)
Function Description: Monitors the WebSocket connection closure event.
Parameters and Description: function listener, the monitoring function for the WebSocket connection closure event.
Attributes
Types
Note
code
number
A numerical value representing the status number of the closed connection, indicating the reason for the connection closure.
reason
string
A readable string indicating the reason for the connection closure.

connectSocket

The usage method for this API is SocketTask wx.connectSocket(Object object)
Function Description: Establishes a WebSocket connection. Please read the relevant instructions.
Parameters and Description: Object object.
Attributes
Types
Default value
Required
Note
url
string
-
Supported
Developer server's wss interface address
header
Object
-
Not required
HTTP Header, the Referer cannot be set in the Header.
protocols
Array.<string>
-
Not required
Array of sub-protocols.
tcpNoDelay
boolean
false
Not required
TCP_NODELAY setting during the establishment of a TCP connection.
timeout
number
-
Not required
Timeout duration, measured in milliseconds.
success
function
-
Not required
Callback function for successful interface invocation
fail
function
-
Not required
Callback function for unsuccessful interface invocation
complete
function
-
Not required
Callback function executed upon the completion of the interface invocation (both successful and unsuccessful invocations)
Return Value: SocketTask.
Concurrency Count
In versions 1.5.0 and above, a maximum of five WebSocket connections can coexist simultaneously.
In versions below 1.5.0, a mini program can only maintain a single WebSocket connection at a time. If a WebSocket connection already exists, it will be automatically closed and a new WebSocket connection will be established.
Example Code
wx.connectSocket({
  url: 'wss://example.qq.com',
  header:{
    'content-type': 'application/json'
  },
  protocols: ['protocol1']
})

closeSocket

The usage of this API is wx.closeSocket(Object object).
Function Description: This function closes the WebSocket connection. The method of use is as follows.
Parameters and Description: Object object.
Attributes
Types
Default value
Required
Note
code
number
1000 (indicating a normal closure of the connection)
Not required
A numerical value representing the status number of the closed connection, indicating the reason for the connection closure.
reason
string
-
Not required
A readable string indicating the reason for the connection closure. This string must be a UTF-8 text that does not exceed 123 bytes in length (not characters).
success
function
-
Not required
Callback function for successful interface invocation
fail
function
-
Not required
Callback function for unsuccessful interface invocation
complete
function
-
Not required
Callback function executed upon the completion of the interface invocation (both successful and unsuccessful invocations)
Sample Code:
wx.connectSocket({
  url: 'test.php'
})

//Please note that there may be timing issues here,
//If wx.connectSocket has not yet called back wx.onSocketOpen, and wx.closeSocket is called first, then the purpose of closing the WebSocket cannot be achieved.
//It is imperative to call wx.closeSocket during the WebSocket's open period to effectuate closure.
wx.onSocketOpen(function() {
  wx.closeSocket()
})

wx.onSocketClose(function(res) {
  console.log('WebSocket has been closed!')
})

SocketTask

.close

The method is utilized in the form of SocketTask.close(Object object).
Function Description: This function serves to close the WebSocket connection.
Parameters and Description: Object object.
Attributes
Types
Default value
Required
Note
code
number
1000 (indicating a normal closure of the connection)
Not required
A numerical value representing the status number of the closed connection, indicating the reason for the connection closure.
reason
string
-
Not required
A readable string indicating the reason for the connection closure. This string must be a UTF-8 text that does not exceed 123 bytes in length (not characters).
success
function
-
Not required
Callback function for successful interface invocation
fail
function
-
Not required
Callback function for unsuccessful interface invocation
complete
function
-
Not required
Callback function executed upon the completion of the interface invocation (both successful and unsuccessful invocations)

.onClose

The method is employed as SocketTask.onClose(function listener).
Function Description: Monitors the WebSocket connection closure event.
Parameters and Description: function listener, the monitoring function for the WebSocket connection closure event.
Attributes
Types
Note
code
number
A numerical value representing the status number of the closed connection, indicating the reason for the connection closure.
reason
string
A readable string indicating the reason for the connection closure.

.onError

The method is invoked as SocketTask.onError(function listener).
Function Description: Monitors the WebSocket error event.
Parameters and Description: function listener, the monitoring function for the WebSocket error event.
Attributes
Types
Note
errMsg
string
Error Message

.onMessage

The method is implemented as SocketTask.onMessage(function listener).
Function Description: Monitors the event of WebSocket receiving a message from the server.
Parameters and Description: function listener, the monitoring function for the event of WebSocket receiving a message from the server.
Attributes
Types
Note
data
string/ArrayBuffer
Message returned by the server

.onOpen

The method is executed as SocketTask.onOpen(function listener).
Function Description: Monitors the WebSocket connection opening event.
Parameters and Description: function listener, the monitoring function for the WebSocket connection opening event.
Attributes
Types
Note
header
Object
HTTP response Header upon successful connection

.send

The usage of this method is SocketTask.send(Object object).
Function Description: Data is transmitted via a WebSocket connection.
Parameters and Description: Object object.
Attributes
Types
Default value
Required
Note
data
string/ArrayBuffer
-
Supported
Content to be dispatched
success
function
-
Not required
Callback function for successful interface invocation
fail
function
-
Not required
Callback function for unsuccessful interface invocation
complete
function
-
Not required
Callback function executed upon the completion of the interface invocation (both successful and unsuccessful invocations)

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback

Contact Us

Contact our sales team or business advisors to help your business.

Contact Us
Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 available.

Submit a Ticket
7x24 Phone Support
Hong Kong, China
+852 800 906 020 (Toll Free)
United States
+1 844 606 0804 (Toll Free)
United Kingdom
+44 808 196 4551 (Toll Free)
Canada
+1 888 605 7930 (Toll Free)
Australia
+61 1300 986 386 (Toll Free)
EdgeOne hotline
+852 300 80699
More local hotlines coming soon