Criar disparo

Endpoint

POST /v1/broadcasts

Escopo necessário: write:broadcasts O disparo nasce em draft. Nada é enviado até você chamar Lançar disparo.

A segmentação fica dentro de audience.rules (ou, no formato anterior, audience.filters), não na raiz de audience. Um corpo com as condições no lugar errado é aceito com 201 — e o disparo sai para toda a base. Confira o aninhamento antes de lançar, e use Estimar audiência para conferir o alcance.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome da campanha. De 3 a 200 caracteres
`whatsappInstances`	string[]	Sim	IDs dos números do WhatsApp. De 1 a 20
`audience`	object	Sim	Segmentação. Ver abaixo
`message`	object	Sim	Conteúdo a enviar. Ver abaixo
`sendConfig`	object	Não	Ritmo, janela de envio e agendamento
`cloudTemplate`	object \| null	Não	Modelo aprovado, obrigatório em disparos pelo WhatsApp Oficial. Envie `null` em disparos por QR Code
`description`	string	Não	Descrição. Até 1000 caracteres

Todos os números do disparo precisam ser do mesmo canal: ou todos por QR Code, ou todos do WhatsApp Oficial. Misturar devolve 422 MIXED_PROVIDERS.

Objeto `audience`

Campo	Tipo	Padrão	Descrição
`type`	string	`filtered`	`filtered` (todos que passam nas regras) ou `manual` (`manualContactIds`)
`rules`	object	—	Regras de segmentação em dois níveis (E/OU). Ver tabela abaixo. Quando presente, decide sozinha quem recebe
`filters`	object	`{}`	Formato anterior, plano. Continua aceito: sem `rules`, é convertido em regras na entrada. Ver tabela abaixo
`manualContactIds`	string[]	`[]`	IDs específicos de contatos
`exclusions`	object	ver abaixo	Quem fica de fora
`estimatedCount`	number	—	Alcance estimado, se você já calculou
`includeAiOwnedConversations`	boolean	`false`	Enviar também para quem está sendo atendido por um agente de IA (por padrão fica de fora, como `skippedByReason.conversa_com_ia`)

`audience.rules`

{
  "match": "all",
  "groups": [
    {
      "match": "any",
      "conditions": [
        { "field": "conversation", "op": "not_within_days", "value": 7 },
        { "field": "conversation", "op": "never" }
      ]
    },
    { "match": "all", "conditions": [{ "field": "lifecycle", "op": "in", "value": ["customer"] }] }
  ],
  "exclude": [{ "field": "broadcast_replied", "op": "within_days", "value": 3 }]
}

Campo	Tipo	Descrição
`match`	string	Como os grupos se combinam: `all` (E, padrão) ou `any` (OU)
`groups[].match`	string	Como as condições do grupo se combinam: `all` (E, padrão) ou `any` (OU)
`groups[].conditions[]`	object	`{ field, op, value }`. Ver campos abaixo
`exclude[]`	object	Condições de exclusão: qualquer uma que o contato atenda o tira do disparo

Sem grupos e sem exclusões, entra toda a base com WhatsApp. Limites: 10 grupos, 15 condições por grupo, 15 exclusões, 100 IDs por condição. Campos e operadores (field → op · tipo de value):

`field`	Operadores	`value`
`tags`	`any`, `all`, `none` · `empty`	IDs ou nomes de tags (string[]) · —
`lifecycle`	`in`, `not_in`	`lead`, `opportunity`, `customer`, `former_customer` (string[])
`source`	`in`, `not_in`	`whatsapp`, `instagram`, `messenger`, `web_chat`, `phone`, `manual`, `import`, `automation`, `api`, `integration` (string[])
`owner`	`is`, `is_not` · `assigned`, `unassigned`	IDs de usuários (string[]) · —
`company`	`is`, `is_not` · `exists`, `not_exists`	IDs de empresas (string[]) · —
`segment`	`in`, `not_in`	IDs de segmentos salvos da tela de Contatos (string[])
`email`	`exists`, `not_exists`	—
`job_title`	`contains`, `not_contains`, `equals` · `exists`, `not_exists`	texto (até 200) · —
`created_at`	`within_days`, `not_within_days` · `after`, `before` · `between`	dias (1–3650) · data ISO · `{ from, to }`
`conversation`	`within_days`, `not_within_days`, `never`, `ever`	dias · —
`contact_message`	idem	Última mensagem recebida do contato
`broadcast_received`	idem	Recebeu qualquer disparo
`broadcast_replied`	idem	Respondeu a qualquer disparo
`broadcast_specific`	`received`, `not_received`, `replied`, `not_replied`	IDs de disparos (string[]). `not_replied` = recebeu e não respondeu
`deal`	`has`, `has_not`	`{ status: "any"\|"open"\|"won"\|"lost", pipelineId?, stageId? }`
`custom:<key>`	conforme o tipo do campo personalizado	texto: como `job_title` · número: `equals`, `not_equals`, `gt`, `lt` · sim/não: `is_true`, `is_false` · seleção: `in`, `not_in` · múltipla: `any`, `none` · data: como `created_at`

