Campaigns API: gerencie públicos e mensagens

A Campaigns API permite gerenciar programaticamente o público e a entrega de mensagens de campanhas evergreen (contínuas) no seu workspace BluBash. Você pode adicionar contatos individualmente ou em massa com agendamento por contato, cancelar mensagens em fila antes de serem enviadas e inspecionar o status das mensagens em qualquer ponto do ciclo de entrega.

O recurso de Campanhas precisa estar habilitado na assinatura do seu workspace para usar os endpoints de escrita. Endpoints de leitura (listar e obter mensagens) podem funcionar mesmo sem o recurso habilitado. Se você tentar uma operação de escrita sem o recurso, receberá uma resposta 403 Forbidden.

URL base

https://api.blubash.io/api/v1/campaigns

Autenticação

Todas as requisições exigem sua Workspace API Key no cabeçalho X-API-Key.

X-API-Key: your_workspace_api_key
Content-Type: application/json

Para obter sua chave de API, vá até Configurações → API Keys no painel de administração do seu workspace.

Pré-requisitos

As campanhas evergreen precisam ser criadas e configuradas na plataforma BluBash antes de você usar essa API. A API cobre apenas a ingestão de público e o disparo de mensagens.

Crie uma campanha evergreen na plataforma

No painel de administração do BluBash, crie uma nova campanha com kind = EVERGREEN.

Configure canal, mensagem e limites de taxa

Configure o canal, o template de mensagem e as regras de rate limit da campanha.

Copie o campaignId

Salve a campanha e copie o campaignId mostrado na plataforma. Você usará esse ID em todas as chamadas de API abaixo.

Adicionar contatos ao público

POST /api/v1/campaigns/:campaignId/audience

Adiciona um ou mais contatos a uma campanha e define o agendamento de envio por contato. Cada entrada no array items representa um contato e sua configuração de agendamento.

Para adicionar um único contato, envie o array items com um único elemento — o endpoint é o mesmo para operações individuais e em lote.

Corpo da requisição

string

Um nome de fuso horário IANA (por exemplo, America/New_York) aplicado a todos os itens cujo datetime não tem offset UTC e nenhum schedule.timezone foi especificado.

array

obrigatório

Um array de objetos de contato + agendamento. Pelo menos um item é obrigatório.

Mostrar Campos do item

string

O ID de um contato existente no seu workspace. Obrigatório se identifier não for fornecido.

string

O identificador de canal do contato (por exemplo, um número de telefone do WhatsApp). Obrigatório se contact_id não for fornecido. Usado para localizar ou criar o contato.

string

Nome de exibição do contato. Usado ao criar um novo registro de contato.

string

Endereço de e-mail do contato. Usado para localização e criação do contato.

object

Valores de campos personalizados como um objeto chave-valor. As chaves precisam ter o prefixo cf_ (por exemplo, { "cf_plan": "pro" }).

string[]

Tags a aplicar ao contato. As tags são normalizadas automaticamente (com trim, lowercase e deduplicação) e aplicadas de forma aditiva — tags existentes não são removidas.

object

Agendamento de envio para este contato. Padrão é immediate se omitido.

Mostrar Campos de schedule

string

obrigatório

immediate para enviar o quanto antes ou absolute para agendar para uma data e hora específicas.

string

Datetime no formato ISO 8601. Obrigatório quando type for absolute. Se o valor incluir um offset UTC ou Z, o campo timezone é ignorado. Se não houver offset, você precisa informar schedule.timezone ou default_schedule_timezone.

string

Nome de fuso horário IANA para converter um datetime sem offset UTC para UTC.

Resolução de contato

Quando você fornece identifier em vez de contact_id, a plataforma resolve o contato nesta ordem:

Procura o contato pelo identificador do canal (por exemplo, número de WhatsApp normalizado).
Se não encontrar e email for fornecido, busca por e-mail (sem diferenciar maiúsculas e minúsculas).
- Se encontrar sem identificador de canal, vincula o identifier ao contato.
- Se encontrar com um identificador de canal diferente, retorna um erro 400 para evitar fusão silenciosa de identidades.
Se ainda não encontrar, cria um novo contato usando name, email e identifier.

Regras de agendamento

