Creates an instance of the Pushover client.
Your Pushover application's API token. Found on your Pushover dashboard.
Cancels the retries for an emergency priority message that has not yet been acknowledged.
The receipt ID of the emergency message whose retries should be cancelled.
Optionalverbose: booleanOptional flag for logging.
A Promise resolving to a basic PushoverResponse. Check status for success (1) or failure (0).
Cancels the retries for all emergency priority messages associated with a specific tag that have not yet been acknowledged.
The tag associated with the emergency messages (set in emergencyOpts.tags during send).
Optionalverbose: booleanOptional flag for logging.
A Promise resolving to a PushoverTagCancellationResponse indicating the number of messages cancelled.
const tagName = "critical-db-alert";
const cancelByTagResponse = await pushover.cancelRetriesByTag(tagName);
if (cancelByTagResponse.status === 1) {
console.log(
`Successfully cancelled ${cancelByTagResponse.canceled} messages with tag: ${tagName}`,
);
} else {
console.error("Failed to cancel by tag:", cancelByTagResponse.errors);
}
Checks the status of an emergency priority message using its receipt ID. Allows querying whether the message has been acknowledged, expired, or if the callback was triggered.
The receipt ID obtained from the PushoverMessageResponse when sending an emergency message.
Optionalverbose: booleanOptional flag for logging.
A Promise resolving to a PushoverReceiptResponse object containing the status details.
const receiptId = "RECEIPT_ID_FROM_SEND_RESPONSE";
const status = await pushover.checkReceipt(receiptId);
if (status.status === 1) {
console.log(
`Acknowledged: ${status.acknowledged} by ${status.acknowledged_by}`,
);
console.log(`Expired: ${status.expired}`);
} else {
console.error("Failed to check receipt:", status.errors);
}
Sends a Pushover notification to one or more recipients.
A PushoverMessage object containing the notification details.
OptionalemergencyOpts?: { callback?: string; expire: number; retry: number; tags?: string[] }Emergency priority options, required when priority is 2.
Optionalcallback?: stringAn optional callback URL that Pushover servers will send a request to when the notification has been acknowledged.
Specifies how long (in seconds) the notification will continue to be resent. Maximum value is 10800 seconds (3 hours).
Specifies how often (in seconds) the Pushover servers will send the same notification to the user. Minimum value is 30 seconds.
Optionaltags?: string[]Optional tags for emergency notifications. Helps with cancelling retries.
Optionalhtml?: booleanIf set to true, the message content will be treated as HTML.
Mutually exclusive with monospace.
Optionallink?: string | { title?: string; url: string }An optional link attached to the message. Can be either a simple URL string or an object containing the URL and an optional display title.
The message content sent to the user. Must be at least 3 characters long.
Optionalmonospace?: booleanIf set to true, the message content will be displayed using a monospace font.
Mutually exclusive with html.
Optionalpriority?: 0 | 1 | 2 | -2 | -1Sets the notification priority for the message. Defaults to 0 (normal priority).
emergencyOpts.Optionalsound?: stringThe name of one of the predefined Pushover sounds or a custom sound uploaded by the user to be played for the notification.
Optionaltimestamp?: numberAn optional Unix timestamp representing the message's date and time to display to the user, rather than the time Pushover received it.
Optionaltitle?: stringAn optional title for the message.
Optionalttl?: numberTime To Live in seconds. Specifies how long the message will be kept until disappearing.
A SendOptions object specifying the recipients and optional settings.
A Promise resolving to an array of PushoverMessageResponse objects, one for each recipient.
Rejects if message validation fails or if there's a fundamental issue sending to all recipients.
Individual recipient failures are indicated within their respective response objects (status: 0).
// Send a message to a specific user and device
const userRecipient: PushoverRecipient = { id: "user-key", devices: ["phone"] };
await pushover.send(
{ message: "Targeted message" },
{ recipients: [userRecipient] },
);
// Send an emergency priority message and handle the receipt
const responses = pushover.send(
{
message: "Emergency alert!",
priority: 2,
emergencyOpts: { retry: 30, expire: 3600 },
},
{ recipients: [userRecipient] },
);
responses
.then((responses) => {
console.log(
`Emergency message sent. Receipts: ${responses.map((response) => response.receipt).join(", ")}`,
);
// Store the receipt to check status or cancel later
})
.catch((error) => {
console.error("Failed to send emergency message:", error);
});
Validates a Pushover user key and optionally a specific device name associated with that user. Useful for verifying recipient details before sending messages.
A ValidateOptions object containing the user key and optional deviceName.
A Promise resolving to a PushoverValidationResponse object.
Check the status field (1 for valid, 0 for invalid) and errors for details on failure.
On success, devices and licenses may be populated.
// Validate a user key
const validation = await pushover.validate({ user: "user-key" });
if (validation.status === 1) {
console.log(
"User is valid. Devices:",
validation.devices,
", Licenses:",
validation.licenses,
);
} else {
console.error("Validation failed:", validation.errors);
}
// Validate a user and device
const deviceValidation = await pushover.validate({
user: "user-key",
deviceName: "phone",
});
console.log("Device validation status:", deviceValidation.status);
Main class for interacting with the Pushover API (v1). Provides methods for sending notifications, validating users/devices, and managing emergency priority messages.
Param: token
Your Pushover application's API token.
Example