Conversa Labs Help Center
en
Language
pt_BR Portuguese (Brazil) en English es Spanish

Scheduled messages API and MCP

Open in
View as Markdown Open in ChatGPT Open in Claude
Conversa Labs

Conversa Labs

Last updated on Aug 23, 2026

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