Formato do `datetime`	Comportamento
Com `Z` ou offset numérico (por exemplo, `+03:00`, `-0500`)	Tratado como instante absoluto; `timezone` é ignorado
Sem offset (por exemplo, `2026-03-11T09:00:00`)	Requer `schedule.timezone` ou `default_schedule_timezone` para conversão para UTC

Se datetime não tem offset UTC e nenhum fuso horário foi fornecido (em schedule.timezone ou default_schedule_timezone), a requisição retorna um erro 400.

Exemplo de requisição

{
  "default_schedule_timezone": "America/New_York",
  "items": [
    {
      "contact_id": "<CONTACT_ID_1>",
      "schedule": {
        "type": "immediate"
      }
    },
    {
      "identifier": "5511999999999",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "custom_fields": {
        "cf_plan": "pro",
        "cf_source": "api"
      },
      "tags": ["Hot Lead", "VIP Customer"],
      "schedule": {
        "type": "absolute",
        "datetime": "2026-03-10T14:30:00.000Z"
      }
    },
    {
      "contact_id": "<CONTACT_ID_3>",
      "schedule": {
        "type": "absolute",
        "datetime": "2026-03-11T09:00:00",
        "timezone": "America/New_York"
      }
    }
  ]
}

Campos da resposta

array

obrigatório

Uma entrada por item de entrada, na mesma ordem da requisição.

Mostrar Campos do item

string

ID da mensagem de campanha criada para este contato.

string

ID do contato resolvido ou criado.

string | null

O horário de envio agendado formatado no fuso horário IANA ou no offset fornecido. null para envios imediatos.

string | null

O horário de envio canônico em UTC (sempre termina em Z). null para envios imediatos.

string | null

O nome de fuso horário IANA (por exemplo, America/New_York) ou offset numérico (por exemplo, -05:00) usado para o agendamento. null para envios imediatos.

Exemplo de resposta

{
  "items": [
    {
      "messageId": "<MESSAGE_ID>",
      "contactId": "<CONTACT_ID_1>",
      "scheduled_at": null,
      "scheduled_at_utc": null,
      "timezone": null
    },
    {
      "messageId": "<MESSAGE_ID>",
      "contactId": "<CONTACT_ID_2>",
      "scheduled_at": "2026-03-10T14:30:00.000Z",
      "scheduled_at_utc": "2026-03-10T14:30:00.000Z",
      "timezone": null
    },
    {
      "messageId": "<MESSAGE_ID>",
      "contactId": "<CONTACT_ID_3>",
      "scheduled_at": "2026-03-11T09:00:00.000-05:00",
      "scheduled_at_utc": "2026-03-11T14:00:00.000Z",
      "timezone": "America/New_York"
    }
  ]
}

Cancelar uma mensagem em fila

POST /api/v1/campaigns/:campaignId/messages/:messageId/cancel

Cancela a entrega de uma mensagem específica de campanha que ainda está na fila. Cancelar uma mensagem não afeta nenhuma outra mensagem da campanha.

Apenas mensagens com status QUEUED podem ser canceladas. Mensagens que já estão SENDING, SENT ou FAILED não podem ser canceladas.

Resposta

{
  "id": "<MESSAGE_ID>",
  "status": "CANCELLED"
}

Listar mensagens da campanha

GET /api/v1/campaigns/:campaignId/messages?limit=50&offset=0

Retorna uma lista paginada de mensagens da campanha, cada uma com seu status atual.

Parâmetros de query

number

padrão:"50"

Número de resultados a retornar por página.

number

padrão:"0"

Número de resultados a pular para paginação.

Obter uma mensagem específica

GET /api/v1/campaigns/:campaignId/messages/:messageId

Retorna os detalhes e o status atual de uma única mensagem da campanha.

Status das mensagens

Status	Descrição
`PENDING`	Aguardando processamento
`QUEUED`	Em fila para entrega — pode ser cancelada
`SENDING`	Sendo enviada no momento
`SENT`	Entregue com sucesso
`FAILED`	Falha na entrega
`CANCELLED`	Cancelada via API

Fluxo recomendado

Configure a campanha na plataforma

Crie uma campanha evergreen no painel de administração do BluBash e copie o campaignId.

Adicione contatos ao público

Chame POST /api/v1/campaigns/:campaignId/audience com seu array items.

Escolha um agendamento por contato

