Centro de Ayuda Conversa Labs
es
Idioma
pt_BR Portuguese (Brazil) en English es Spanish

API y MCP de mensajes programados

Abrir en
Ver como Markdown Abrir en ChatGPT Abrir en Claude
Conversa Labs

Conversa Labs

Última actualización el Aug 23, 2026

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