Pular para o conteúdo principal

Documentação da Bulk Template Message API

Esta API permite enviar mensagens de template a vários destinatários simultaneamente pelo canal de WhatsApp.

O envio das mensagens é processado de forma assíncrona; a requisição da API retorna imediatamente um bulkMessageId, enquanto as mensagens são colocadas em fila e processadas em segundo plano.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/send.js

Principais recursos​

  • Envie mensagens de template em massa para 1 a 5.000 destinatários em uma única requisição
  • Variáveis personalizadas para cada destinatário (HEADER, BODY, BUTTONS, CAROUSEL)
  • defaultPayload compartilhado por todos os destinatários, com mesclagem do payload específico de cada destinatário (isMerge)
  • Envio agendado (scheduleAt)
  • Indique os destinatários por username (número de telefone), userId ou sessionId
  • Envie várias mensagens ao mesmo usuário em uma única requisição em massa
  • referenceId opcional para acompanhar registros em sistemas externos
  • Atribua automaticamente as conversas a um usuário ou grupo de trabalho após o envio (action)
aviso

Esta API só pode enviar templates que tenham sido aprovados pela Meta.

O nome do template e o código de idioma devem corresponder exatamente ao template cadastrado no Meta Business Manager.

Parâmetros da requisição​

Parâmetros de nível superior​

ParâmetroTipoObrigatórioDescrição
channelUsernamestringSimNúmero do canal de WhatsApp usado para enviar a mensagem (por exemplo "908506669933")
connectorBrandstringSimMarca do conector do canal. Valor atualmente aceito: "whatsapp"
titlestringNãoTítulo da campanha. Usado para exibição no painel. Padrão: "-"
scheduleAtstring (ISO 8601)NãoData e hora do envio agendado (por exemplo "2026-06-10T10:00:00.000Z"). Se omitido, as mensagens são enviadas imediatamente.
defaultPayloadobjectCondicional*Payload de template padrão aplicado a todos os destinatários. Obrigatório se um destinatário não informar o próprio payload.
recipientsarraySimLista de destinatários. Mínimo de 1, máximo de 5.000 destinatários.
actionobjectNãoAção aplicada à conversa após o envio. assign-to-user ou assign-to-workgroup.

*Se todos os destinatários informarem o próprio payload, o defaultPayload é opcional.

Estrutura do destinatário​

Para cada destinatário, deve ser informado exatamente um entre username, userId ou sessionId. Não é possível usar vários identificadores juntos, e omitir todos resultará em erro.

Para enviar várias mensagens ao mesmo usuário em uma única requisição em massa, adicione o mesmo identificador à lista de destinatários várias vezes.

CampoTipoDescrição
usernamestringNúmero de telefone do destinatário (por exemplo "905554443322"). Se o usuário não existir no sistema, ele é criado automaticamente.
userIdstringID de um usuário existente no sistema.
sessionIdstringID de uma sessão de conversa existente no sistema.
referenceIdstringID de referência opcional (máximo de 256 caracteres) para correspondência com registros de sistemas externos (CRM, pedido, ticket etc.). Deve ser único dentro do envio em massa, se informado.
payloadobjectPayload de template específico do destinatário (opcional). Se isMerge: true, ele é mesclado com o defaultPayload.
isMergebooleanSubstitui o comportamento de mesclagem para este destinatário (opcional). Se omitido, usa-se o defaultPayload.isMerge.

Estrutura da ação​

CampoTipoDescrição
action.keystring"assign-to-user" atribui a conversa a um atendente específico; "assign-to-workgroup" atribui a um grupo de trabalho.
action.valuestringID do usuário ou do grupo de trabalho de destino.

Estrutura do payload do template​

defaultPayload e o payload específico de cada destinatário têm a mesma estrutura. Para mensagens de template, é preciso informar type: "template".

