Overview

The Tencent Cloud SMS notification channel uses the Tencent Cloud SMS · SendSms API to deliver alerts to phones as plain text messages. It is commonly used as a fallback for email/IM.

• Use case: must-deliver notifications, users who do not install IM apps, on-call shift handover reminders, and so on.
• Prerequisites:
  1. An account that has enabled Tencent Cloud SMS;
  2. Tencent Cloud SecretId / SecretKey (CAM sub-account recommended, with only SMS send permissions);
  3. SmsSdkAppId (the SMS app ID, created in the SMS console);
  4. An approved SMS Signature and SMS Template.
• The whole setup has three steps: ① Prepare the app/signature/template in the Tencent Cloud console → ② Create a Tencent Cloud SMS notification channel in Nightingale → ③ Fill in user phone numbers and pick recipients in the notification rule.

Signatures and templates require ticket review (typically a few hours up to one business day). Plan ahead for first-time onboarding.

Step 1: Prepare resources in the Tencent Cloud console

1. Sign in to the Tencent Cloud SMS Console.
2. Create an SMS app: go to App Management → Create App, and you get an SmsSdkAppId (a numeric string).
3. Create an SMS signature: Signature Management → Create Signature, and follow the prompts to submit corporate/personal qualification for review.
4. Create an SMS template: Body Template → Create Body Template.
   • Set the template type to “Notification”;
   • Important: the template can only have a single variable {1}, because Nightingale’s preset request body uses TemplateParamSet = ["{{$tpl.content}}"] — only one value is passed, mapped to {1}.
   • Put the boilerplate phrasing inside the template, and let {1} carry only the variable part:

     You have a {1} severity alert, please handle promptly
     

     Then go to Nightingale → Message Templates → make a copy of Tencent SMS, and edit the content field to whatever you want to drop into {1}.
   • Once approved, you get the TemplateId (a numeric ID).
5. In CAM, create a sub-account, grant the policy QcloudSMSFullAccess (or a least-privilege custom policy), and write down the SecretId / SecretKey.

Step 2: Create a Tencent Cloud SMS notification channel in Nightingale

1. Sign in to Nightingale → left menu Notification → Notification Channels.

2. In the type panel on the left, click Tencent Cloud SMS to enter the create page (URL /notification-channels/add?ident=tx-sms).

3. Fill in the basics:

   Field	Notes
   Name	e.g. Tencent Cloud SMS
   Contact Method	Keep default Phone
   URL	Keep default https://sms.tencentcloudapi.com
   Method	POST

4. In Headers, in addition to the usual Content-Type / Host, Tencent Cloud also requires auth-related fields:

   

   Parameter	Value	Edit needed
   Content-Type	application/json	Keep default
   Host	sms.tencentcloudapi.com	Keep default
   Secret_ID	Your SecretId	Yes
   Secret_Key	Your SecretKey	Yes
   Service	sms	Keep default
   X-TC-Action	SendSms	Keep default
   X-TC-Region	Your region	Yes, e.g. ap-guangzhou / ap-beijing; fill in the region where your SMS app lives
   X-TC-Version	2021-01-11	Keep default

   Secret_ID / Secret_Key are not transmitted in plain text: before sending, Nightingale uses them to compute the TC3-HMAC-SHA256 signature, then strips them from the request headers.

5. Finally, edit the “Request Body”, replacing the placeholders with your real values:

   {
     "PhoneNumberSet": ["{{ $sendto }}"],
     "SignName": "Replace with the actual signature",
     "SmsSdkAppId": "Replace with the actual app ID",
     "TemplateId": "Replace with the actual template ID",
     "TemplateParamSet": ["{{$tpl.content}}"]
   }
   

   Field	Value	Notes
   PhoneNumberSet	["{{ $sendto }}"]	Keep default — replaced with the recipient’s phone at send time; domestic numbers must be in E.164 format, i.e. +86138XXXXXXXX (see Q4)
   SignName	Your SMS signature	The approved signature name from Step 1, character-for-character
   SmsSdkAppId	Your app ID	The numeric ID from Step 1
   TemplateId	Your template ID	The approved numeric ID from Step 1
   TemplateParamSet	["{{$tpl.content}}"]	An array, one entry per template variable in order — Nightingale defaults to passing only one value, so your Tencent Cloud SMS template can only have a single {1}. {{$tpl.content}} comes from the built-in Tencent SMS message template; defaults to Severity: S<level> {Triggered/Recovered}Rule: <rule name>

