> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 预定发送

> 稍后发送任何消息，一次或每天、每周或每月重复发送，并通过 /send/schedule进行管理。

![GOWA Message Scheduler Overview](https://mintcdn.com/gowa-docs/G0gUpNl3gUGyehVX/images/GOWA-Message-Scheduler-Overview.png?fit=max\&auto=format\&n=G0gUpNl3gUGyehVX\&q=85\&s=663bfdbb9e1c0bb451c0fa782380b139)

任何发送请求都可以定时执行。添加 `scheduled_at` 和 `timezone` 后，GOWA 会存储该请求，并由后台工作进程在指定时间发送。定时任务会在重启后保留；如果设备离线，则会等待设备上线。

可定时发送的消息类型：文本、图片、文件、视频、音频、贴纸、联系人、链接、位置、投票和转发（`/message/{id}/forward`）。在线状态、正在输入提示和实验性端点 `/send/interactive` 不支持定时执行。

## 计划字段

| 字段 | 必填 | 描述 |
| - | - | - |
| `scheduled_at` | 是的 | 首次发送时间，采用 RFC 3339 格式，且必须是未来的时间，例如 `2026-11-01T09:00:00+07:00`。首次发送始终在此时间执行。 |
| `timezone` | 是的 | IANA区域 (例如`Asia/Jakarta`) 用于计算重复，所以"每天09:00"在DST change中保留09:00。 |
| `recurrence` | 否 | `once` (默认), `daily`, `weekly` 或 `monthly` 。 |
| `weekdays` | 每周的 | 要发送的天数，`0` = 星期日 … `6` = 星期六，例如，`[1, 3, 5]` 。 |
| `day_of_month` | 每月的 | `1`–`31`；若月份天数不足，则调整为该月最后一天。 |
| `end_at` | 否 | 仅重复。这段时间后没有发送。 |
| `occurrence_limit` | 否 | 仅重复。多次发送后停止。 |

没有`scheduled_at`，请求将会像往常一样立即发送。

## 示例：

```bash theme={null}
# once, tomorrow morning
curl -u admin:changeme -X POST http://localhost:3000/send/message \
  -H "Content-Type: application/json" -H "X-Device-Id: my-device" \
  -d '{
    "phone": "628123456789",
    "message": "Reminder: meeting at 10:00",
    "scheduled_at": "2026-11-01T09:00:00+07:00",
    "timezone": "Asia/Jakarta"
  }'
```

```json theme={null}
{
  "code": "SUCCESS",
  "message": "Success",
  "results": {
    "schedule_id": "0b5c3a8e-7f5d-4d6f-9d1e-2f8c1a7b9e10",
    "scheduled_at": "2026-11-01T02:00:00Z",
    "next_run_at": "2026-11-01T02:00:00Z"
  }
}
```

计划中的响应有 `schedule_id` 而不是 `message_id` 。

```bash theme={null}
# every Monday, Wednesday and Friday at 08:30, 12 times
curl -u admin:changeme -X POST http://localhost:3000/send/message \
  -H "Content-Type: application/json" -H "X-Device-Id: my-device" \
  -d '{
    "phone": "120363025246125486@g.us",
    "message": "Standup in 30 minutes",
    "scheduled_at": "2026-11-02T08:30:00+07:00",
    "timezone": "Asia/Jakarta",
    "recurrence": "weekly",
    "weekdays": [1, 3, 5],
    "occurrence_limit": 12
  }'
```

```bash theme={null}
# monthly invoice on the 1st, with an uploaded file (multipart: repeat weekdays as separate fields if used)
curl -u admin:changeme -X POST http://localhost:3000/send/file \
  -H "X-Device-Id: my-device" \
  -F phone=628123456789 \
  -F file=@invoice.pdf \
  -F scheduled_at=2026-12-01T09:00:00+07:00 \
  -F timezone=Asia/Jakarta \
  -F recurrence=monthly \
  -F day_of_month=1 \
  -F end_at=2027-12-31T23:59:59+07:00
```

上传的文件会保留在服务器上，直到定时任务结束。在 multipart 请求体中，请通过重复字段发送 `weekdays`（`-F weekdays=1 -F weekdays=3`）。

## 管理计划表

定时任务归属于某台设备；请发送相同的 `X-Device-Id`。

| 行 动 | 请求 |
| - | - |
| 列表 | `GET /send/schedules`，带可选`status`、`search`(收件人或文本)、`message_type`、`limit`、`offset` |
| 获取一个 | `GET /send/schedules/{schedule_id}` |
| 暂停 | `POST /send/schedules/{schedule_id}/pause` |
| 恢复 | `POST /send/schedules/{schedule_id}/resume` |
| 取消 | `POST /send/schedules/{schedule_id}/cancel` |

```bash theme={null}
curl -u admin:changeme -H "X-Device-Id: my-device" \
  "http://localhost:3000/send/schedules?status=active&limit=25"
```

列表返回 `results.data` 和 `results.pagination`（`limit`，默认为 25；`offset`；`total`）。

### Statuses

| 状态 | 含义 |
| - | - |
| `active` | 正在等待其下次运行。 |
| `running` | 该工人声称并正在发送。 |
| `paused` | 一直保持直到恢复。 |
| `completed` | 没有剩余的运行。 |
| `failed` | 检索完成后，或者存储的请求无效。 |
| `cancelled` | 被您取消。 |

## 送货行为

* 工人每5秒检查到期时间。
* **设备离线或未登录：** 运行等待并每30秒重试一次。 等待不会计为失败的尝试，所以一个时间表会持续很长时间。
* **发送错误：** 采用退避机制重试，间隔从 15 秒开始，最长为 5 分钟，每次计划执行最多尝试 10 次。之后，重复任务会跳至下次执行时间；一次性任务则变为 `failed`。
* **无效的请求** (例如一个坏的收件人)：在没有重试的情况下立即失败。
* **延迟运行：** 未发送一个事件延迟通过 `end_at` 。
* **崩溃和重启：** 关闭不会中止已经在飞行中的发送。在第一次尝试之前，GOWA仍然存在一个 WhatsApp 消息ID。 在其2分钟的索赔到期后，中断的事件通常与同一ID合并，并计入尝试预算。 调查还会在所有检索中保留加密密。这会在确认含糊不清后保存消息身份，但不会保证一旦交货。
* \*\*较早中断的尝试：\*\*遗留下来但结果未知的尝试保留了保守的恢复。 工人跳过重复计划或一次性计划而不是给它分配一个新的消息身份。

## 超过 MCP

MCP 工具 `whatsapp_send` 接受相同的定时字段，`whatsapp_schedule` 则用于列出、获取、暂停、恢复和取消定时任务。参阅 [MCP 服务器](https://gowa-docs.mintlify.site/zh/integrations/mcp.md)。

> [!NOTE]
>
> 检查`GET /app/info`: `results.scheduled_sends` 是`true` 当服务器接受schedule字段并暴露`/send/schedules`时。


## Related topics

- [预定发送列表列表](https://gowa-docs.mintlify.site/zh/api-reference/send/预定发送列表列表.md)
- [恢复已暂停的预定发送](https://gowa-docs.mintlify.site/zh/api-reference/send/恢复已暂停的预定发送.md)
- [暂停预定的发送](https://gowa-docs.mintlify.site/zh/api-reference/send/暂停预定的发送.md)
- [取消预定的发送](https://gowa-docs.mintlify.site/zh/api-reference/send/取消预定的发送.md)
- [获得预定的发送](https://gowa-docs.mintlify.site/zh/api-reference/send/获得预定的发送.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.