{
  "type": "template",
  "template": {
    "templateName": "order_confirmation",
    "languageCode": "tr-TR",
    "variables": []
  },
  "isMerge": true
}
CampoTipoObrigatórioDescrição
typestringSimTipo do payload. Para mensagens de template: "template"
template.templateNamestringSim*Nome do template cadastrado na Meta. Opcional nos payloads de destinatário quando se usa isMerge: true (herda do padrão).
template.languageCodestringNãoCódigo de idioma do template (por exemplo "tr", "en", "tr-TR", "en-US"). Deve corresponder exatamente ao idioma cadastrado na Meta.
template.variablesarrayNãoLista de variáveis aplicadas aos componentes do template. Detalhada abaixo.
isMergebooleanNãotrue: o payload do destinatário é mesclado em profundidade com o defaultPayload. false ou omitido: o payload do destinatário substitui completamente o defaultPayload.
Comportamento de isMerge
  • Se defaultPayload.isMerge: true e o destinatário informar o próprio payload, é aplicada uma mesclagem em profundidade.
  • Com a mesclagem em profundidade, o destinatário pode informar apenas variables; templateName e languageCode são herdados do payload padrão.
  • O campo isMerge do destinatário substitui o defaultPayload.isMerge.
  • Se um destinatário não informar um payload, o defaultPayload é sempre usado.

Estrutura das variáveis​

Cada item do array variables corresponde a um componente do template. Um tipo de componente (type) pode aparecer apenas uma vez no array.

typeDescriçãoparameterscards
"HEADER"Componente de cabeçalho do template. Variável de texto ou URL de mídia (imagem, vídeo, documento)Sim—
"BODY"Variáveis de texto do corpo do templateSim—
"BUTTONS"Variáveis de sufixo de URL dinâmico para botõesSim—
"CAROUSEL"Componentes de cartão para templates de carrossel—Sim

Formatos dos parâmetros​

O campo parameters pode ser informado em três formatos diferentes:

// Format 1: Array (index-based) — for placeholders like {{1}}, {{2}}, {{3}}
"parameters": ["value1", "value2", "value3"]

// Format 2: Object (numeric keys) — alternative representation for {{1}}, {{2}}
"parameters": { "1": "value1", "2": "value2" }

// Format 3: Object (named keys) — for placeholders like {{name}}, {{amount}}
"parameters": { "name": "John", "amount": "150 USD" }
Qual formato devo usar?
  • Se o seu template da Meta usa marcadores como {{1}}, {{2}}, use o formato de array ou o de objeto com chaves numéricas.
  • Se o seu template usa marcadores nomeados, como {{firstName}} ou {{orderTotal}}, use o formato de objeto com chaves nomeadas.
  • Ao usar arrays, a ordem importa: o primeiro elemento corresponde a {{1}}, o segundo a {{2}}, e assim por diante.

Componente HEADER​

Use o componente HEADER quando o cabeçalho do template contiver mídia (imagem, vídeo, documento) ou texto dinâmico.

// Media header (image URL)
{
  "type": "HEADER",
  "parameters": ["https://example.com/product-image.jpg"]
}

// Text header variable
{
  "type": "HEADER",
  "parameters": ["Special Campaign"]
}

Componente BODY​

Usado para variáveis de texto dinâmicas dentro do corpo do template.

// Array format — when the template uses {{1}}, {{2}}, {{3}}
{
  "type": "BODY",
  "parameters": ["John", "ORD-12345", "150.00 USD"]
}

// Named format — when the template uses {{name}}, {{orderAmount}}
{
  "type": "BODY",
  "parameters": {
    "name": "John",
    "orderAmount": "150.00 USD"
  }
}

Componente BUTTONS​

Usado para botões com sufixos de URL dinâmicos. Se o template contiver vários botões de URL, apenas os botões com variáveis são indexados em sequência (botões sem variáveis ou botões FLOW são ignorados).

// Single URL button suffix variable
{
  "type": "BUTTONS",
  "parameters": ["tracking/ORD-12345"]
}

// Multiple URL button suffix variables (first URL button, second URL button)
{
  "type": "BUTTONS",
  "parameters": ["tracking/ORD-12345", "cancel/ORD-12345"]
}