6. Click Save.

Step 3: Configure phone numbers and the notification rule

1. Go to Organization → User Management and fill in phone numbers for target users.

   Two formats work for domestic numbers:

   • The 11-digit form 138XXXXXXXX (recommended), with {{ $sendto }} in PhoneNumberSet changed to "+86{{ $sendto }}" in the request body;
   • Or store the full +86138XXXXXXXX, and keep the request body default.

2. Go to Notification → Notification Rules → New:

   • Notification Channel: pick Tencent Cloud SMS;
   • Message Template: pick the built-in Tencent SMS — its content field renders as Severity: S<level> {Triggered/Recovered}Rule: <rule name> by default, e.g. Severity: S1 TriggeredRule: CPU usage exceeds threshold. Combined with the default request body TemplateParamSet = ["{{$tpl.content}}"], this string becomes the value of {1} sent to Tencent Cloud;
   • Note: SMS is billed at 70 characters per message; if the rule name + severity is too long, copy the Tencent SMS template and shorten it;
   • Recipients / Recipient Teams: pick target users;
   • Applicable Severity / Time Range: filter as needed;
   • Save.

3. Click “Notification Test”; the phone should receive an SMS within seconds in the form [Signature] You have an alert xxx.

Billing and compliance

• Billed by successfully delivered messages, 70 characters per message. See Tencent Cloud SMS Pricing.
• Each phone number has a rate limit (defaults: 1 per minute, 10 per day for the same signature + template); notification templates can be raised via ticket.
• The actual SMS body must match the approved template exactly, otherwise it will be blocked (FailedOperation.InsertAuthFail / FailedOperation.TemplateIncorrectOrUnapproved).

FAQ

Q1: AuthFailure.SignatureFailure?

A: Wrong Secret_Key, or large local clock drift. Make sure the server time is NTP-synced.

Q2: FailedOperation.TemplateIncorrectOrUnapproved / template not approved?

A:

• Wrong TemplateId;
• The template has not been approved;
• The length of TemplateParamSet does not match the number of template variables.

Q3: FailedOperation.SignatureIncorrectOrUnapproved / signature error?

A: SignName does not exactly match the approved signature (watch for spaces, brackets, half-width vs. full-width characters).

Q4: InvalidParameterValue.InvalidPhoneNumber?

A: Tencent Cloud requires E.164 format (+86...). Two options:

• Store users’ phone numbers as +86138XXXXXXXX directly;
• Or change {{ $sendto }} to +86{{ $sendto }} in the request body to add the prefix automatically.

Q5: FailedOperation.InsufficientBalance?

A: Insufficient account balance — top up and configure a balance alert in the console.

Q6: LimitExceeded.PhoneNumberCountLimit — too many numbers in one call?

A: SendSms accepts up to 200 numbers per call. By default Nightingale loops through recipients, one per call. If you want to pack multiple numbers into one request, change the request body to:

{
  "PhoneNumberSet": {{batchContactsJsonMarshal $sendtos}},
  "SignName": "...",
  "SmsSdkAppId": "...",
  "TemplateId": "...",
  "TemplateParamSet": ["{{$tpl.content}}"]
}

Note: in this mode, all numbers receive the exact same SMS content.

Q7: International SMS?

A: For international numbers, just prefix the country code (e.g. +6587654321); but you must enable international SMS separately in the Tencent Cloud console and use an international SMS template.

References

• Tencent Cloud SMS · SendSms API documentation
• Tencent Cloud SMS · Template specification
• Tencent Cloud API · TC3-HMAC-SHA256 signing