API de Transmissões #

Uma transmissão é um envio de saída: um público, uma mensagem de abertura, um canal e um agendamento. Opcionalmente, ela também nomeia o Agente de IA que lida com as respostas recebidas. A API de Transmissões permite que você crie, precifique, lance e monitore esses envios a partir do seu próprio código, em vez do painel. Para o produto em si, consulte o guia de Transmissões.

• URL Base — https://api.youraiconnector.com/v1
• Autenticação — sua chave de API (veja Autenticação)
• Erros e paginação — veja Erros e Paginação

Todos os exemplos abaixo mostram a forma de consulta ?apiKey= em cURL e o cabeçalho X-API-Key em JavaScript e Python — ambos funcionam em todos os endpoints.

No explorador de API. Cada endpoint nesta página está na especificação OpenAPI publicada, para que você possa navegar pelos seus campos exatos e executar solicitações ao vivo no explorador de API.

Como um envio é montado #

Enviar uma transmissão requer quatro chamadas, não uma:

1. Crie a transmissão com seu público, canal e agendamento — ela começa como um Draft.
2. Defina a mensagem de abertura. No WhatsApp Business, isso significa enviar um modelo para aprovação (ou escolher um que você já tenha aprovado). Em qualquer outro canal, é texto simples.
3. Estime o custo se você quiser verificar o preço antes de gastar qualquer coisa (opcional).
4. Lance a transmissão. O lançamento executa uma verificação completa — público, mensagem, aprovação de modelo, remetente conectado — e inicia o envio ou informa exatamente o que está faltando.

Nada é enviado até que você chame o lançamento.

O objeto de transmissão #

{
  "id": "bcd123abc456",
  "name": "June promo",
  "status": "Draft",
  "channel": "whatsapp",
  "agent_id": "agt_789",
  "list_id": "lst_456",
  "list_name": "Newsletter subscribers",
  "total_contacts": 240,
  "send_to_new_list_members": false,
  "whats_app_template": {
    "body": "Hi {{first_name}}, our June offer is live.",
    "status": "approved",
    "sid": "HX0123...",
    "language": "en",
    "category": "marketing",
    "variables": ["first_name"]
  },
  "execution_date": 1781000000000,
  "drip_mode": true,
  "time_critical": false,
  "total_contacts_sent": 0,
  "credits_used": 0,
  "created_at": 1780900000000,
  "last_modified_at": 1780900000000
}

Os carimbos de data/hora retornam como milissegundos da época (execution_date, created_at, last_modified_at, …), e qualquer referência de contato retorna como uma string de caminho como contacts/uid_whatsapp_15551234567.

Campos que você define #

Qualquer coisa que você enviar como user_id, id, status ou source_campaign_id é ignorada na criação e descartada na atualização — o status só muda através dos endpoints de lançamento, pausa e retomada abaixo.

Campos que a plataforma mantém #

status, total_contacts_sent, unique_contacts_replied, overall_reply_rate, credits_used, paused_reason, completion_summary, os contadores de lote e contacts (os contatos individuais anexados a partir do painel, lidos de volta como strings de caminho). Leia-os, não os escreva.

Status #

Criar uma transmissão #

POST /broadcasts — cria uma Draft.

cURL

curl -X POST "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "June promo",
    "channel": "whatsapp",
    "list_id": "lst_456",
    "agent_id": "agt_789",
    "drip_mode": true,
    "execution_date": "2026-06-15T09:00:00.000Z"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "June promo",
    channel: "whatsapp",
    list_id: "lst_456",
    agent_id: "agt_789",
    drip_mode: true,
    execution_date: "2026-06-15T09:00:00.000Z",
  }),
});
const { broadcast_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "June promo",
        "channel": "whatsapp",
        "list_id": "lst_456",
        "agent_id": "agt_789",
        "drip_mode": True,
        "execution_date": "2026-06-15T09:00:00.000Z",
    },
)
print(res.json()["broadcast_id"])

Resposta (201)

{ "success": true, "broadcast_id": "bcd123abc456" }

Listar transmissões #

GET /broadcasts — todas as transmissões na conta, da mais recente para a mais antiga.

Parâmetros de consulta

curl "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY&status=Sending"

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts?status=Sending", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { broadcasts } = await res.json();

