Overview

The Aliyun SMS notification channel uses the Aliyun SMS Service · SendSms API to push alerts to mobile phones as plain text messages. It is typically used as a fallback for email/IM — even on devices without IM apps, SMS still gets through.

• Use case: backup notification for ops on-call, alerts to executives/clients who do not install IM apps.
• Prerequisites:
  • An Aliyun account that has completed real-name verification and has SMS Service enabled;
  • Aliyun AccessKey ID / AccessKey Secret (RAM sub-account recommended);
  • An approved SMS Signature SignName (e.g. “Nightingale Monitoring”);
  • An approved SMS Template TemplateCode (in the form SMS_123456789).
• The whole setup has three steps: ① Apply for the signature and template on Aliyun → ② Create an Aliyun SMS notification channel in Nightingale → ③ Configure phone numbers for users and pick recipients in the notification rule.

Aliyun SMS signatures and templates both require ticket review (1–3 business days), and different industries face different content requirements. We recommend applying for several backup templates upfront.

Step 1: Prepare resources in the Aliyun console

1. Sign in to the Aliyun SMS Service Console; first-time users need to enable the service.

2. Apply for an SMS Signature: go to Domestic Messages → Signature Management → Add Signature. Enterprise users should fill in the company short name as it appears on the business license; individual users can only use a personal name, app name, etc.

3. Apply for an SMS Template: go to Domestic Messages → Template Management → Add Template.

   • Set template type to “Notification SMS” (alert scenarios cannot use “Marketing SMS”);

   • Important: the variable name must be incident, because Nightingale’s preset request body uses TemplateParam = {"incident":"Incident {{$tpl.incident}}, please handle promptly"} — meaning the entire string “Incident + rule name + , please handle promptly” is passed to Aliyun as the value of ${incident};

   • Recommended template body (simplest):

     You have an alert ${incident}
     

     After approval, the SMS the user receives will be: [Your Signature] You have an alert Incident CPU usage exceeds threshold, please handle promptly.

   • Submit for review; once approved, you get a SMS_XXXXXXXX.

4. In RAM Access Control, create a sub-account, grant AliyunDysmsFullAccess, and write down the AccessKey ID / AccessKey Secret.

Step 2: Create an Aliyun SMS notification channel in Nightingale

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

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

3. Fill in the basics:

   

   Section	Field	Edit needed	Notes
   Basic	Name	Yes	e.g. Aliyun SMS
   Variables	Contact Method	Keep default Phone	SMS uses the user’s phone number as $sendto
   HTTP	URL	Keep default	https://dysmsapi.aliyuncs.com
   HTTP	Method	POST
   HTTP	Headers	Keep default	Content-Type: application/json, Host: dysmsapi.aliyuncs.com — required by signing, do not delete

4. Scroll down to “Request Parameters” and replace the placeholders with your real values:

   

   Parameter	Value	Notes
   AccessKeyId	Your AK ID	The LTAI5t... from Step 1 RAM console
   AccessKeySecret	Your AK Secret	The corresponding Secret
   PhoneNumbers	{{ $sendto }}	Keep default; replaced with the recipient’s phone number at send time
   SignName	Your SMS signature	The approved signature name from Step 1; copy it exactly, character by character
   TemplateCode	SMS_XXXXXXXX	The approved template ID from Step 1
   TemplateParam	{"incident":"Incident {{$tpl.incident}}, please handle promptly"}	A JSON string; the left-side key (here incident) must match the ${xxx} variable name in your Aliyun template exactly. {{$tpl.incident}} comes from the built-in Aliyun SMS message template (defaults to {{$event.RuleName}})

   The Nightingale backend automatically computes the ACS3-HMAC-SHA256 signature using your AK/SK, and strips AccessKeyId / AccessKeySecret from the query before the call — they never appear in the actual request in plain text.

5. Click Save.

Step 3: Configure phone numbers and the notification rule

1. Go to Organization → User Management and fill in the phone number field for users who need to receive SMS (11-digit Chinese mobile numbers; international numbers require separately enabling international SMS).
2. Go to Notification → Notification Rules → New:
   • Notification Channel: pick the Aliyun SMS channel;
   • Message Template: pick the built-in Aliyun SMS — its incident field renders as {{$event.RuleName}} by default, and combined with the default request body TemplateParam = {"incident":"Incident {{$tpl.incident}}, please handle promptly"}, the value of ${incident} finally sent to Aliyun is roughly Incident <rule name>, please handle promptly;
   • Recipients / Recipient Teams: pick target users;
   • Applicable Severity / Time Range: filter as needed;
   • Save.
3. Click “Notification Test”; if the parameters are correct, the phone receives an SMS within seconds in the form [Your Signature] You have an alert xxx.

Aliyun-side billing and compliance

• SMS is billed per message, 70 characters per message; longer content is split into multiple billed messages. See Aliyun SMS Pricing.
• The actual SMS content must match the approved template body exactly. Text not in the template, or rejected keywords, will be blocked by Aliyun (returning isv.OUT_OF_SERVICE or isv.ILLEGAL_CONTENT).
• Each signature + template pair has rate limits per phone number (defaults: 5/min, 10/hour, 50/24h; notification templates can be raised via ticket).

FAQ

Q1: Returns SignatureDoesNotMatch?

A: Either the AK Secret is wrong, or the signature contains invisible characters (newlines, spaces).

Q2: Returns isv.SMS_SIGNATURE_ILLEGAL / “signature illegal”?

A: The SignName value does not exactly match the approved signature; check spaces, punctuation, and Chinese vs. English brackets. The signature field must match strictly.

Q3: Returns isv.OUT_OF_SERVICE / isv.ILLEGAL_CONTENT?

A: The template body does not match the approved version, or contains sensitive words. Go back to the Aliyun console, open the template details, look at “Original Template Content”, and keep the value of TemplateParam consistent with that context.

Q4: Returns isv.MOBILE_NUMBER_ILLEGAL?

A: The user’s phone number format is wrong. Domestic numbers should be 11 digits only (without +86); international numbers must use SendMessageToGlobe (a different API — you need to create another channel with manually edited URL and action).

Q5: I want the SMS to include rule name + trigger value + time, but my template only takes one variable?

A:

• Option 1: apply for a template with multiple variables, e.g. [${name}] ${level} alert: ${detail}, and assign each value in TemplateParam;
• Option 2: have {{$tpl.incident}} render a compact line of text (under 20 characters) inside the message template, then stuff it into the single variable.

Q6: I want one alert to fan out to multiple people in a single call?

A: Aliyun SendSms supports up to 1000 phone numbers per call, but Nightingale currently loops through recipients, one per call. For large recipient lists, raise the “retry interval” appropriately to avoid rate limiting.

References

• Aliyun SMS · SendSms documentation
• Aliyun SMS · Template specification
• Aliyun SMS · Error codes