notifery

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Notifery

Send notifications to the user via the Notifery API.

通过Notifery API向用户发送通知。

API Configuration

API配置

Base URL:

https://api.notifery.com

(override with

NOTIFERY_API_URL

env var)

Auth:
```
x-api-key: $NOTIFERY_API_KEY
```

At the start of any workflow, verify the API key is set:

bash

test -n "$NOTIFERY_API_KEY" || echo "ERROR: NOTIFERY_API_KEY is not set"

NOTIFERY_API_KEY

is not set, stop and tell the user to set it.

基础URL：
```
https://api.notifery.com
```
（可通过
```
NOTIFERY_API_URL
```
环境变量覆盖）
认证：
```
x-api-key: $NOTIFERY_API_KEY
```

在任何工作流开始前，需验证API密钥已配置：

bash

test -n "$NOTIFERY_API_KEY" || echo "ERROR: NOTIFERY_API_KEY is not set"

如果未设置

NOTIFERY_API_KEY

，请停止操作并告知用户进行配置。

Key Details

关键细节

```
title
```
is the only required field.
If
```
NOTIFERY_DEFAULT_GROUP
```
is set and no
```
group
```
is provided, use it as the default group.

```
title
```
是唯一必填字段。
如果已设置
```
NOTIFERY_DEFAULT_GROUP
```
且未提供
```
group
```
参数，则使用该默认分组。

API Operations

API操作

Send Notification

发送通知

bash

curl -s -f -X POST "${NOTIFERY_API_URL:-https://api.notifery.com}/event" \
  -H "x-api-key: $NOTIFERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "TITLE",
    "message": "MESSAGE",
    "group": "GROUP"
  }'

Only include fields that have values. Omit fields that are not needed.

Parameters:

Parameter	Type	Required	Description
title	string	Yes	Notification title (1-255 chars)
message	string	No	Body text (max 2048 chars)
group	string	No	Group alias (falls back to `NOTIFERY_DEFAULT_GROUP` )
code	number	No	Status code: 0 = success, >0 = error
duration	number	No	Duration in milliseconds
ttl	number	No	Auto-expiry in seconds (60-31536000)
icon	string	No	Icon name
iconColor	string	No	Hex color for icon (e.g. "ff0000")

Response:

{ "ok": true }

on success.

bash

curl -s -f -X POST "${NOTIFERY_API_URL:-https://api.notifery.com}/event" \
  -H "x-api-key: $NOTIFERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "TITLE",
    "message": "MESSAGE",
    "group": "GROUP"
  }'

仅包含有值的字段，省略不需要的字段。

参数说明：

参数名	类型	是否必填	描述
title	字符串	是	通知标题（1-255个字符）
message	字符串	否	正文内容（最大2048个字符）
group	字符串	否	分组别名（默认使用 `NOTIFERY_DEFAULT_GROUP` ）
code	数字	否	状态码：0=成功，>0=错误
duration	数字	否	耗时（毫秒）
ttl	数字	否	自动过期时间（秒，范围60-31536000）
icon	字符串	否	图标名称
iconColor	字符串	否	图标十六进制颜色（例如"ff0000"）

响应：

{ "ok": true }

表示成功。

Error Handling

错误处理

All curl commands use
```
-f
```
to fail on HTTP errors.
If a command fails, check the HTTP status by running without
```
-f
```
and adding
```
-w "\n%{http_code}"
```
.
Common errors: 401 (bad API key), 422 (invalid parameters).

所有curl命令使用
```
-f
```
参数，在HTTP错误时终止。
如果命令执行失败，可去掉
```
-f
```
参数并添加
```
-w "\n%{http_code}"
```
来查看HTTP状态码。
常见错误：401（API密钥无效）、422（参数不合法）。

Proactive Usage

主动通知场景

Send notifications proactively in these situations:

After a long-running task completes (build, deploy, migration).
When a task fails with an error.
When the user explicitly asked to be notified ("let me know when done").

When sending proactively, use

code: 0

for success and

code: 1

for errors.

在以下场景中主动发送通知：

长时间运行的任务完成后（构建、部署、迁移等）。
任务执行出错时。
用户明确要求通知时（例如“完成时告知我”）。

主动发送通知时，成功场景使用

code: 0

，错误场景使用

code: 1

。

Example: Task Completion

示例：任务完成通知

bash

curl -s -f -X POST "${NOTIFERY_API_URL:-https://api.notifery.com}/event" \
  -H "x-api-key: $NOTIFERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"title\": \"Build complete\",
    \"message\": \"Project built successfully in 42s\",
    \"code\": 0,
    \"duration\": 42000
  }"

bash

curl -s -f -X POST "${NOTIFERY_API_URL:-https://api.notifery.com}/event" \
  -H "x-api-key: $NOTIFERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"title\": \"Build complete\",
    \"message\": \"Project built successfully in 42s\",
    \"code\": 0,
    \"duration\": 42000
  }"

Example: Task Failure

示例：任务失败通知

bash

curl -s -f -X POST "${NOTIFERY_API_URL:-https://api.notifery.com}/event" \
  -H "x-api-key: $NOTIFERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"title\": \"Deploy failed\",
    \"message\": \"Error: container health check timed out\",
    \"code\": 1
  }"

bash

curl -s -f -X POST "${NOTIFERY_API_URL:-https://api.notifery.com}/event" \
  -H "x-api-key: $NOTIFERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"title\": \"Deploy failed\",
    \"message\": \"Error: container health check timed out\",
    \"code\": 1
  }"