Use schedule.type = immediate para entrega instantânea, ou schedule.type = absolute com um datetime para entrega agendada.

Cancele se necessário

Se você precisar parar uma mensagem em fila, chame POST /api/v1/campaigns/:campaignId/messages/:messageId/cancel.

Monitore o status das mensagens

Use GET /api/v1/campaigns/:campaignId/messages para inspecionar o status de entrega ao longo da campanha.

Exemplos de código

curl -X POST https://api.blubash.io/api/v1/campaigns/{campaignId}/audience \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "identifier": "5511999999999",
        "name": "Jane Smith",
        "tags": ["Hot Lead"],
        "schedule": {
          "type": "immediate"
        }
      }
    ]
  }'

curl -X POST https://api.blubash.io/api/v1/campaigns/{campaignId}/audience \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "default_schedule_timezone": "America/New_York",
    "items": [
      {
        "contact_id": "contact_abc123",
        "schedule": {
          "type": "absolute",
          "datetime": "2026-04-01T10:00:00"
        }
      }
    ]
  }'

curl -X POST https://api.blubash.io/api/v1/campaigns/{campaignId}/audience \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "default_schedule_timezone": "America/New_York",
    "items": [
      {
        "contact_id": "contact_001",
        "schedule": { "type": "immediate" }
      },
      {
        "identifier": "5511888887777",
        "name": "Pedro Lima",
        "custom_fields": {
          "cf_plan": "enterprise"
        },
        "tags": ["VIP Customer", "Hot Lead"],
        "schedule": {
          "type": "absolute",
          "datetime": "2026-04-05T09:00:00",
          "timezone": "America/New_York"
        }
      },
      {
        "contact_id": "contact_003",
        "schedule": {
          "type": "absolute",
          "datetime": "2026-04-06T12:00:00.000Z"
        }
      }
    ]
  }'

curl -X POST https://api.blubash.io/api/v1/campaigns/{campaignId}/messages/{messageId}/cancel \
  -H "X-API-Key: your_api_key"

curl -X GET "https://api.blubash.io/api/v1/campaigns/{campaignId}/messages?limit=50&offset=0" \
  -H "X-API-Key: your_api_key"

Referência de erros

Status	Mensagem	Causa
`400`	`Each item must provide contact_id or identifier`	Um item não tem nem `contact_id` nem `identifier`
`400`	`Identifier is invalid`	`identifier` está vazio ou é inválido após normalização
`400`	`schedule.timezone (IANA) is required when datetime has no UTC offset`	`datetime` não tem offset e nenhum fuso horário foi fornecido
`400`	`Campaign is not an evergreen campaign`	O `campaignId` pertence a uma campanha não evergreen
`400`	`Cannot add contacts to cancelled or failed campaigns`	O status da campanha é `CANCELLED` ou `FAILED`
`400`	`Cannot add contacts while the campaign is paused. Resume the campaign first.`	O status da campanha é `PAUSED`
`400`	`Contact found by email already has a different identifier for this campaign channel`	A busca por e-mail encontrou um contato com um identificador de canal conflitante
`400`	`Contact does not have a valid channel identifier for this campaign channel`	O contato resolvido não tem identificador válido para o canal da campanha
`401`	—	Chave de API ausente ou inválida
`403`	`Campaigns feature is not available in your current plan`	O recurso de Campanhas não está habilitado na sua assinatura
`404`	`Campaign not found`	O `campaignId` não existe no seu workspace

​URL base

​Autenticação

​Pré-requisitos

​Adicionar contatos ao público

​Corpo da requisição

​Resolução de contato

​Regras de agendamento

​Exemplo de requisição

​Campos da resposta

​Exemplo de resposta

​Cancelar uma mensagem em fila

​Resposta

​Listar mensagens da campanha

​Parâmetros de query

​Obter uma mensagem específica

​Status das mensagens

​Fluxo recomendado

​Exemplos de código

​Referência de erros

URL base

Autenticação

Pré-requisitos

Adicionar contatos ao público

Corpo da requisição

Resolução de contato

Regras de agendamento

Exemplo de requisição

Campos da resposta

Exemplo de resposta

Cancelar uma mensagem em fila

Resposta

Listar mensagens da campanha

Parâmetros de query

Obter uma mensagem específica

Status das mensagens

Fluxo recomendado

Exemplos de código

Referência de erros