> ## 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.

# Envíos programados

> Envía cualquier mensaje más tarde, una vez o en una repetición diaria, semanal o mensual, y gestiona programas a través de /send/schedules.

![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)

Cualquier solicitud de envío puede ser programada en lugar de ser enviada inmediatamente. Añade `scheduled_at` y `timezone`; GOWA almacena la solicitud y un trabajador de fondo la envía en ese momento. Los programas sobreviven a los reinicios y esperan un dispositivo sin conexión.

Tipos de mensajes programables: texto, imagen, archivo, vídeo, audio, sticker, contacto, enlace, ubicación, encuestas y reenvío (`/message/{id}/forward`). Presencia, indicadores de tecleo y el final experimental `/send/interactive` no son programables.

## Programar campos

| Campo | Requerido | Descripción |
| - | - | - |
| `scheduled_at` | sí | RFC 3339 vez del primer envío, en el futuro, por ejemplo `2026-11-01T09:00:00+07:00`. El primer envío siempre ocurre en este momento. |
| `timezone` | sí | Zona IANA (por ejemplo, `Asia/Jakarta`) utilizada para calcular repeticiones, así que "09:00 todos los días" permanece a las 9:00 a través de los cambios DST. |
| `recurrence` | no | `once` (por defecto), `daily`, `weekly` o `monthly`. |
| `weekdays` | semanal | Días para enviar, `0` = domingo … `6` = sábado, p. ej. `[1, 3, 5]`. |
| `day_of_month` | mensual | `1`–`31`; aplastó el último día de meses más cortos. |
| `end_at` | no | Sólo recurriendo. No hay envíos después de este tiempo. |
| `occurrence_limit` | no | Sólo recurriendo. Detener después de este número de envíos. |

Sin `scheduled_at`, la solicitud se envía inmediatamente como de costumbre.

## Ejemplos

```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"
  }
}
```

Las respuestas programadas tienen `schedule_id` en lugar de `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
```

Los archivos subidos se conservan en el servidor hasta que finalice la programación. En los cuerpos multipart, envía `weekdays` como campos repetidos (`-F weekdays=1 -F weekdays=3`).

## Gestionar programas

Los programas pertenecen a un dispositivo; envíe el mismo `X-Device-Id`.

| Accin | Solicitud |
| - | - |
| Lista | `GET /send/schedules` con `status`, `search` (recipiente o texto), `message_type`, `limit`, `offset` |
| Obtener uno | `GET /send/schedules/{schedule_id}` |
| Pausa | `POST /send/schedules/{schedule_id}/pause` |
| Reanudar | `POST /send/schedules/{schedule_id}/resume` |
| Cancelar | `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"
```

La lista devuelve `results.data` y `results.pagination` (`limit`, default 25; `offset`; `total`).

### Statuses

| Estado | Comenzando |
| - | - |
| `active` | Esperando para su próxima carrera. |
| `running` | Reclamado por el trabajador y el envío. |
| `paused` | Realizado hasta reanudado. |
| `completed` | No quedan ejecuciones. |
| `failed` | Salir después de las recuperaciones, o la solicitud almacenada no era válida. |
| `cancelled` | Cancelado por ti. |

## Comportamiento de entrega

* El trabajador verifica los horarios de vencimiento cada 5 segundos.
* **Dispositivo sin conexión o no conectado:** la ejecución espera y vuelve a intentarlo cada 30 segundos. Esperar no cuenta como un intento fallido, por lo que un programa sobrevive a largas interrupciones.
* **Enviar errores:** reintentó con backoff a partir de 15 segundos y se limitó a 5 minutos, hasta 10 intentos por ocurrencia. Un programa recurrente luego se salta a su siguiente ocurre; un programa único se vuelve `failed`.
* **Solicitud no válida** (por ejemplo un mal destinatario): falla inmediatamente sin reintentar.
* **Late runs:** no se envía una ocurrencia retrasada pasada `end_at`.
* **Accidentes y reinicios:** el apagado no aborta un envío ya en vuelo. Antes del primer intento, GOWA persiste un ID de mensaje de WhatsApp para la ocurrencia. Después de que expire su reclamo de 2 minutos, una ocurrencia interrumpida es solicitada con ese mismo ID y cuenta para el presupuesto de intento. Las encuestas también mantienen su cifrado secreto a través de las recuperaciones. Esto preserva la identidad del mensaje después de un reconocimiento ambiguo, pero no garantiza una entrega exacta una vez.
* **Anteriores intentos interrumpidos:** intentos heredados cuyo resultado es desconocido retienen la recuperación conservadora. El trabajador salta esa ocurrencia para un programa recurrente o falla un programa único en lugar de asignarle una nueva identidad de mensaje.

## Sobre MCP

La herramienta MCP `whatsapp_send` acepta los mismos campos de programación, y `whatsapp_schedule` listas, obtienen, pausas, reanudan y cancelan programas. Vea [Servidor MCP](https://gowa-docs.mintlify.site/es/integrations/mcp.md).

> [!NOTE]
>
> Comprueba `GET /app/info`: `results.scheduled_sends` es `true` cuando el servidor acepta campos de programación y expone `/send/schedules`.


## Related topics

- [Lista de envíos programados](https://gowa-docs.mintlify.site/es/api-reference/send/lista-de-envíos-programados.md)
- [Límites de envío](https://gowa-docs.mintlify.site/es/advanced/rate-limiting.md)
- [Enviando mensajes](https://gowa-docs.mintlify.site/es/examples/sending-messages.md)
- [Borrar mensaje](https://gowa-docs.mintlify.site/es/api-reference/message/borrar-mensaje.md)
- [Enviar estado de presencia](https://gowa-docs.mintlify.site/es/api-reference/send/enviar-estado-de-presencia.md)


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