- 快猫星云Flashcat

Place a phone call to on-call engineers and play back alerts via Tencent Cloud Voice Service (VMS · SendTtsVoice). Beginners can finish the setup step by step.

Overview

The Tencent Cloud Voice notification channel uses the Tencent Cloud VMS (Voice Message Service) · SendTtsVoice API to automatically dial on-call engineers and play alerts as TTS (text-to-speech). It is used for the most time-critical severe alerts — phone calls wake people up far better than SMS or IM.

Use case: P0 alerts at night or on holidays, fault notifications that require forced reach.
Prerequisites:
1. A Tencent Cloud account that has completed real-name verification and enabled VMS;
2. Tencent Cloud SecretId / SecretKey (CAM sub-account recommended);
3. An approved voice template TemplateId;
4. A created VoiceSdkAppid (voice app ID, created in the VMS console).
The whole setup has three steps: ① Enable VMS on Tencent Cloud and apply for a voice template → ② Create a Tencent Cloud Voice notification channel in Nightingale → ③ Fill in user phone numbers and pick recipients in the notification rule.

Tencent Cloud VMS templates and signatures require ticket review (1–3 business days).

Step 1: Prepare resources in the Tencent Cloud console

Sign in to the Tencent Cloud Voice Message Console; first-time users need to enable the service.
Create a voice app: go to App Management → Create App, and you get a VoiceSdkAppid (a 7-digit number).
Create a voice template:
- Under App Management → Your App → Body Template, apply for a TTS template;
- 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} in the template.
- Put the boilerplate phrasing inside the template, and let {1} carry only the variable part:
```
You have an alert: {1}, please handle promptly
```
  Then go to Nightingale → Message Templates → make a copy of Tencent Voice and shorten the content field (e.g. change it to {{$event.RuleName}}).
- Submit for review; once approved, you get the TemplateId (a numeric string, e.g. 1234567).
In CAM Access Management · Sub-account, create a sub-account, grant the policy QcloudVMSFullAccess (or equivalent), and write down the SecretId / SecretKey (shown only once at creation).

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

Sign in to Nightingale → left menu Notification → Notification Channels.
In the type panel on the left, click Tencent Cloud Voice to enter the create page (URL /notification-channels/add?ident=tx-voice).

Fill in the basics:

Tencent Cloud Voice basic configuration

Section	Field	Edit needed	Notes
Basic	Name	Yes	e.g. `Tencent Cloud Voice`
Variables	Contact Method	Keep default `Phone`	At send time, `$sendto` takes the user’s phone number
HTTP	URL	Keep default	`https://vms.tencentcloudapi.com` (fixed VMS domain)
HTTP	Method	`POST`

In Headers, in addition to the usual Content-Type / Host, Tencent Cloud-specific auth fields also live here — these are the only ones you need to edit:

Tencent Cloud Voice headers

Parameter	Value	Edit needed
`Content-Type`	`application/json`	Keep default
`Host`	`vms.tencentcloudapi.com`	Keep default
`Secret_ID`	Your SecretId	Yes, the AKID from Step 1 CAM
`Secret_Key`	Your SecretKey	Yes
`Service`	`vms`	Keep default
`X-TC-Action`	`SendTtsVoice`	Keep default
`X-TC-Region`	`ap-beijing`	Adjust to where your voice app lives; common values: `ap-guangzhou` / `ap-beijing` / `ap-nanjing`
`X-TC-Version`	`2020-09-02`	Keep default (API version)

Note: although Secret_ID / Secret_Key are placed in “Headers”, before sending Nightingale extracts them to compute the TC3-HMAC-SHA256 signature and strips them from the actual request headers — they are never sent to Tencent Cloud in plain text.

Scroll to “Request Body”. The default template is already filled in:

{
  "CalledNumber": "+86{{ $sendto }}",
  "TemplateId": "Replace with the actual template ID",
  "TemplateParamSet": ["{{$tpl.content}}"],
  "VoiceSdkAppid": "Replace with the actual app ID"
}

Replace the placeholders with your real values:

Field	Value	Notes
`CalledNumber`	`+86{{ $sendto }}`	Keep default — must include the `+86` prefix (international E.164 format)
`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 template can only have a single `{1}`. `{{$tpl.content}}` comes from the built-in `Tencent Voice` message template; defaults to `S<level>{Triggered/Recovered}<rule name>`
`VoiceSdkAppid`	Your AppID	The 7-digit number from Step 1

Click Save.

Step 3: Configure phone numbers and the notification rule

Go to Organization → User Management and fill in phone numbers for users who need to take calls (11-digit domestic numbers, without the +86 prefix — the prefix is added by the request body automatically).
Go to Notification → Notification Rules → New:
- Notification Channel: pick the Tencent Cloud Voice channel;
- Message Template: pick the built-in Tencent Voice — its content field renders as S{{$event.Severity}}{{if $event.IsRecovered}}Recovered{{else}}Triggered{{end}}{{$event.RuleName}} by default, e.g. S1Triggered 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: the length of {{$tpl.content}} must stay within Tencent Cloud’s per-variable limit (default ≤ 30 characters); if the rule name is very long, copy and shorten the Tencent Voice template before use;
- Recipients / Recipient Teams: pick target users;
- Applicable Severity: we recommend ticking only Critical (severity 1);
- Save.
Click “Notification Test”; the target phone should ring within 10 seconds and play back a TTS alert message.

Tencent Cloud-side billing and quotas

VMS is billed by call duration / count; see Tencent Cloud VMS Pricing.
Each phone number has a daily call cap (low by default); raise it via ticket.
If the callee presses a key (e.g. press 1 to acknowledge), Tencent Cloud calls back the URL you have registered — Nightingale does not handle this callback by default; if you need an acknowledgement workflow, build it yourself.

FAQ

Q1: Returns AuthFailure.SignatureFailure?

A: Wrong Secret_Key, or large clock drift on the machine (TC3 signing is time-sensitive — anything beyond ±5 minutes fails). Check the server NTP time.

Q2: Returns UnauthorizedOperation / CAM?

A: The sub-account does not have QcloudVMSFullAccess attached, or the SecretId belongs to an account that has not enabled VMS.

Q3: Returns FailedOperation.InvalidTemplate / template not approved?

A: Check that TemplateId is correct; sign in to the VMS console and confirm the template status is “Approved”.

Q4: Returns FailedOperation.InsufficientBalance?

A: Insufficient account balance — top up or set a top-up alert.

Q5: Returns InvalidParameterValue.InvalidCalledNumber?

A: CalledNumber must be E.164 format; for domestic numbers write +861XXXXXXXXXX. The default Nightingale template already prepends +86 to {{ $sendto }} — do not double-prepend.

Q6: What error if the TemplateParamSet array length does not match the template?

A: Tencent Cloud returns InvalidParameterValue.TemplateParamSet. Open the VMS template, count how many {1} {2} {3} placeholders there are, and make the array the same length; and no entry can be empty.

Q7: How are multiple recipients scheduled?

A: SendTtsVoice only dials one number per call; Nightingale calls recipients one by one. For a long list, raise the “retry interval” appropriately (e.g. 500 ms) to avoid concurrency limits.

Q8: I’m using an overseas account / international numbers?

A: Tencent Cloud’s international voice service (SendCallVoice, etc.) is a different product line, and the default Nightingale ident does not cover it. For international voice, change the URL on the channel to the international endpoint, change X-TC-Action to the corresponding API name, and fill CalledNumber in international format.