## Visión general

La API de mensajes programados expone el mismo módulo usado por el dashboard. Siempre opera dentro
de una cuenta y sobre una conversación existente. Las herramientas MCP se generan desde este contrato
OpenAPI y aplican la misma autorización y validación.

## Requisitos previos

- La función **Mensajes programados** habilitada en la cuenta.
- Un token de usuario con acceso a la cuenta, Inbox y conversación.
- Una política completa configurada en la cuenta.
- Para crear, una clave `X-Idempotency-Key` estable de 1 a 128 caracteres.

## Paso a paso

1. Consulta `GET /api/v1/accounts/{account_id}/message_scheduling/settings` y verifica la política
   efectiva.
2. Envía la definición a `POST .../message_schedules/preview`. La vista previa no persiste ni envía.
3. Corrige todos los `blockers` y crea con `POST .../message_schedules` más
   `X-Idempotency-Key`.
4. Guarda `id` y `lock_version`. Repetir la misma clave y contenido devuelve la programación
   existente; contenido diferente devuelve `409`.
5. Lista ocurrencias con `GET .../message_schedules/{id}/occurrences`.
6. En cambios y acciones, envía el `lock_version` actual y el `scope` exigido.

## Configuración y opciones

- Tipos: `one_time`, `sequence`, `recurring_single` y `recurring_sequence`.
- Alcances: `this_occurrence`, `this_and_future` y `all_future`.
- `send_now` exige elegir si consume la ocurrencia o crea una copia inmediata.
- `reconcile` exige un resultado observado: `sent`, `failed` o `canceled`.
- Las acciones de programación usan `all_future`; `resume` también informa la acción publicada.
- El destino, remitente efectivo, capabilities y draft normalizado son autoridad del servidor.

En MCP, busca las herramientas en **Message Schedules**. Los nombres derivan del `operationId`; los
argumentos y respuestas coinciden con Swagger.

## Casos de uso

- Un CRM externo programa un retorno idempotente tras actualizar una oportunidad.
- Un operador de IA usa MCP para consultar bloqueos y pausar una secuencia con confirmación humana.
- Un proceso de reconciliación registra un resultado incierto sin duplicar el envío.

## Consejos, límites y buenas prácticas

- Nunca reutilices una clave idempotente para una definición distinta.
- Ante `409`, vuelve a leer el recurso; no supongas ni incrementes el lock local.
- No envíes `campaign_id`, audiencia, segmento ni listas de contactos. El contrato usa una conversación.
- Usa la vista previa antes de crear y trata la validación al vencimiento como segunda autoridad.
- No reintentes automáticamente `needs_attention`; verifica primero el efecto en el proveedor.
- Consulta el OpenAPI publicado para schemas y ejemplos completos, incluidos drafts multipartes.

## Solución de problemas

- **400 invalid_idempotency_key**: corrige formato o longitud del header.
- **401/403**: revisa token, función, rol, Inbox y acceso a la conversación.
- **409 stale_lock_version**: recarga la programación u ocurrencia y reaplica la intención.
- **422 preview_blocked**: revisa cada código y corrige política, canal, remitente o contenido.
- **No aparece la herramienta MCP**: confirma que el servidor publica el Swagger actual y actualiza la
  sesión/catálogo MCP.

## Ver también

- [Crear y administrar mensajes programados](/hc/ajuda/articles/calendar-scheduling-mensagens-agendadas-nativas-es)
- [Referencia de API (Swagger/OpenAPI)](/hc/ajuda/articles/api-developers-swagger-reference-es)
- [Servidor y cliente MCP](/hc/ajuda/articles/api-developers-mcp-server-and-client-es)