Overview

The Aliyun Voice notification channel uses the Aliyun Voice Service (VMS) · Voice Notification (SingleCallByTts) API to automatically dial an on-call engineer and play the alert as TTS (text-to-speech). It is typically used for P0 alerts that “must wake someone up”.

• Use case: severe alerts at night or on holidays — phone calls are far more effective than IM at waking people up.
• Prerequisites:
  • An Aliyun account with real-name verification and Voice Service enabled;
  • Aliyun AccessKey ID / AccessKey Secret (RAM sub-account recommended, with only Voice Service send permissions);
  • An approved TTS template (TtsCode / TTS_1234567);
  • (Optional) An applied caller-ID number (CalledShowNumber); if not applied, Aliyun’s default number will be displayed.
• The whole setup has three steps: ① Enable Voice Service on Aliyun and apply for a TTS template → ② Create an Aliyun Voice notification channel in Nightingale → ③ Configure phone numbers for users and pick recipients in the notification rule.

Aliyun Voice Service requires ticket review for TTS templates and caller-ID numbers (typically 1–3 business days). Plan to start a week ahead.

Step 1: Prepare resources in the Aliyun console

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

2. Create a TTS template (voice template):

   • Go to Domestic Voice → Voice Template Management → Add Template;

   • Select template type “Text-to-Speech Template”;

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

   • Recommended template body (simplest, avoids variable-length issues):

     You have an alert ${incident}
     

     After approval, the actual playback will be: You have an alert Incident CPU usage exceeds threshold, press 1 to acknowledge.

   • Submit for review; once approved, you get the template ID TTS_XXXXXXXX.

3. (Optional) Apply for a caller-ID number: go to Number Management → Number Application and apply for a dedicated CalledShowNumber. If not applied, calls go out from Aliyun’s default outbound number.

4. In RAM Access Control, create a sub-account, grant AliyunDyvmsFullAccess, and write down the AccessKey ID and AccessKey Secret (Secret is shown only once — keep it safe).

Step 2: Create an Aliyun Voice notification channel in Nightingale

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

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

3. Fill in the basics:

   

   Section	Field	Edit needed	Notes
   Basic	Name	Yes	e.g. Aliyun Voice; this is what appears when you select the channel in a notification rule
   Variables	Contact Method	Keep default Phone	Voice notifications must use the user’s phone number as $sendto
   HTTP	URL	Keep default	https://dyvmsapi.aliyuncs.com (fixed VMS domain)
   HTTP	Method	POST
   HTTP	Headers	Keep default	Content-Type: application/json, Host: dyvmsapi.aliyuncs.com — required by signing, do not delete

4. Scroll down to “Request Parameters” — this is the only place you need to edit:

   

   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; keep it safe
   CalledNumber	{{ $sendto }}	Keep default; replaced with the recipient’s phone at send time
   CalledShowNumber	Your caller-ID or empty	If you have not applied for a caller-ID, delete this entire row; Aliyun will dial out using a default number
   TtsCode	TTS_XXXXXXXX	The voice template ID from Step 1
   TtsParam	{"incident":"Incident {{$tpl.incident}}, press 1 to acknowledge"}	Variable assignment for the template, as a JSON string; the left-side key (here incident) must match the ${xxx} variable name in the Aliyun TTS template exactly. {{$tpl.incident}} comes from the built-in Aliyun Voice 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 request before sending — they never appear in the actual call 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 calls (must be 11-digit Chinese mobile numbers; international roaming requires separate enablement on Aliyun).
2. Go to Notification → Notification Rules → New:
   • Notification Channel: pick the Aliyun Voice channel;
   • Message Template: pick the built-in Aliyun Voice — its incident field renders as {{$event.RuleName}} by default (just the rule name, the shortest form). Combined with the default request body TtsParam = {"incident":"Incident {{$tpl.incident}}, press 1 to acknowledge"}, the variable value finally sent to Aliyun is roughly Incident <rule name>, press 1 to acknowledge;
   • Recipients / Recipient Teams: pick target users (users must already have a phone number);
   • Applicable Severity: we recommend ticking only Critical (severity 1);
   • Save.
3. Click “Notification Test”; the test phone should ring within 10 seconds and play back a TTS alert message.

Aliyun-side billing and quotas

• Voice notifications are billed by call duration; see Aliyun Voice Service Pricing.
• Each calendar day has a default cap on calls per number (raisable via ticket). Connection rate and call duration can be checked under “Usage Statistics” in the Aliyun console.
• After answering, if the callee presses a key (e.g. press “1” to acknowledge), Aliyun delivers the keypress event to a callback URL you have registered — Nightingale v8 does not handle this callback by default; if you really need acknowledgement, you must build a callback Webhook yourself.

FAQ

Q1: Returns InvalidAccessKeyId.NotFound / SignatureDoesNotMatch?

A: Wrong AK or Secret. Common causes:

• Pasting the sub-account’s Display Name as the AK ID;
• Extra spaces / newlines in the pasted AK Secret;
• The sub-account’s RAM policy does not authorize Voice Service — AliyunDyvmsFullAccess is missing.

Q2: Returns isv.SMART_INVALID_APP_KEY / TtsCode Invalid?

A: Wrong TtsCode, or the voice template has not been approved. Sign in to the Voice Service console → Voice Template Management and confirm the template status is Approved.

Q3: TtsParam returns TtsParam variable not match?

A: Keys in TtsParam must match the ${xxx} parts in the voice template exactly, and all variables must have values. For example, for template You have an alert ${incident}, press ${button} to acknowledge, TtsParam must be written as {"incident":"...","button":"1"}.

Q4: isv.MOBILE_NUMBER_ILLEGAL?

A: Wrong phone-number format. Voice Service requires 11-digit Chinese mobile numbers without country code; international numbers require a separate ticket.

References

• Aliyun Voice Service · SingleCallByTts documentation
• Aliyun Voice Service · TTS template specification
• Aliyun Voice Service · Error codes