Agendar mensagens em grupos

Disponível a partir da versão 1.99.0.

Autenticação e seleçãoCopy Anchor Link

Use Authorization: Bearer SUA_CHAVE. A organização vem da chave: não envie organization_id. O criador da chave precisa continuar como membro aceito e ter permissão para operar grupos. Consulta exige messages:read; criação exige messages:write.

Base: https://crm.oficinamartech.com/api/v1.

GET /groups?q=Alunos&limit=50&offset=0 retorna groups com id, chat_name e instance_id, além de pagination com limit, offset, total e has_more. O filtro q pesquisa o nome; ele não classifica o público. Confira os grupos e selecione IDs explícitos para separar alunos, grupos gerais e idiomas. Avance o offset até has_more=false. Limite máximo por página: 100; offset máximo: 10000.

Criar um loteCopy Anchor Link

POST /groups/broadcasts exige um cabeçalho Idempotency-Key estável, de 1 a 128 letras, números, ponto, hífen, sublinhado ou dois-pontos. Use uma chave por solicitação lógica. Não gere outra chave para repetir uma chamada cujo resultado ficou incerto.

{
  "items": [
    {
      "name": "Moriá — aviso da aula",
      "message_type": "image",
      "content": "Nossa aula começa às 19h. Esperamos vocês!",
      "media_url": "https://arquivos.exemplo.com/aviso.jpg",
      "target_groups": ["11111111-1111-4111-8111-111111111111"],
      "scheduled_at": "2027-01-20T18:00:00",
      "time_zone": "America/Sao_Paulo"
    }
  ]
}

IDs e URL são exemplos; substitua pelos grupos consultados e arquivo acessível. O endpoint não faz upload. Links privados de mídia do CRM não são aceitos: forneça uma URL pública independente.

• name: nome do agendamento, até 200 caracteres.
• message_type: text, image, video ou document (inclui PDF).
• content: obrigatório para texto; opcional como legenda em mídia, até 4096 caracteres. O limite aceito no envio pode variar conforme o tipo de mídia e a conexão.
• media_url: obrigatório para mídia, HTTPS público sem credenciais; o arquivo precisa continuar acessível até o envio. Use URL com validade suficiente.
• file_name: obrigatório para documento, por exemplo material-da-aula.pdf.
• target_groups: IDs únicos no item; cada item pode usar grupos diferentes.
• scheduled_at: data e hora com segundos. Antecedência mínima de cinco minutos.
• time_zone: fuso IANA, padrão America/Sao_Paulo. Exemplos: America/Manaus, Europe/Lisbon e America/New_York.

Horário sem offset é interpretado no fuso informado. Horários inexistentes ou repetidos na mudança de horário de verão são rejeitados. Para desambiguar, envie offset explícito, como 2027-10-31T01:30:00+01:00. Quando há offset ou Z, ele define o instante; time_zone permanece como referência do agendamento.

Limites: 50 itens, 50 grupos por item e 1000 destinos somados e corpo de 1 MiB. As chaves criadas por conexões de agente (MCP) de uma mesma pessoa agendam, juntas, no máximo 200 destinos a cada 24 horas por organização, somando os lotes aceitos; chaves de integração criadas em Configurações → API não têm esse limite. Não há envio imediato nem recorrência neste endpoint. O lote é atômico: um item inválido impede a criação de todos os itens.

Resposta e repetiçãoCopy Anchor Link

Criação retorna HTTP 201:

{
  "replayed": false,
  "broadcasts": [
    {
      "broadcast_group_id": "22222222-2222-4222-8222-222222222222",
      "scheduled_at": "2027-01-20T21:00:00+00:00",
      "time_zone": "America/Sao_Paulo",
      "total": 1
    }
  ]
}

A ordem de broadcasts corresponde à ordem de items. Guarde os IDs. Repetição com a mesma chave e payload normalizado retorna HTTP 200 e replayed=true, inclusive depois do horário agendado. Reutilização da chave com conteúdo diferente retorna HTTP 409. A idempotência é por organização e chave de API: não troque a chave de API para repetir uma operação incerta.

Listar agendamentosCopy Anchor Link

GET /groups/broadcasts?status=scheduled&limit=50&offset=0 retorna broadcasts e pagination. Há uma linha por mensagem agendada, da criada mais recentemente para a mais antiga, incluindo as agendadas pela tela do CRM e por outras chaves: broadcast_group_id, name, message_type, content, scheduled_for, created_at, status, total, sent, failed, pending e uncertain.

status é a situação agregada dos grupos do agendamento e aceita scheduled, pending, sending, paused, sent, failed ou canceled; sem o filtro, vêm todas. A lista alcança os 500 agendamentos mais recentes da organização. Use-a para conferir o que já existe antes de criar um lote e para recuperar um broadcast_group_id.

AcompanhamentoCopy Anchor Link

GET /groups/broadcasts/ID?limit=50&offset=0 retorna broadcast_group_id, deliveries e pagination. Cada destino informa conversation_id, status, scheduled_for, sent_at, delivery_attempt_count, next_retry_at e delivery_outcome_uncertain.

Agendamento registrado não confirma envio ou entrega. A conexão precisa estar operacional no horário. Se delivery_outcome_uncertain=true, consulte o histórico antes de qualquer nova criação; não repita automaticamente. O endpoint não oferece cancelamento ou edição nesta versão.

ErrosCopy Anchor Link

• 400: JSON, formato, grupo, horário ou limite do lote inválido.
• 401: chave ausente, inválida, expirada ou revogada.
• 403: escopo ou permissão insuficiente, criador sem vínculo aceito.
• 404: identificador de agendamento não encontrado na organização.
• 409: conflito de idempotência.
• 413: corpo maior que 1 MiB.
• 429: limite de requisições, ou daily_limit quando as conexões de agente da pessoa passaram de 200 destinos em 24 horas. Nesse caso nada foi agendado e repetir não resolve.
• 500: falha interna; repita com a mesma chave de idempotência.