Skip to main content
POST
/
api
/
v1
/
external
/
campaigns
/
dispatch
curl -X POST https://api-hub-campaign.convertt.ai/api/v1/external/campaigns/dispatch \
  -H "Authorization: Bearer eyJhbG..." \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Promoção Black Friday 2025",
    "templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "messages": [
      {
        "phone": "5511999999999",
        "uid": "user-001",
        "vars": { "nome": "João", "desconto": "30%" }
      },
      {
        "phone": "5521988888888",
        "uid": "user-002",
        "vars": { "nome": "Maria", "desconto": "25%" }
      }
    ],
    "batch": "batch-001"
  }'

{
  "campaignId": "<string>",
  "status": "<string>",
  "accepted": 123,
  "rejected": 123,
  "feedback": {}
}

​
Autenticação

Requer OAuth Bearer token com scope campaigns:dispatch. 
Authorization: Bearer {access_token}

​
Request Body

​
campaignId
string
required
UUID da campanha. Controlado pelo cliente — será usado como identificador interno.
​
name
string
required
Nome da campanha. Deve ser único por tenant.
​
templateId
string
required
UUID do template RCS a ser usado. Deve pertencer ao mesmo tenant.
​
messages
array
required
Array de mensagens (máximo 2.000 por chamada).
​
batch
string
Identificador do lote. Obrigatório quando campaignId já existe (batch incremental); deve ser único por campanha.
​
schedule
string
Data/hora ISO 8601 para agendamento (fuso horário America/Sao_Paulo). Deve ser no mínimo 5 minutos no futuro.

​
Resposta de Sucesso (202 Accepted)

{
  "campaignId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "sending",
  "accepted": 1950,
  "rejected": 50,
  "feedback": {
    "invalidPhones": [
      { "phone": "123", "reason": "Número inválido: 123..." }
    ],
    "errorFileUrl": "https://s3.../errors.csv"
  }
}
​
campaignId
string
UUID da campanha criada.
​
status
string
sending para envio imediato, scheduled para agendamento.
​
accepted
number
Quantidade de mensagens aceitas para envio.
​
rejected
number
Quantidade de mensagens rejeitadas (telefones inválidos).
​
feedback
object
Detalhes dos erros. Se houver mais de 5 telefones inválidos, um arquivo CSV com os erros é gerado e retornado em errorFileUrl.

​
Validações

ValidaçãoErro
campaignId não é UUID400 Bad Request
templateId não existe404 Not Found
Template pertence a outro tenant403 Forbidden
Nome de campanha duplicado409 Conflict
messages vazio ou > 2000400 Bad Request
uid ausente em alguma mensagem400 Bad Request
Variáveis do template ausentes400 Bad Request
schedule < 5 minutos no futuro400 Bad Request
batch ausente em disparo para campanha existente400 Bad Request
batch já utilizado nesta campanha409 Conflict
Número já despachado em batch anterior409 Conflict
campaignId já existe com nome diferente409 Conflict
curl -X POST https://api-hub-campaign.convertt.ai/api/v1/external/campaigns/dispatch \
  -H "Authorization: Bearer eyJhbG..." \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Promoção Black Friday 2025",
    "templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "messages": [
      {
        "phone": "5511999999999",
        "uid": "user-001",
        "vars": { "nome": "João", "desconto": "30%" }
      },
      {
        "phone": "5521988888888",
        "uid": "user-002",
        "vars": { "nome": "Maria", "desconto": "25%" }
      }
    ],
    "batch": "batch-001"
  }'