Envio em Lote

Cada chamada à API aceita no máximo 2.000 mensagens. Para campanhas maiores, você tem duas opções:

Batches independentes — cada chamada usa um campaignId diferente. Cada um é uma campanha separada no dashboard.
Batches incrementais — múltiplas chamadas usam o mesmo campaignId e name, com o campo batch obrigatório e único por envio. O resultado é uma única campanha no dashboard com os destinatários acumulados.

Batches Incrementais (Mesma Campanha)

Use esta abordagem quando quiser que todos os destinatários apareçam sob uma única campanha no dashboard. Regras:

campaignId e name devem ser idênticos em todas as chamadas
batch é obrigatório a partir do segundo envio (recomendado desde o primeiro)
O nome do batch deve ser único dentro da campanha
O mesmo número de telefone não pode aparecer em dois batches da mesma campanha

import uuid
import requests

API_URL = "https://api-hub-campaign.convertt.ai/api/v1/"
TOKEN = "seu-access-token"
TEMPLATE_ID = "seu-template-id"
CAMPAIGN_ID = str(uuid.uuid4())  # ← mesmo em todas as chamadas
CAMPAIGN_NAME = "Black Friday 2025"  # ← mesmo em todas as chamadas
BATCH_SIZE = 2000

all_recipients = load_recipients()  # ex: 10.000 registros

for i in range(0, len(all_recipients), BATCH_SIZE):
    batch = all_recipients[i:i + BATCH_SIZE]
    batch_number = (i // BATCH_SIZE) + 1

    response = requests.post(
        f"{API_URL}/external/campaigns/dispatch",
        headers={
            "Authorization": f"Bearer {TOKEN}",
            "Content-Type": "application/json"
        },
        json={
            "campaignId": CAMPAIGN_ID,          # ← SEMPRE O MESMO
            "name": CAMPAIGN_NAME,              # ← SEMPRE O MESMO
            "templateId": TEMPLATE_ID,
            "batch": f"lote-{batch_number}",   # ← ÚNICO POR ENVIO
            "messages": [
                {"phone": r["phone"], "uid": r["id"], "vars": r.get("vars", {})}
                for r in batch
            ]
        }
    )

    result = response.json()
    print(f"Batch {batch_number}: {result['accepted']} aceitas, {result['rejected']} rejeitadas")

Erros possíveis:

Status	Motivo
400	Campo `batch` ausente no segundo+ envio
409	Nome de `batch` já utilizado nesta campanha
409	Número de telefone já presente em batch anterior
409	`campaignId` usado para uma campanha de nome diferente

Estratégia Multi-Batch

Cada chamada é processada independentemente. O campo batch é apenas metadado para sua referência.

import uuid
import requests

API_URL = "https://api-hub-campaign.convertt.ai/api/v1/"
TOKEN = "seu-access-token"
TEMPLATE_ID = "seu-template-id"
BATCH_SIZE = 2000

# Sua lista completa de destinatários
all_recipients = load_recipients()  # ex: 10.000 registros

# Dividir em batches
for i in range(0, len(all_recipients), BATCH_SIZE):
    batch = all_recipients[i:i + BATCH_SIZE]
    batch_number = (i // BATCH_SIZE) + 1

    campaign_id = str(uuid.uuid4())

    payload = {
        "campaignId": campaign_id,
        "name": f"Campanha Nov 2025 - Batch {batch_number}",
        "templateId": TEMPLATE_ID,
        "messages": [
            {
                "phone": r["phone"],
                "uid": r["id"],
                "vars": r.get("vars", {})
            }
            for r in batch
        ],
        "batch": f"batch-{batch_number}"
    }

    response = requests.post(
        f"{API_URL}/external/campaigns/dispatch",
        headers={
            "Authorization": f"Bearer {TOKEN}",
            "Content-Type": "application/json"
        },
        json=payload
    )

    result = response.json()
    print(f"Batch {batch_number}: {result['accepted']} aceitas, {result['rejected']} rejeitadas")

Boas Práticas

Trate erros por batch

Se um batch falhar, reenvie apenas ele. Os outros batches não são afetados.

Monitore via webhook

Configure webhooks para acompanhar o status de entrega em tempo real, ao invés de consultar o dashboard manualmente.

Respeite os rate limits

Mantenha no máximo 60 chamadas por minuto. Adicione um intervalo entre os batches se necessário.

Mapeamento de Resultados

Use o campo uid para correlacionar os webhooks de status com seus registros internos:

Disparo: uid="user-123" → Webhook: uid="user-123", status="delivered"

Início

Guias

Batches Incrementais (Mesma Campanha)

Estratégia Multi-Batch

Boas Práticas

Mapeamento de Resultados

​Batches Incrementais (Mesma Campanha)

​Estratégia Multi-Batch

​Boas Práticas

​Mapeamento de Resultados

Batches Incrementais (Mesma Campanha)

Estratégia Multi-Batch

Boas Práticas

Mapeamento de Resultados