Campanhas

Criar campanha

Changed on Oct 12, 2026

Cria a campanha, valida template e variáveis, reserva a cota do plano e debita o custo total da carteira antes de enfileirar. Os envios rodam em segundo plano. Contatos bloqueados no envio (opt-out, número inválido, limite de frequência) são estornados um a um.

Idempotency-Key é obrigatório. Repetir a chave devolve a campanha já criada, sem cobrar de novo. A unicidade da chave é global na Arara, não por organização: derive do identificador da campanha no seu sistema, com um prefixo só seu (ex. acme-campanha-8842).
scheduledAt agenda o envio, entre 5 minutos e 30 dias à frente. A campanha nasce SCHEDULED, já cobrada. Fora da janela: 400 CAMPAIGN_SCHEDULE_TOO_SOON ou 400 CAMPAIGN_SCHEDULE_TOO_FAR.
abTest cria o teste A/B junto com a campanha. templateName é a variante A.

Pré-requisitos: número dedicado conectado (403 NO_DEDICATED_NUMBER), saldo para o total (402 INSUFFICIENT_FUNDS) e cota do plano (403 PLAN_LIMIT_REACHED).

Permissão: CAMPAIGNS_SEND.

post/v1/campaigns

Request

Base URL
https://api.ararahq.com
Auth
HTTP bearer
TypeScript
https://skmtc.dev/ararahq/apis/ararahq-api/docs/v1/campaigns/post.ts
A function with typed inputs. Its response is checked against the schema.

Headers

Idempotency-Keystring required

Identificador único da campanha. Derive do identificador da campanha no seu sistema (ex. acme-campanha-8842) e reuse a mesma chave nas retentativas. A unicidade é global na Arara.

Request body

namestring required

Nome interno da campanha.

templateNamestring required

Nome ou ID do template aprovado. Com abTest, é a variante A.

senderstring nullable

Número que envia. Omitido, usa o padrão da organização.

scheduledAtstring date-time nullable

Agenda o envio (ISO 8601), entre 5 minutos e 30 dias no futuro.

Example request

{
  "contacts": [
    {
      "to": "+5511999999999"
    }
  ]
}

Response

Campanha criada (ou existente, se a chave já foi usada)

idstring uuid required

namestring required

SCHEDULED: agendada, aguardando o horário.
INGESTING: processando contatos e enfileirando envios.
AB_TESTING: teste A/B em andamento.
COMPLETED: todos os contatos processados.
COMPLETED_WITH_ERRORS: processada, com contatos bloqueados.
FAILED: falha geral no processamento.
CANCELED: cancelada.

totalMessagesinteger required

totalCostnumber required

Valor já debitado da carteira, em reais. Os valores dos exemplos são ilustrativos.

scheduledAtstring date-time nullable

Example response

{
  "id": "7b3789fb-4c5d-6789-abcd-ef0123456789",
  "name": "Black Friday 2026",
  "status": "INGESTING",
  "totalMessages": 2,
  "totalCost": 0.767,
  "scheduledAt": null
}

Changes

Oct 12, 2026d576cd28afc0 Revision changes
- info
  api tag Campanhas added
- info
  api tag campaigns removed
- info
  added the non-success response with the status
Sep 15, 2026372d8c2e735d Revision changes
- breaking
  the response's body type changed from object to no type for status
- breaking
  the response property / became nullable for the status
- breaking
  the response property became optional for the status
- breaking
  the response's property type changed from object to string for status
- breaking
  the response's property format changed from float to no format for status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- warning
  for the header request parameter Idempotency-Key, the maxLength was set to 255
- warning
  removed the optional property / from the response with the status
- warning
  added the new AB_TESTING enum value to the response property for the response status
- warning
  added the new CANCELED enum value to the response property for the response status
- warning
  added the new COMPLETED enum value to the response property for the response status
- warning
  added the new COMPLETED_WITH_ERRORS enum value to the response property for the response status
- warning
  added the new FAILED enum value to the response property for the response status
- warning
  added the new INGESTING enum value to the response property for the response status
- warning
  added the new SCHEDULED enum value to the response property for the response status
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added to the response body anyOf list for the response status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  removed the non-success response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status

Operation history (3 revisions)