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": {}
}Referência da API
POST /external/campaigns/dispatch
Dispara uma campanha RCS para até 2.000 destinatários
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 scopecampaigns: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
Show Propriedades de cada mensagem
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"
}'