not_within_days nos campos de evento (conversation, contact_message, broadcast_*) inclui quem nunca teve o evento — é o que uma reativação quer. Em created_at significa “cadastrado há mais de N dias”. Para consultar os campos personalizados disponíveis na sua organização, use a tela de segmentação de audiência no painel. A API pública v1 não oferece um endpoint de catálogo de audiência.

`audience.filters` (formato anterior)

Campo	Tipo	Descrição
`tags`	string[]	Nomes ou IDs de tags. Nome desconhecido não cria tag — apenas não casa com ninguém
`tagsOperator`	string	`or` (padrão) ou `and`
`hasWhatsapp`	boolean	Apenas contatos com WhatsApp vinculado
`hasOptIn`	boolean	Apenas contatos com consentimento de marketing registrado
`createdAfter`	string	ISO 8601 — contatos criados após esta data
`createdBefore`	string	ISO 8601 — contatos criados antes desta data
`assignedTo`	string	ID do vendedor: só a carteira dele
`hasOwner`	boolean	`false` = só contatos sem dono; `true` = só com dono
`companyId`	string	ID da empresa
`source`	string	Origem do contato (`whatsapp`, `instagram`, `manual`, `import`…)
`lastContactOlderThanDays`	number	Reativação: sem contato há mais de N dias (inclui quem nunca teve contato)
`lifecycleStages`	string[]	`lead`, `opportunity`, `customer`, `former_customer`
`segmentId`	string	Segmento salvo da tela de Contatos — aplica os filtros e a busca dele
`dealFilter`	object	Filtro por negócios abertos. Ver abaixo

`audience.filters.dealFilter`

Campo	Tipo	Descrição
`mode`	string	`none` (padrão), `exclude_active` ou `include_active`
`pipelineId`	string	Restringe a um funil. Obrigatório se você informar `stageId`
`stageId`	string	Restringe a uma etapa

`audience.exclusions`

Campo	Tipo	Padrão	Descrição
`recentBroadcastHours`	number	`24`	Pula quem já recebeu disparo nas últimas N horas
`blockedContacts`	boolean	`true`	Pula contatos bloqueados
`contactIds`	string[]	—	IDs a excluir explicitamente

Objeto `message`

Campo	Tipo	Descrição
`type`	string	`text` (padrão), `media`, `document` ou `audio`
`text`	string	Texto da mensagem, até 5000 caracteres. Aceita variáveis do contato
`media`	object	`{url, mimetype, filename, caption}` para os tipos não-texto

Objeto `sendConfig`

Campo	Tipo	Descrição
`profile`	string	`conservative`, `moderate` ou `aggressive`. O perfil `custom` é exclusivo do painel web e devolve `400 UNSUPPORTED_PROFILE`
`sendWindow`	object	`{startHour, endHour, timezone, daysOfWeek, pauseWindows}` — ver Configurar envio
`scheduledFor`	string \| null	ISO 8601. Com data futura, o lançamento apenas agenda em vez de disparar

Objeto `cloudTemplate`

Obrigatório quando os números do disparo são do WhatsApp Oficial. Em disparos por QR Code, envie null (ou omita) — mandar um modelo devolve 422 TEMPLATE_ON_QRCODE_BROADCAST.

Campo	Tipo	Obrigatório	Descrição
`templateId`	string	Sim	ID de um modelo aprovado da própria organização
`language`	string	Não	Idioma do modelo. Se omitido, usa o do próprio modelo
`variables`	array	Não	Mapeamento das variáveis. Até 50

Objeto `variables[]`

Campo	Tipo	Padrão	Descrição
`key`	string	—	Nome da variável no modelo. Até 60 caracteres
`component`	string	`body`	`header`, `body` ou `button:N` (`N` = índice do botão, para link dinâmico e cupom)
`sourceType`	string	`contact_field`	`contact_field` (puxa do contato) ou `static` (texto fixo)
`sourceKey`	string	—	Campo do contato, quando `sourceType` é `contact_field`
`fallback`	string	—	Texto alternativo quando o contato não tem o dado
`value`	string	—	Texto fixo, quando `sourceType` é `static`