Em templates de carrossel, as variáveis dos componentes são definidas separadamente para cada cartão.

{
  "type": "CAROUSEL",
  "cards": [
    {
      "components": [
        {
          "type": "HEADER",
          "parameters": ["https://example.com/card1.jpg"]
        },
        {
          "type": "BODY",
          "parameters": ["Product A", "99.00 USD"]
        }
      ]
    },
    {
      "components": [
        {
          "type": "HEADER",
          "parameters": ["https://example.com/card2.jpg"]
        },
        {
          "type": "BODY",
          "parameters": ["Product B", "149.00 USD"]
        }
      ]
    }
  ]
}
aviso

O tamanho do array cards deve corresponder exatamente ao número de cartões definidos no template.

Exemplos​

1. Template simples — sem variáveis, mesmo conteúdo para todos os destinatários​

Esta é a forma mais simples de enviar um template estático, sem variáveis, a vários destinatários.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "General Announcement",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "hello_world",
      "languageCode": "tr-TR"
    }
  },
  "recipients": [{ "username": "905554443301" }, { "username": "905554443302" }, { "username": "905554443303" }]
}
curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/send.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "General Announcement",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "hello_world",
      "languageCode": "tr-TR"
    }
  },
  "recipients": [
    { "username": "905554443301" },
    { "username": "905554443302" },
    { "username": "905554443303" }
  ]
}'
dica
  • Os destinatários indicados por username são criados automaticamente se ainda não existirem no sistema
  • Todos os destinatários usam o mesmo defaultPayload; nenhum dado específico por destinatário é necessário
  • Quando isMerge não é especificado, cada destinatário usa diretamente o defaultPayload

2. Template com variáveis de corpo compartilhadas​

O mesmo template é enviado a todos os destinatários com valores de variáveis idênticos. O template contém marcadores como {{1}} e {{2}}.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Summer Campaign",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "promo_notification",
      "languageCode": "tr-TR",
      "variables": [
        {
          "type": "BODY",
          "parameters": ["30%", "July 31, 2026"]
        }
      ]
    }
  },
  "recipients": [{ "username": "905554443301" }, { "username": "905554443302" }]
}
dica
  • Neste exemplo, o corpo do template pode conter um texto como: "Aproveite {{1}} de desconto na nossa campanha! Oferta válida até {{2}}."
  • parameters[0] substitui {{1}}, enquanto parameters[1] substitui {{2}}

3. Template personalizado — variáveis por destinatário com isMerge​

Valores de variáveis diferentes são usados para cada destinatário. Ao definir isMerge: true no defaultPayload, os destinatários só precisam informar variables; templateName e languageCode são herdados do payload padrão.

Neste exemplo, o template inclui um cabeçalho de mídia e variáveis de corpo personalizadas.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Personal Order Notification",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "order_confirmation",
      "languageCode": "tr-TR"
    },
    "isMerge": true
  },
  "recipients": [
    {
      "username": "905554443301",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "HEADER",
              "parameters": ["https://s3.example.com/product-a.jpg"]
            },
            {
              "type": "BODY",
              "parameters": ["Ahmet", "ORD-001", "150.00 TRY"]
            }
          ]
        }
      }
    },
    {
      "username": "905554443302",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "HEADER",
              "parameters": ["https://s3.example.com/product-b.jpg"]
            },
            {
              "type": "BODY",
              "parameters": ["Fatma", "ORD-002", "289.00 TRY"]
            }
          ]
        }
      }
    }
  ]
}
dica
  • Graças a isMerge: true, templateName não precisa ser repetido no payload de cada destinatário
  • O array variables de cada destinatário é totalmente independente
  • A URL da mídia do cabeçalho deve ser publicamente acessível
  • Se type for omitido no payload do destinatário, defaultPayload.type é herdado

4. Variável de botão de URL​

