Central de Ajuda Conversa Labs
pt_BR
Idioma
pt_BR Portuguese (Brazil) en English es Spanish

API e MCP de mensagens agendadas

Abrir em
Ver como Markdown Abrir no ChatGPT Abrir no Claude
Conversa Labs

Conversa Labs

Última atualização em Aug 23, 2026

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