Toda variável precisa resolver para algum texto: com sourceType: "static", o value é obrigatório; com contact_field, sourceKey e fallback são os dois obrigatórios. Sem texto alternativo, quem não tiver o dado receberia a mensagem com um buraco — “Olá , temos uma novidade”.

Exemplo — disparo por QR Code, segmentado por tag

curl -X POST https://api.socialsell.ai/v1/broadcasts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aviso de manutenção",
    "whatsappInstances": ["6643cb19da1774a51495b603"],
    "audience": {
      "type": "filtered",
      "filters": {
        "tags": ["cliente"],
        "tagsOperator": "or",
        "hasWhatsapp": true
      },
      "exclusions": { "recentBroadcastHours": 48 }
    },
    "message": {
      "type": "text",
      "text": "Olá {{nome_cliente}}! Informamos manutenção programada no dia 15/06."
    },
    "sendConfig": { "profile": "moderate" },
    "cloudTemplate": null
  }'

Exemplo — disparo pelo WhatsApp Oficial com modelo

curl -X POST https://api.socialsell.ai/v1/broadcasts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Retomada de carrinho",
    "whatsappInstances": ["6643cb19da1774a51495b603"],
    "audience": {
      "type": "filtered",
      "filters": {
        "hasWhatsapp": true,
        "dealFilter": { "mode": "include_active", "pipelineId": "664a1b2c3d4e5f6789012345" }
      }
    },
    "message": { "type": "text", "text": "" },
    "cloudTemplate": {
      "templateId": "66462c8e7962a7d357cdb272",
      "language": "pt_BR",
      "variables": [
        { "key": "1", "component": "body", "sourceType": "contact_field", "sourceKey": "name", "fallback": "cliente" },
        { "key": "2", "component": "body", "sourceType": "static", "value": "15%" }
      ]
    },
    "sendConfig": { "profile": "conservative" }
  }'

Resposta

Retorna HTTP 201 com o disparo em status: draft. O objeto devolvido é o mesmo descrito em Listar disparos.

Erros

Código	Status	Descrição
`VALIDATION_ERROR`	`400`	Corpo inválido. `details[]` aponta o campo
`INVALID_WHATSAPP_INSTANCE`	`400`	Um ou mais números não pertencem à organização
`UNSUPPORTED_PROFILE`	`400`	O perfil `custom` não é aceito na API pública
`MIXED_PROVIDERS`	`422`	Números por QR Code e do WhatsApp Oficial no mesmo disparo
`MISSING_CLOUD_TEMPLATE`	`422`	Disparo pelo WhatsApp Oficial sem modelo aprovado
`TEMPLATE_ON_QRCODE_BROADCAST`	`422`	Modelo informado num disparo por QR Code
`TEMPLATE_NOT_FOUND`	`422`	O modelo não existe nesta organização
`MISSING_AUTHOR`	`422`	A API Key não tem usuário criador associado

Contatos

Empresas

Negócios

Funis de venda

Conversas

Mensagens

Tarefas

Campos personalizados

Agentes de IA

Disparos

Créditos de mensagem

Lookup

Endpoint

Corpo da requisição

Objeto `audience`

`audience.rules`

`audience.filters` (formato anterior)

`audience.filters.dealFilter`

`audience.exclusions`

Objeto `message`

Objeto `sendConfig`

Objeto `cloudTemplate`

Objeto `variables[]`

Exemplo — disparo por QR Code, segmentado por tag

Exemplo — disparo pelo WhatsApp Oficial com modelo

Resposta

Erros

​Endpoint

​Corpo da requisição

​Objeto audience

​audience.rules

​audience.filters (formato anterior)

​audience.filters.dealFilter

​audience.exclusions

​Objeto message

​Objeto sendConfig

​Objeto cloudTemplate

​Objeto variables[]

​Exemplo — disparo por QR Code, segmentado por tag

​Exemplo — disparo pelo WhatsApp Oficial com modelo

​Resposta

​Erros

Endpoint

Corpo da requisição

Objeto `audience`

`audience.rules`

`audience.filters` (formato anterior)

`audience.filters.dealFilter`

`audience.exclusions`

Objeto `message`

Objeto `sendConfig`

Objeto `cloudTemplate`

Objeto `variables[]`

Exemplo — disparo por QR Code, segmentado por tag

Exemplo — disparo pelo WhatsApp Oficial com modelo

Resposta

Erros