Use o componente BUTTONS quando o template contiver um botão com sufixo de URL dinâmico. Por exemplo, um código de rastreamento acrescentado à URL base https://example.com/track/.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Shipment Tracking Notification",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "shipment_tracking",
      "languageCode": "tr-TR"
    },
    "isMerge": true
  },
  "recipients": [
    {
      "username": "905554443301",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": ["Ahmet", "TK-98765"]
            },
            {
              "type": "BUTTONS",
              "parameters": ["TK-98765"]
            }
          ]
        }
      }
    },
    {
      "username": "905554443302",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": ["Recep", "TK-12345"]
            },
            {
              "type": "BUTTONS",
              "parameters": ["TK-12345"]
            }
          ]
        }
      }
    }
  ]
}
dica
  • Os parâmetros de BUTTONS são associados conforme a ordem dos botões que contêm variáveis
  • Botões FLOW e botões sem variáveis são ignorados; a indexação se aplica apenas aos botões de URL dinâmica
  • Se a URL do botão do template for https://example.com/track/{{1}}, então parameters[0] substitui {{1}}

5. Envio agendado​

Agende o envio de uma mensagem para uma data e hora futuras. scheduleAt deve ser informado como um timestamp ISO 8601 em UTC.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Morning Campaign Message",
  "scheduleAt": "2026-06-10T07:00:00.000Z",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "morning_campaign",
      "languageCode": "en-US"
    },
    "isMerge": true
  },
  "action": {
    "key": "assign-to-workgroup",
    "value": "WORKGROUP_ID"
  },
  "recipients": [
    {
      "username": "905554443301",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": { "name": "Ahmet", "discountRate": "25" }
            }
          ]
        }
      }
    },
    {
      "username": "905554443302",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": { "name": "Zeynep", "discountRate": "40" }
            }
          ]
        }
      }
    }
  ]
}
dica
  • scheduleAt deve ser informado no fuso horário UTC (por exemplo, para 10:00 no horário da Turquia, use 07:00:00.000Z)
  • Este exemplo usa o formato de parâmetros nomeados; o template deve conter marcadores como {{name}} e {{discountRate}}
  • Com action, as conversas criadas pelo envio da mensagem são atribuídas automaticamente ao grupo de trabalho especificado

Resposta​

Uma requisição bem-sucedida retorna um bulkMessageId, que pode ser usado para acompanhar o processo de envio:

{
  "bulkMessageId": "abc123xyz789"
}

Respostas de erro​

StatusDescrição
Channel not foundNenhum canal verificado correspondente a channelUsername e connectorBrand foi encontrado
Channel is not verifiedO canal correspondente existe, mas ainda não foi verificado
invalidRequestForam informados vários identificadores para um destinatário ou falta um payload obrigatório
channelNotFoundNenhum canal ativo correspondente ao channelId informado foi encontrado
schema-errorUm campo do corpo da requisição falhou na validação do esquema (campo obrigatório ausente, tipo incorreto ou valor não aceito)

O bulkMessageId retornado pode ser usado com os endpoints abaixo para consultar as estatísticas de envio e interromper o processo de envio.

Stats — estatísticas de envio​

Obtém o status atual de envio de uma mensagem em massa. Retorna as contagens de registros pendentes, bem-sucedidos, com falha e cancelados.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/stats.js

Parâmetros da requisição​

ParâmetroTipoObrigatórioDescrição
bulkMessageIdstringSimID da mensagem em massa a acompanhar (retornado por createBulkPerRecipient)
{
  "bulkMessageId": "abc123xyz789"
}
curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/stats.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "bulkMessageId": "abc123xyz789"
}'

Resposta​

{
  "bulkMessage": {
    "_id": "abc123xyz789",
    "slug": "my-workspace",
    "title": "Campaign Title",
    "channelUsername": "908506669933",
    "connectorBrand": "whatsapp",
    "connectorSlug": "whatsapp-cloud",
    "payload": {
      "recipientCount": 100,
      "defaultPayloadType": "template",
      "jobId": "job_abc123"
    },
    "schedule": {
      "date": "2026-06-10T07:00:00.000Z",
      "type": "later"
    },
    "createdAt": "2026-06-08T10:00:00.000Z",
    "updatedAt": "2026-06-08T10:30:00.000Z"
  },
  "stats": {
    "pending": 45,
    "success": 42,
    "failed": 3,
    "cancelled": 10,
    "total": 100
  }
}

