POST /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": {}
}

POST

api

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

string

required

UUID da campanha. Controlado pelo cliente — será usado como identificador interno.

string

required

Nome da campanha. Deve ser único por tenant.

string

required

UUID do template RCS a ser usado. Deve pertencer ao mesmo tenant.

array

required

Array de mensagens (máximo 2.000 por chamada).

Show Propriedades de cada mensagem

string

required

Número do destinatário. Formatos aceitos: 5511999999999, 11999999999, +5511999999999.

string

required

Identificador único da mensagem no sistema do cliente. Retornado nos webhooks para correlação.

object

Variáveis dinâmicas do template. Ex: {"nome": "João", "produto": "TV"}.

string

Identificador do lote. Obrigatório quando campaignId já existe (batch incremental); deve ser único por campanha.

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"
  }
}

string

UUID da campanha criada.

string

sending para envio imediato, scheduled para agendamento.

number

Quantidade de mensagens aceitas para envio.

number

Quantidade de mensagens rejeitadas (telefones inválidos).

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ção	Erro
`campaignId` não é UUID	400 Bad Request
`templateId` não existe	404 Not Found
Template pertence a outro tenant	403 Forbidden
Nome de campanha duplicado	409 Conflict
`messages` vazio ou > 2000	400 Bad Request
`uid` ausente em alguma mensagem	400 Bad Request
Variáveis do template ausentes	400 Bad Request
`schedule` < 5 minutos no futuro	400 Bad Request
`batch` ausente em disparo para campanha existente	400 Bad Request
`batch` já utilizado nesta campanha	409 Conflict
Número já despachado em batch anterior	409 Conflict
`campaignId` já existe com nome diferente	409 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"
  }'

​Autenticação

​Request Body

​Resposta de Sucesso (202 Accepted)

​Validações

Autenticação

Request Body

Resposta de Sucesso (202 Accepted)

Validações