Message Batches

Cria um lote persistente

Persiste a definição, os destinatários normalizados e as instâncias permitidas. A requisição não envia mensagens; com autoStart=true, o lote já é gravado em QUEUED para consumo assíncrono pelo worker.

Pro

POSThttp://localhost:8084/message/batches

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>

Request body

obrigatório

bodyobject

Exemplo:

{"name":"Aviso de manutenção","instances":["codechat-01","codechat-02"],"recipients":["5531999999999","5531888888888"],"message":{"type":"interactive","payload":{"title":"Confirmação","description":"Deseja continuar?","footerText":"CodeChat","buttons":[{"displayText":"Repo","url":"https://github.com/code-chat-br/whatsapp-api-go"},{"displayText":"Código de barras","copyCode":"32546413216543165489869589416558645341864321365468435469465"},{"displayText":"Sim","id":"1"},{"displayText":"Não","id":"0"},{"displayText":"Talvez","id":"-1"}]}},"options":{"replicable":true,"presence":"composing","delay":{"minMs":3000,"maxMs":12000}},"autoStart":false,"externalAttributes":{"origin":"admin-panel"}}

namestringobrigatóriominLength: 1 · maxLength: 255

instancesarrayobrigatório

Nomes de instâncias existentes e com autenticação disponível.

items[]stringminLength: 1 · maxLength: 255

recipientsarrayobrigatório

Somente contatos individuais. O limite é definido por MESSAGE_BATCH_MAX_RECIPIENTS e duplicados normalizados são ignorados.

items[]stringminLength: 1

messageobjectobrigatório

payloadoneOfobrigatório

Para type=interactive, segue MessageBatchInteractivePayload; os demais tipos reutilizam o payload interno do endpoint individual.

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

Campos ausentes assumem zero. maxMs precisa ser maior ou igual a minMs e respeitar MESSAGE_BATCH_MAX_DELAY_MS.

minMsintegerformat: int64 · padrão: 0 · mín: 0

maxMsintegerformat: int64 · padrão: 0 · mín: 0

quotedMessageIdintegerformat: int64

quotedMessageobject

externalAttributesobject

mentionAllboolean

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

autoStartbooleanpadrão: false

externalAttributesobject

Objeto JSON com até 64 KiB.

Exemplo JSONgerado do schema

{
  "name": "Aviso de manutenção",
  "instances": [
    "codechat-01",
    "codechat-02"
  ],
  "recipients": [
    "5531999999999",
    "5531888888888"
  ],
  "message": {
    "type": "interactive",
    "payload": {
      "title": "Confirmação",
      "description": "Deseja continuar?",
      "footerText": "CodeChat",
      "buttons": [
        {
          "displayText": "Repo",
          "url": "https://github.com/code-chat-br/whatsapp-api-go"
        },
        {
          "displayText": "Código de barras",
          "copyCode": "32546413216543165489869589416558645341864321365468435469465"
        },
        {
          "displayText": "Sim",
          "id": "1"
        },
        {
          "displayText": "Não",
          "id": "0"
        },
        {
          "displayText": "Talvez",
          "id": "-1"
        }
      ]
    }
  },
  "options": {
    "replicable": true,
    "presence": "composing",
    "delay": {
      "minMs": 3000,
      "maxMs": 12000
    }
  },
  "autoStart": false,
  "externalAttributes": {
    "origin": "admin-panel"
  }
}

Respostas

application/json

201

Lote criado em DRAFT ou QUEUED

response 201object

idstringobrigatórioformat: uuid

ownerUserIdstringobrigatórioformat: uuid

namestringobrigatório

messageobject

payloadoneOfobrigatório

Para type=interactive, segue MessageBatchInteractivePayload; os demais tipos reutilizam o payload interno do endpoint individual.

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).

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 201

{
  "id": "01900000-0000-7000-8000-000000000001",
  "ownerUserId": "11111111-1111-4111-8111-111111111111",
  "name": "Aviso de manutenção",
  "status": "DRAFT",
  "instances": [
    {
      "id": 1,
      "name": "codechat-01",
      "connectionStatus": "offline"
    },
    {
      "id": 2,
      "name": "codechat-02",
      "connectionStatus": "online"
    }
  ],
  "counts": {
    "received": 2,
    "total": 2,
    "processed": 0,
    "pending": 2,
    "sending": 0,
    "success": 0,
    "failed": 0,
    "skipped": 0,
    "unknown": 0
  },
  "progress": 0,
  "externalAttributes": {
    "origin": "admin-panel"
  },
  "createdAt": "2026-07-13T15:00:00Z",
  "updatedAt": "2026-07-13T15:00:00Z"
}