Campos de stats​

CampoTipoDescrição
stats.pendingnumberNúmero de registros ainda aguardando na fila
stats.successnumberNúmero de registros processados com sucesso para envio
stats.failednumberNúmero de registros que tiveram um erro de envio
stats.cancellednumberNúmero de registros cancelados
stats.totalnumberNúmero total de registros (pending + success + failed + cancelled)
observação

stats.success indica que a mensagem foi repassada com sucesso pelo sistema. Isso não garante que a Meta entregou a mensagem ao destinatário. As atualizações de status posteriores geradas pela Meta (como delivered, read ou failed) não afetam esse contador e não são refletidas aqui.

Stats e Message Stats
  • Endpoint stats: mostra o status do trabalho de envio (pending, success, failed, cancelled)
  • Endpoint message-stats: mostra o status real da mensagem (pending, sending, sent, delivered, read, error etc.)
  • Um trabalho pode ter sucesso, mas a mensagem ainda pode não ter sido entregue/lida

ID de referência​

O referenceId é um campo opcional que você pode usar para associar os registros de envio a um ID do seu próprio sistema para fins de acompanhamento (por exemplo, número do pedido, ID do ticket).

Se informado, ele deve ser único dentro do envio em massa (máximo de 256 caracteres).

Importante
  • Não é obrigatório
  • Não pode ser duplicado dentro da mesma mensagem em massa
  • Pode ser reutilizado em mensagens em massa diferentes

Message Stats — status das mensagens do WhatsApp​

Obtém as estatísticas de status das mensagens de uma mensagem em massa. Diferentemente do endpoint stats, este mostra o message.status real de cada registro, em vez do status do trabalho.

Status possíveis das mensagens: pending, sending, sent, delivered, read, deleted, warning, error, unknown, not-sended

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/message-stats.js

Parâmetros da requisição​

ParâmetroTipoObrigatórioDescrição
bulkMessageIdstringSimID da mensagem em massa a consultar
{
  "bulkMessageId": "abc123xyz789"
}
curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/message-stats.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "bulkMessageId": "abc123xyz789"
}'

Resposta​

{
  "bulkMessage": {
    "_id": "abc123xyz789",
    "slug": "my-workspace",
    "type": "perRecipient",
    "title": "Campaign Title"
  },
  "messageStats": {
    "pending": 5,
    "sending": 2,
    "sent": 10,
    "delivered": 45,
    "read": 30,
    "deleted": 2,
    "warning": 1,
    "error": 3,
    "unknown": 0,
    "not-sended": 2,
    "no-message": 10,
    "total": 120
  }
}

Campos de message stats​

CampoTipoDescrição
pendingnumberMensagens ainda não enviadas
sendingnumberMensagens sendo enviadas no momento
sentnumberMensagens entregues ao WhatsApp, ainda não entregues ao destinatário
deliverednumberMensagens entregues ao telefone do destinatário
readnumberMensagens lidas pelo destinatário
deletednumberMensagens excluídas
warningnumberMensagens com avisos
errornumberMensagens com erros
unknownnumberMensagens com status desconhecido
not-sendednumberMensagens que não puderam ser enviadas
no-messagenumberRegistros ainda sem mensagem (ainda na fila)
totalnumberTotal de registros
Dicas de uso
  • Uma contagem alta de no-message indica que o envio ainda está em andamento
  • A contagem de delivered mostra as mensagens entregues com sucesso
  • A contagem de read pode ser usada para medir o engajamento da campanha
  • Você pode consultar este endpoint periodicamente para acompanhamento em tempo real

Estrutura de options — paginação, filtragem e ordenação​

O parâmetro options usado nos endpoints list e list-with-messages oferece uma estrutura padrão para paginação, filtragem e ordenação.

Campos de options​

