## Overview

The scheduled messages API exposes the same module used by the dashboard. It always operates inside
one account and on an existing conversation. MCP tools are generated from this OpenAPI contract and
apply the same authorization and validation.

## Prerequisites

- The **Scheduled messages** account feature enabled.
- A user token with access to the account, Inbox and conversation.
- A complete account policy.
- For creation, a stable 1–128 character `X-Idempotency-Key`.

## Step by step

1. Call `GET /api/v1/accounts/{account_id}/message_scheduling/settings` and verify the effective
   policy.
2. Send the definition to `POST .../message_schedules/preview`. Preview neither persists nor sends.
3. Resolve every `blocker`, then create with `POST .../message_schedules` and
   `X-Idempotency-Key`.
4. Store `id` and `lock_version`. Repeating the key with identical content returns the existing
   schedule; different content returns `409`.
5. List occurrences with `GET .../message_schedules/{id}/occurrences`.
6. For changes and actions, submit the current `lock_version` and required `scope`.

## Settings & options

- Kinds: `one_time`, `sequence`, `recurring_single` and `recurring_sequence`.
- Occurrence scopes: `this_occurrence`, `this_and_future` and `all_future`.
- `send_now` requires choosing whether to consume the occurrence or create an immediate copy.
- `reconcile` requires an observed outcome: `sent`, `failed` or `canceled`.
- Schedule actions use `all_future`; `resume` also supplies the published resume action.
- Target, effective sender, capabilities and normalized draft are server-authoritative.

In MCP, find tools under **Message Schedules**. Names derive from `operationId`; arguments and
responses match Swagger.

## Use cases

- An external CRM schedules an idempotent callback after a deal update.
- An AI operator uses MCP to inspect blockers and pause a sequence with human confirmation.
- A reconciliation process records an uncertain provider outcome without duplicating it.

## Tips, limits & best practices

- Never reuse an idempotency key for a different definition.
- On `409`, reread the resource; do not guess or increment the local lock.
- Do not send `campaign_id`, audience, segment or contact lists. The contract targets one conversation.
- Preview before creation, and treat due-time validation as a second authority.
- Do not automatically retry `needs_attention`; verify the provider effect first.
- Use the published OpenAPI document for complete schemas and examples, including multipart drafts.

## Troubleshooting

- **400 invalid_idempotency_key**: correct the header format or length.
- **401/403**: check token, feature, role, Inbox and conversation access.
- **409 stale_lock_version**: reload the schedule or occurrence and reapply the intention.
- **422 preview_blocked**: inspect every blocker code and correct policy, channel, sender or content.
- **MCP tool is missing**: verify that the server publishes the current Swagger and refresh the MCP
  session/catalog.

## See also

- [Create and manage scheduled messages](/hc/ajuda/articles/calendar-scheduling-mensagens-agendadas-nativas-en)
- [API reference (Swagger/OpenAPI)](/hc/ajuda/articles/api-developers-swagger-reference-en)
- [MCP server and client](/hc/ajuda/articles/api-developers-mcp-server-and-client-en)