## Visão geral

A API de mensagens agendadas expõe o mesmo módulo usado no dashboard. Ela opera sempre dentro de uma
conta e sobre uma conversa existente. As ferramentas MCP são geradas desse contrato OpenAPI e aplicam
as mesmas permissões e validações.

## Pré-requisitos

- Feature **Mensagens agendadas** habilitada na conta.
- Token de usuário com acesso à conta, Inbox e conversa.
- Políticas completas configuradas na conta.
- Para criação, uma chave `X-Idempotency-Key` estável de 1 a 128 caracteres.

## Passo a passo

1. Consulte `GET /api/v1/accounts/{account_id}/message_scheduling/settings` e confirme a política
   efetiva.
2. Envie a definição para `POST .../message_schedules/preview`. A prévia não persiste nem envia.
3. Corrija todos os `blockers` e crie com `POST .../message_schedules` mais
   `X-Idempotency-Key`.
4. Guarde `id` e `lock_version`. Repetir a mesma chave e conteúdo devolve o agendamento existente;
   conteúdo diferente devolve `409`.
5. Liste ocorrências em `GET .../message_schedules/{id}/occurrences`.
6. Em alterações e ações, envie o `lock_version` atual e o `scope` exigido.

## Configurações & opções

- Tipos: `one_time`, `sequence`, `recurring_single` e `recurring_sequence`.
- Escopos de ocorrência: `this_occurrence`, `this_and_future` e `all_future`.
- `send_now` exige escolher entre consumir a ocorrência ou criar uma cópia imediata.
- `reconcile` exige um resultado observado: `sent`, `failed` ou `canceled`.
- Ações de agenda usam `all_future`; `resume` também informa a ação de retomada publicada.
- O alvo, remetente efetivo, capabilities e draft normalizado são autoritativos no servidor.

No MCP, procure as ferramentas pelo grupo **Message Schedules**. Os nomes são derivados do
`operationId`; argumentos e respostas são os mesmos do Swagger.

## Casos de uso

- Um CRM externo agenda um retorno idempotente após uma atualização de negócio.
- Um operador de IA usa MCP para consultar bloqueios e pausar uma sequência com confirmação humana.
- Um processo de reconciliação registra o resultado de um envio incerto sem duplicá-lo.

## Dicas, limites e boas práticas

- Nunca reutilize uma chave idempotente para uma definição diferente.
- Ao receber `409`, releia o recurso; não incremente o lock localmente por suposição.
- Não envie `campaign_id`, audiência, segmento ou lista de contatos. O contrato é de uma conversa.
- Use a prévia antes da criação e trate a validação no vencimento como uma segunda autoridade.
- Não faça retry automático de `needs_attention`; confirme primeiro o efeito no provedor.
- Consulte o OpenAPI publicado para schemas e exemplos completos, inclusive drafts multipartes.

## Solução de problemas

- **400 invalid_idempotency_key**: ajuste formato/tamanho do header.
- **401/403**: confira token, feature, papel, Inbox e acesso à conversa.
- **409 stale_lock_version**: recarregue o agendamento ou ocorrência e reaplique a intenção.
- **422 preview_blocked**: leia cada código em `blockers` e corrija política, canal, remetente ou
  conteúdo.
- **MCP não mostra a ferramenta**: confirme que o servidor publicou o Swagger atual e atualize a
  sessão/catálogo MCP.

## Veja também

- [Criar e gerenciar mensagens agendadas](/hc/ajuda/articles/calendar-scheduling-mensagens-agendadas-nativas-pt-br)
- [Referência da API (Swagger/OpenAPI)](/hc/ajuda/articles/api-developers-swagger-reference-pt-br)
- [Servidor e cliente MCP](/hc/ajuda/articles/api-developers-mcp-server-and-client-pt-br)