CampoTipoObrigatórioDescrição
paginationobjectNãoConfigurações de paginação
filteringobjectNãoCritérios de filtragem
sortingobjectNãoConfigurações de ordenação (por exemplo, {"createdAt": -1})

Estrutura de paginação​

CampoTipoPadrãoDescrição
currentPagenumber1Número da página a obter
pageItemsnumber50Número de registros por página (máximo: 50)

Estrutura de filtragem​

A filtragem usa o formato de consulta do MongoDB. Você pode filtrar pelos campos do registro. No endpoint list-with-messages, também é possível filtrar pelos campos da mensagem (por exemplo, message.status).

// Filter by record status
{
  "options": {
    "filtering": {
      "status": "success"
    }
  }
}

// Filter by referenceId
{
  "options": {
    "filtering": {
      "referenceId": "ORDER-12345"
    }
  }
}

// Filter by message status (only list-with-messages)
{
  "options": {
    "filtering": {
      "message.status": "delivered"
    }
  }
}

// Filter by multiple statuses using $in (MongoDB operator)
{
  "options": {
    "filtering": {
      "message.status": {
        "$in": ["delivered", "read"]
      }
    }
  }
}

// Exclude specific statuses using $nin (MongoDB operator)
{
  "options": {
    "filtering": {
      "message.status": {
        "$nin": ["error", "not-sended"]
      }
    }
  }
}

Estrutura de ordenação​

A ordenação usa o formato de ordenação do MongoDB. 1 significa crescente e -1 significa decrescente.

// Sort by creation date descending (newest first)
{
  "options": {
    "sorting": {
      "createdAt": -1
    }
  }
}

// Sort by multiple fields
{
  "options": {
    "sorting": {
      "status": 1,
      "createdAt": -1
    }
  }
}

Exemplo de uso combinado​

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 2,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "delivered"
    },
    "sorting": {
      "createdAt": -1
    }
  }
}

Este exemplo ordena as mensagens entregues da mais recente para a mais antiga.

Dicas práticas
  • Combine filtering e pagination para consultas direcionadas
  • A resposta inclui options.pagination.totalCount e options.pagination.totalPages para navegação
  • O filtro message.status só funciona no endpoint list-with-messages

Records — detalhes e listagem de registros​

Lista todos os registros de envio de uma mensagem em massa. Cada registro representa uma única mensagem enviada a um destinatário.

List — lista de registros​

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message-records/list.js

Parâmetros da requisição​

ParâmetroTipoObrigatórioDescrição
bulkMessageIdstringSimID da mensagem em massa a listar
optionsobjectNãoOpções de paginação, filtragem e ordenação. Veja Estrutura de options para mais detalhes.

Requisição — uso básico​

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    }
  }
}

Requisição — filtrar por um status específico​

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "status": "success"
    }
  }
}

Lista apenas os registros de envio bem-sucedidos (record.status = "success").

Resposta​

{
  "bulkMessageRecords": [
    {
      "_id": "record_1",
      "bulkMessageId": "abc123xyz789",
      "slug": "my-workspace",
      "userId": "user_123",
      "sessionId": "session_456",
      "messageId": "msg_789",
      "referenceId": "ORDER-12345",
      "status": "success",
      "createdAt": "2026-06-10T10:00:00.000Z"
    }
  ],
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50,
      "totalCount": 150,
      "totalPages": 3
    },
    "sorting": {},
    "filtering": {}
  }
}

List With Messages — lista com detalhes das mensagens​

Tem os mesmos recursos do endpoint list (paginação, filtragem, ordenação). A única diferença: se um registro tiver um messageId, o objeto message relacionado também é retornado. Isso permite ver o status da mensagem (delivered, read, error etc.) e o payload em uma única consulta.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message-records/list-with-messages.js

Requisição — uso básico​

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    }
  }
}

Requisição — filtrar por status da mensagem​

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "delivered"
    }
  }
}

Este exemplo obtém apenas as mensagens com status "delivered".

Requisição — listar mensagens com falha​

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "error"
    }
  }
}