res = requests.get(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"status": "Sending"},
)
broadcasts = res.json()["broadcasts"]

Resposta (200)

{ "success": true, "broadcasts": [{ "id": "bcd123abc456", "name": "June promo", "status": "Sending", "...": "..." }] }

Obter uma transmissão #

GET /broadcasts/{broadcastId} — retorna { "success": true, "broadcast": { ... } }. Use-o para verificar um envio em andamento: total_contacts_sent, unique_contacts_replied, overall_reply_rate e credits_used são atualizados conforme o processo ocorre.

curl "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY"

Uma transmissão que não existe em sua conta retorna 404.

Listar os destinatários de uma transmissão #

GET /broadcasts/{broadcastId}/recipients retorna todos os contatos no público da transmissão com informações sobre até onde a mensagem de abertura chegou, por que falhou e se o contato respondeu. Falhas que o provedor relata após o envio (por exemplo, um número que não pode receber mensagens do WhatsApp, código 63024) estão incluídas.

curl "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/recipients?status=failed&apiKey=YOUR_API_KEY"

{
  "success": true,
  "data": {
    "recipients": [
      {
        "contact_id": "ct_9f2",
        "name": "Anna Virtanen",
        "phone_number": "+358401234567",
        "identifier": "+358401234567",
        "status": "failed",
        "error_code": 63024,
        "failure_reason": "This number cannot receive WhatsApp messages. It may not be on WhatsApp, or the person has not accepted WhatsApp's latest terms",
        "replied": false,
        "sent_at": "2026-09-02T14:15:26.529Z"
      }
    ],
    "counts": { "all": 61, "sent": 0, "delivered": 9, "read": 47, "failed": 5, "pending": 0, "replied": 16 },
    "total": 5,
    "limit": 50,
    "offset": 0,
    "truncated": false
  }
}

status é pending até que a mensagem de abertura tenha sido enviada para esse contato. counts fornece o total para cada filtro, portanto, uma chamada é suficiente para rotular as guias de filtro. Um membro da equipe que esteja configurado para ocultar detalhes de contato terá os números de telefone mascarados.

Atualizar uma transmissão #

PUT /broadcasts/{broadcastId} — envie apenas os campos que deseja alterar. Você também pode endereçar uma única chave dentro de um objeto aninhado com um caminho pontilhado, ex.: "whats_app_template.body".

curl -X PUT "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "June promo (v2)", "execution_date": "2026-06-16T09:00:00.000Z" }'

await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ name: "June promo (v2)", execution_date: "2026-06-16T09:00:00.000Z" }),
});

Um corpo vazio retorna 400. Duas regras importantes:

• opener_media é tudo ou nada. Envie o objeto completo ou null para remover o anexo. Um caminho pontilhado dentro dele (opener_media.name) é rejeitado com 400, porque um anexo parcialmente atualizado descreveria um arquivo que não existe.
• O status não é editável. Use lançar, pausar e retomar.

A mensagem de abertura #

Cada transmissão carrega seu conteúdo inicial em whats_app_template. O que isso significa depende do canal:

• WhatsApp Business — deve ser um modelo aprovado pelo WhatsApp. Use um dos dois endpoints abaixo.
• Qualquer outro canal (WhatsApp Web, SMS, Instagram, Messenger, Telegram, …) — o body do mesmo campo é simplesmente o texto que será enviado. Enviá-lo através do endpoint abaixo o armazena e o marca como pronto, sem envolver o WhatsApp.

Enviar um modelo para aprovação #

POST /broadcasts/{broadcastId}/template

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, our June offer is live until Friday.",
    "language": "en",
    "category": "marketing"
  }'

Resposta (200)

{ "success": true, "broadcast_id": "bcd123abc456", "template_status": "pending", "template_sid": "HX0123..." }

template_status é o que o WhatsApp informa: pending enquanto está sendo analisado, approved quando está utilizável, rejected se foi recusado. Em um canal que não seja WhatsApp, ele retorna diretamente como approved com template_sid: null — nada a analisar.

Coisas que impedirão você:

• Enviar enquanto um modelo anterior ainda está em análise retorna 400. Aguarde a decisão primeiro.
• Editar um modelo que já está aprovado mantém o aprovado ativo até que o novo retorne, para que uma transmissão em andamento nunca perca seu conteúdo inicial.
• Em um número de WhatsApp conectado diretamente via Meta, uma transmissão com imagem ou vídeo anexado não pode ser enviada (400) — anexos são suportados na via gerenciada do WhatsApp Business e no WhatsApp Web.

Usar um modelo que você já teve aprovado #

POST /broadcasts/{broadcastId}/template/select — copia um modelo já aprovado da sua biblioteca de modelos para a transmissão, portanto, não há nada pelo que esperar.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template/select?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "tpl_abc123" }'

Resposta (200)

{
  "success": true,
  "broadcast_id": "bcd123abc456",
  "template_status": "approved",
  "template_sid": "HX0123...",
  "body": "Hi {{first_name}}, our June offer is live until Friday.",
  "name": "june_promo",
  "language": "en",
  "variables": ["first_name"],
  "category": "marketing"
}

A aprovação é verificada do nosso lado a partir do registro da biblioteca — você sempre envia apenas o id. Você recebe um 400 se a transmissão não for um rascunho do WhatsApp, se o modelo não estiver aprovado, se for um modelo de acompanhamento em vez de um inicial, ou se a transmissão tiver um anexo (modelos da biblioteca são apenas texto). Um id de modelo que não está em sua conta retorna 404.

Estimar o custo #

POST /broadcasts/{broadcastId}/estimate-cost — precifica o envio antes de você se comprometer com ele. Disponível em transmissões whatsapp e sms; qualquer outro canal retorna 400. A transmissão precisa de um list_id, já que a estimativa conta o público.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/estimate-cost?apiKey=YOUR_API_KEY"

Resposta do WhatsApp (200) — créditos, detalhados por país de destino:

{
  "success": true,
  "channel": "whatsapp",
  "billing_mode": "credits",
  "data": {
    "countries": [
      { "countryCode": "31", "name": "Netherlands", "iso": "NL", "flag": "🇳🇱", "contactCount": 180, "costPerContact": 1.2, "subtotal": 216 },
      { "countryCode": "1", "name": "United States", "iso": "US", "flag": "🇺🇸", "contactCount": 60, "costPerContact": 0.9, "subtotal": 54 }
    ],
    "totalContacts": 240,
    "totalTemplateCost": 270,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}

Resposta por SMS (200) — Dólares americanos, com base nos preços em tempo real da Twilio para sua própria conta Twilio:

{
  "success": true,
  "channel": "sms",
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 240,
    "messageLength": 118,
    "segmentsPerMessage": 1,
    "totalSegments": 240,
    "estimatedCostUsd": 1.788,
    "priceUnit": "USD",
    "billedByTwilio": true,
    "billing_mode": "twilio_direct",
    "service_messages_billable_soon": false
  }
}

Leia billing_mode antes de exibir um número. Ele informa quem está sendo cobrado:

SMS sem credenciais da Twilio conectadas ainda retorna as contagens de segmento, com estimatedCostUsd: 0 — não há preços para consultar.

Iniciar uma transmissão #

POST /broadcasts/{broadcastId}/launch

O início verifica tudo primeiro e só então prossegue com a transmissão. Não existe início parcial: ou ela começa, ou nada muda e você recebe uma mensagem de erro explicando o motivo.

cURL

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
if (!data.success) console.error(data.error);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json())

