CodeChat APIv1.0.0
ChangelogPostman
Referência/Message Batches/startMessageBatch
Message Batches

Inicia ou continua o lote sem executar o loop na requisição

Inicia DRAFT, PAUSED ou INTERRUPTED respeitando a agenda: QUEUED dentro da janela, SCHEDULED antes da primeira ou WAITING_FOR_WINDOW fora dela. É idempotente nos estados já ativos ou agendados.

Pro
POSThttp://localhost:8084/message/batches/{batchId}/start

Autenticação

UserBearerobrigatório

JWT HS256 de usuario. Deve conter userId em formato UUID e exp; a expiracao sempre e validada.

Header
Authorization
Exemplo
Bearer <INSTANCE_TOKEN>

Parâmetros

batchIdpathobrigatório
string<uuid>

Sem descrição adicional.

Respostas

application/json
200

Estado persistido

response 200object
idstringobrigatórioformat: uuid
ownerUserIdstringobrigatórioformat: uuid
namestringobrigatório
statusenum<DRAFT | SCHEDULED | QUEUED | PROCESSING | PAUSE_REQUESTED | PAUSED | WAITING_FOR_INSTANCE | WAITING_FOR_WINDOW | STOP_REQUESTED | STOPPED | INTERRUPTED | COMPLETED | COMPLETED_WITH_ERRORS | FAILED>obrigatório
messageobject

Mensagem persistida do lote. O payload é direto: não envie number/chat/recipient/options nem wrappers como textMessage, mediaMessage, audioMessage, contactMessage, locationMessage ou buttonMessage. Tipos aceitos: text, link, media, audio, contact, location e interactive; ptt, whatsapp-audio e whatsapp_audio são aliases de audio.

typeenum<text | link | media | audio | ptt | whatsapp-audio | whatsapp_audio | contact | location | interactive>obrigatório
payloadoneOfobrigatório

Objeto ou array persistente conforme message.type: text={text}; link={link,thumbnailUrl,title,description}; media={mediatype,media|mediaUploadId,fileName,caption}; audio={audio} ou {mediaUploadId,ptt:true}; contact=[{fullName,phoneNumber,wuid,organization,vcard}]; location={latitude,longitude,name,address,url}; interactive segue MessageBatchInteractivePayload.

opção 1object
opção 2array
items[]object
optionsobject
replicableboolean

Preservado no contrato; não adiciona semântica própria no worker.

presenceenum<composing | recording | paused>
delayobject
minMsintegerobrigatórioformat: int64 · padrão: 0 · mín: 0
maxMsintegerobrigatórioformat: int64 · padrão: 0 · mín: 0
quotedMessageIdintegerformat: int64
quotedMessageobject
externalAttributesobject
mentionAllboolean

Somente false é aceito; true é rejeitado porque lotes não aceitam grupos.

externalAttributesobject
instancesarrayobrigatório
items[]object
idintegerobrigatório
namestringobrigatório
connectionStatusstring
selectedCountintegerformat: int64
successCountintegerformat: int64
failedCountintegerformat: int64
countsobjectobrigatório
receivedintegerformat: int64 · mín: 0
totalintegerobrigatórioformat: int64 · mín: 0
duplicatesIgnoredintegerformat: int64 · mín: 0
processedintegerobrigatórioformat: int64 · mín: 0
pendingintegerobrigatórioformat: int64 · mín: 0
sendingintegerobrigatórioformat: int64 · mín: 0
successintegerobrigatórioformat: int64 · mín: 0
failedintegerobrigatórioformat: int64 · mín: 0
skippedintegerobrigatórioformat: int64 · mín: 0
unknownintegerobrigatórioformat: int64 · mín: 0
progressintegerobrigatóriomín: 0 · máx: 100

floor(processed * 100 / total).

autoResumebooleanobrigatório
scheduleoneOfobrigatório
opção 1object

Janela absoluta inicial. DAILY preserva os horários locais e aceita janelas que atravessam a meia-noite.

windowStartAtstringobrigatórioformat: date-time
windowEndAtstringobrigatórioformat: date-time
recurrenceenum<NONE | DAILY>obrigatório
timezonestringobrigatório

Timezone IANA usado no cálculo da recorrência.

opção 2null
nextRunAtstring | nullobrigatórioformat: date-time
lastInterruptedAtstring | nullobrigatórioformat: date-time
interruptionReasonenum<GRACEFUL_SHUTDOWN | LEASE_EXPIRED | PROCESS_CRASH | SEND_TIMEOUT_DURING_SHUTDOWN | null>obrigatório
lastRecoveredAtstring | nullobrigatórioformat: date-time
currentItemobject
idstringobrigatórioformat: uuid
positionintegerobrigatóriomín: 0
recipientstringobrigatório
instanceNamestring | nullobrigatório
lastErrorstring
createdAtstringobrigatórioformat: date-time
startedAtstringformat: date-time
pausedAtstringformat: date-time
stoppedAtstringformat: date-time
completedAtstringformat: date-time
interruptedAtstringformat: date-time
updatedAtstringobrigatórioformat: date-time
Exemplo 200gerado do schema
{
  "id": "01900000-0000-7000-8000-000000000001",
  "ownerUserId": "01900000-0000-7000-8000-000000000001",
  "name": "CodeChat",
  "status": "DRAFT",
  "message": {
    "type": "text",
    "payload": {}
  },
  "options": {
    "replicable": true,
    "presence": "composing",
    "delay": {
      "minMs": 0,
      "maxMs": 0
    },
    "quotedMessageId": 1,
    "quotedMessage": {},
    "externalAttributes": {},
    "mentionAll": false
  },
  "externalAttributes": {},
  "instances": [
    {
      "id": 1,
      "name": "CodeChat",
      "connectionStatus": "string",
      "selectedCount": 1,
      "successCount": 1,
      "failedCount": 1
    }
  ],
  "counts": {
    "received": 1,
    "total": 1,
    "duplicatesIgnored": 1,
    "processed": 1,
    "pending": 1,
    "sending": 1,
    "success": 1,
    "failed": 1,
    "skipped": 1,
    "unknown": 1
  },
  "progress": 1,
  "autoResume": true,
  "schedule": {
    "windowStartAt": "2026-07-13T15:10:00Z",
    "windowEndAt": "2026-07-13T15:10:00Z",
    "recurrence": "NONE",
    "timezone": "string"
  },
  "nextRunAt": "2026-07-13T15:10:00Z",
  "lastInterruptedAt": "2026-07-13T15:10:00Z",
  "interruptionReason": "GRACEFUL_SHUTDOWN",
  "lastRecoveredAt": "2026-07-13T15:10:00Z",
  "currentItem": {
    "id": "01900000-0000-7000-8000-000000000001",
    "position": 1,
    "recipient": "5511999999999",
    "instanceName": "minha-instancia"
  },
  "lastError": "string",
  "createdAt": "2026-07-13T15:10:00Z",
  "startedAt": "2026-07-13T15:10:00Z",
  "pausedAt": "2026-07-13T15:10:00Z",
  "stoppedAt": "2026-07-13T15:10:00Z",
  "completedAt": "2026-07-13T15:10:00Z",
  "interruptedAt": "2026-07-13T15:10:00Z",
  "updatedAt": "2026-07-13T15:10:00Z"
}