Usado para revisar as mensagens que tiveram erros de envio.

Resposta​

{
  "bulkMessageRecords": [
    {
      "_id": "record_1",
      "bulkMessageId": "abc123xyz789",
      "userId": "user_123",
      "messageId": "msg_789",
      "referenceId": "ORDER-12345",
      "status": "success",
      "message": {
        "_id": "msg_789",
        "status": "delivered",
        "payload": {
          "type": "template",
          "template": {
            "templateName": "order_notification"
          }
        },
        "createdAt": "2026-06-10T10:01:00.000Z",
        "deliveredAt": "2026-06-10T10:01:05.000Z"
      }
    }
  ],
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50,
      "totalCount": 150,
      "totalPages": 3
    },
    "sorting": {},
    "filtering": {}
  }
}

Campos do registro​

CampoTipoDescrição
_idstringID do registro
bulkMessageIdstringID da mensagem em massa à qual este registro pertence
userIdstringID do usuário destinatário
sessionIdstringID da sessão de conversa
messageIdstringID da mensagem enviada (null se ainda não foi enviada)
referenceIdstringID de referência opcional (se informado)
statusstringStatus do registro: pending, success, failed, cancelled
messageobjectDetalhes da mensagem (somente em list-with-messages)

Comparação entre List e List-With-Messages​

Recursolistlist-with-messages
PaginaçãoSimSim
FiltragemSim (somente campos do registro)Sim (campos do registro e da mensagem)
Objeto messageNãoSim (se messageId existir)
DesempenhoRápidoMédio (executa JOIN)
Filtro message.statusIndisponívelDisponível
Cenários de uso
  • list: liste rapidamente todos os registros, filtre por referenceId, verifique os status dos registros
  • list-with-messages: veja os status das mensagens do WhatsApp (delivered, read), inspecione os payloads das mensagens
  • Exemplos de filtragem:
    • {"status": "failed"} — registros de envio com falha
    • {"referenceId": "ORDER-123"} — um ID de referência específico
    • {"message.status": "delivered"} — mensagens entregues (somente list-with-messages)
    • {"message.status": "read"} — mensagens lidas (somente list-with-messages)
    • {"message.status": "error"} — mensagens com erros (somente list-with-messages)
    • {"message.status": {"$in": ["delivered", "read"]}} — mensagens entregues ou lidas (somente list-with-messages)
    • {"message.status": {"$nin": ["error", "not-sended"]}} — mensagens, exceto as com erro e as não enviadas (somente list-with-messages)
    • {"status": {"$in": ["success", "pending"]}} — registros bem-sucedidos ou pendentes
Observações sobre desempenho e uso
  • O endpoint list é mais rápido; prefira-o para verificações gerais de status
  • Use list-with-messages quando os detalhes da mensagem forem necessários
  • O máximo de registros por página (pageItems) é 50; o padrão é 50 se não for especificado
  • O filtro message.status só funciona em list-with-messages
  • Registros com messageId nulo terão objetos message nulos

Stop — cancelar o envio​

Interrompe o envio em andamento de uma mensagem em massa. O trabalho em fila é cancelado e todos os registros pending passam para o status cancelled. Os registros que já foram processados como success ou failed não são afetados.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/stop.js
aviso

Esta ação não pode ser desfeita. Um envio interrompido não pode ser retomado.

Parâmetros da requisição​

ParâmetroTipoObrigatórioDescrição
bulkMessageIdstringSimID da mensagem em massa a interromper
{
  "bulkMessageId": "abc123xyz789"
}
curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/stop.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "bulkMessageId": "abc123xyz789"
}'

Resposta​

Em uma requisição bem-sucedida, o corpo da resposta fica vazio. Um status HTTP 200 indica que a operação foi concluída com sucesso.

{}
dica
  • Somente as mensagens em massa criadas por esta API podem ser interrompidas
  • Depois de interromper um envio, você pode usar o endpoint stats para verificar o número de registros cancelados
  • Se a mensagem em massa não for encontrada, a API retorna o erro: bulkMessageNotFound