Resposta (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Scheduled" }

status é onde a transmissão foi parar:

• Scheduled — execution_date está no futuro.
• Sending — começou agora.
• Pending Approval — o modelo do WhatsApp ainda está em análise. Ele será enviado assim que o modelo for aprovado; não chame o início novamente.

Apenas uma Draft (ou uma transmissão Pending Approval cujo modelo tenha sido aprovado desde então) pode ser iniciada — qualquer outra coisa retorna 400.

Por que um início é recusado #

Cada um desses retorna como 400 com uma mensagem error em linguagem simples:

Pausar e retomar #

POST /broadcasts/{broadcastId}/pause interrompe uma transmissão Sending ou Scheduled e cancela tudo o que estiver na fila.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/pause?apiKey=YOUR_API_KEY"

Pausar uma transmissão Pending Approval a coloca de volta em Draft — nada foi agendado ainda, então não há nada para retomar. Qualquer outro status retorna 400.

POST /broadcasts/{broadcastId}/resume reinicia uma transmissão Paused:

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/resume?apiKey=YOUR_API_KEY"

Resposta (200)

{ "success": true, "broadcast_id": "bcd123abc456" }

Ela retoma em Sending, ou volta para Scheduled se o seu execution_date ainda estiver no futuro. Apenas uma transmissão Paused pode ser retomada.

Continuar enviando após uma pausa por baixo engajamento #

POST /broadcasts/{broadcastId}/override-engagement-guard

Enquanto uma transmissão é enviada em lotes, medimos quantas pessoas responderam a cada lote antes de iniciar o próximo. Se quase ninguém estiver respondendo, a transmissão pausa automaticamente — um envio que continua insistindo no silêncio é a maneira mais rápida de ter um número filtrado ou bloqueado. É o botão Continuar mesmo assim no painel.

Como a taxa de resposta que causou a pausa não pode mudar enquanto a transmissão está parada, um resume simples seria pausado novamente pela próxima verificação. Este endpoint é a decisão de continuar mesmo assim: ele registra a substituição nessa transmissão específica e remove a pausa na mesma chamada, caso a transmissão tenha sido pausada por baixo engajamento.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/override-engagement-guard?apiKey=YOUR_API_KEY"

Resposta (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Sending", "resumed": true }

• resumed: true — a transmissão foi pausada por baixo engajamento e agora está rodando novamente; status é onde ela foi retomada.
• resumed: false — nada foi removido, a substituição é simplesmente registrada para verificações futuras. Isso é o que você recebe se a transmissão nunca foi pausada ou foi pausada por um motivo diferente (você a pausou manualmente, um limite de envio foi atingido ou muitos envios apresentaram erro). Essas pausas não são removidas aqui — retome-a você mesmo depois de ter resolvido a causa.

A substituição se aplica apenas a esta transmissão. Não é uma configuração de conta e é seguro chamar duas vezes.

Duplicar uma transmissão #

POST /broadcasts/{broadcastId}/duplicate — copia o público, a mensagem e as configurações para uma nova Draft. Tudo sobre a execução anterior (contadores, lotes, agendamento, estatísticas de resposta) começa do zero.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/duplicate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to_channel": "sms" }'

Resposta (201)

{ "success": true, "broadcast_id": "bcd999new111", "source_broadcast_id": "bcd123abc456" }

Uma cópia nunca herda uma aprovação ativa do WhatsApp: em uma cópia do WhatsApp, o modelo vem precisando da sua confirmação e, em uma cópia para outro canal, ele é descartado e o texto se torna o abridor simples. Copiar para SMS também descarta qualquer anexo, já que SMS não pode enviar um.

Excluir uma transmissão #

DELETE /broadcasts/{broadcastId}

curl -X DELETE "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY"

Uma Sending ou Scheduled transmissão é recusada com 400 — pause-a primeiro.

Transmissões que espelham uma campanha clássica #

Campanhas clássicas que enviam mensagens também aparecem em Transmissões, e a API as retorna junto com as transmissões nativas (elas carregam um source_campaign_id). Elas se comportam de maneira um pouco diferente, porque a campanha permanece no controle:

• Editar o público, a mensagem ou o agendamento funciona e é aplicado diretamente à campanha.
• Canal, agente de resposta, anexo e todos os contadores de execução são somente leitura aqui — 400 se você tentar alterá-los. Altere-os na campanha.
• Lançar retorna 400 direcionando você para o editor da campanha.
• Pausar e retomar funcionam e agem sobre a campanha.
• Excluir retorna 400 — exclua a campanha em vez disso, e sua entrada em Transmissões será removida com ela.
• Duplicar fornece uma transmissão nativa independente, que é a maneira suportada de mover uma campanha comprovada.

Erros #

Solicitações com falha retornam {"success": false, "error": "<message>"} com estes status:

Próximos passos #

• Guia de Transmissões — o produto por trás desses endpoints, incluindo ritmo e comportamento de segurança
• API de Contatos — crie a lista para a qual uma transmissão envia
• API de Modelos — gerencie os modelos aprovados do WhatsApp que você pode selecionar
• API de Webhooks — inscreva-se em Broadcast Started e Broadcast Completed em vez de fazer polling