tencent cloud

Modifying Dynamically Client Keep Alive Time
Download PDF
Last updated:2026-01-30 14:59:41
Modifying Dynamically Client Keep Alive Time
Last updated: 2026-01-30 14:59:41
Download PDF

Overview

This API is used to dynamically adjust the Keep Alive (heartbeat keepalive) time for online MQTT clients. After this API is invoked, the server will immediately apply the new Keep Alive time without disconnecting the client.

Usage Method

curl --verbose --request POST -H "Authorization: Basic base64(username:password)" http://mqtt.cloud.tencent.com/keep-alive?client-id=${client-id}&interval=${seconds}

Authentication Method

Currently supported authentication methods include Basic HTTP Authentication and X.509 certificate-based "unique certificate per device". JWT-based authentication is currently not supported.

Basic HTTP Authentication

The parameters involved in the Basic Authentication process are as follows:
The request's HTTP header field will contain an Authorization field, as follows: Authorization: Basic <credentials>
<credentials> = username:password is the Base64 encoding.
username participates in ACL authorization.

BYOC (Bring Your Own Certificate Based on X.509 Certificate Authentication)

Root certificate trusted by clients: CA.crt
Client certificate chain file: client.chain.crt
Client private key file: client.pkcs8.key

Request Parameter

Parameter Name
Required
Type
Description
client-id
Yes
String
Client ID
interval
Yes
Integer
New Keep Alive time, ranging from 30 to 1200 (unit: seconds)
Note:
When this API is called, the following limitations apply:
Sessions with current Keep Alive set to 0 are not supported for modification: If Keep Alive is set to 0 during client connection, it cannot be modified via this API.
Modifying Keep Alive to 0 is not supported: Dynamically adjusting the Keep Alive time of existing connections to 0 is not allowed.

Response Parameters

Parameter Name
Type
Description
success
Boolean
Request processing result. true indicates that the modification command was successfully issued.
keepalive
Integer
Modified Keep Alive time value (seconds).

Request Example

Example 1

Use Basic Authentication.
curl --request POST \\
  --header "Authorization: Basic c2Vpcm9saTIyMjo5NEZWUmpTejBOR0dXVmFU" \\
  "http://mqtt.cloud.tencent.com/keep-alive?client-id=curl-x&interval=120"

Example 2

Use BYOC certificate authentication.
curl --tlsv1.2 \\
  --cacert CA.crt \\
  --cert client.chain.crt \\
  --key client.pkcs8.key \\
  --verbose \\
  --request POST \\
  "https://mqtt.cloud.tencent.com/keep-alive?client-id=curl-x&interval=120"

Response Example

Successful Response Example

{
  "success": true,
  "keepalive": 120
}

Status Code Description

1. Support HTTP Method: POST.
2. Support HTTP/HTTPS.
3. Authenticate via HTTP Basic Authentication or BYOC. See Basic Authentication.
4. Authentication and authorization: The username and password must be valid, and the account must have CONNECT permission.
5. HTTP response:
HTTP Status Code
Description
200
The request is successful.
401
Authentication failed. Username or password is incorrect.
403
Authentication failure, lack of CONNECT permission.
429
Flow control, Too Many Requests.



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

Feedback