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, também nomeia o Agente de IA que lida com as respostas recebidas. A API de Transmissões permite-lhe criar, definir preços, lançar e monitorizar esses envios a partir do seu próprio código em vez do painel de controlo. Para o produto em si, consulte o guia de Transmissões.

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

Todos os exemplos abaixo mostram o formato de consulta ?apiKey= em cURL e o cabeçalho X-API-Key em JavaScript e Python — qualquer um funciona em todos os endpoints.

No explorador da API. Todos os endpoints nesta página estão na especificação OpenAPI publicada, pelo que pode consultar os seus campos exatos e executar pedidos em tempo real no explorador da API.

Como um envio é estruturado #

O envio de uma transmissão requer quatro chamadas, não apenas uma:

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

Nada é enviado até que 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 são devolvidos como milissegundos da época (execution_date, created_at, last_modified_at, …), e qualquer referência de contacto é devolvida como uma string de caminho como contacts/uid_whatsapp_15551234567.

Campos que define #

Qualquer coisa que envie como user_id, id, status ou source_campaign_id é ignorada na criação e descartada na atualização — o estado apenas muda através dos endpoints de lançamento, pausa e retoma 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 contactos individuais anexados a partir do painel de controlo, lidos como strings de caminho). Leia-os, não os escreva.

Estados #

Criar uma difusã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 difusões #

GET /broadcasts — todas as difusõ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 difusão #

GET /broadcasts/{broadcastId} — devolve { "success": true, "broadcast": { ... } }. Utilize-o para consultar um envio em curso: total_contacts_sent, unique_contacts_replied, overall_reply_rate e credits_used são atualizados à medida que o processo decorre.

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

Uma difusão que não existe na sua conta devolve 404.

Listar os destinatários de uma transmissão #

GET /broadcasts/{broadcastId}/recipients devolve todos os contactos na audiência da transmissão com o estado de entrega da mensagem inicial, o motivo da falha e se o contacto respondeu. As falhas comunicadas pelo fornecedor após o envio (por exemplo, um número que não pode receber mensagens 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 inicial tenha sido enviada para esse contacto. counts fornece o total para cada filtro, pelo que uma chamada é suficiente para identificar os separadores de filtro. Um membro da equipa que esteja configurado para ocultar detalhes de contacto verá os números de telefone mascarados.

Atualizar uma difusão #

PUT /broadcasts/{broadcastId} — envie apenas os campos que pretende alterar. Também pode endereçar uma única chave dentro de um objeto aninhado com um caminho pontuado, p. 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 devolve 400. Duas regras que vale a pena conhecer:

• opener_media é tudo ou nada. Envie o objeto completo, ou null para remover o anexo. Um caminho pontuado para o mesmo (opener_media.name) é rejeitado com 400, porque um anexo parcialmente atualizado descreveria um ficheiro que não existe.
• O estado não é editável. Utilize lançar, pausar e retomar.

A mensagem de abertura #

Cada difusão contém o seu elemento de abertura em whats_app_template. O que isso significa depende do canal:

• WhatsApp Business — tem de ser um modelo aprovado pelo WhatsApp. Utilize um dos dois endpoints abaixo.
• Todos os outros canais (WhatsApp Web, SMS, Instagram, Messenger, Telegram, …) — o body do mesmo campo é simplesmente o texto que é enviado. Submetê-lo através do endpoint abaixo armazena-o e marca-o como pronto sem envolver o WhatsApp.

Submeter 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 indica: pending enquanto está a ser revisto, approved quando está pronto a utilizar, rejected se foi recusado. Num canal que não seja WhatsApp, a resposta é diretamente approved com template_sid: null — não há nada para rever.

Coisas que o impedirão:

• Submeter enquanto um modelo anterior ainda está sob revisão devolve 400. Aguarde primeiro pela decisão.
• Editar um modelo que está atualmente aprovado mantém o aprovado ativo até que o novo seja processado, para que uma difusão em curso nunca perca o seu elemento de abertura.
• Num número WhatsApp ligado diretamente através da Meta, uma difusão com uma imagem ou vídeo anexado não pode ser submetida (400) — os anexos são suportados na via gerida do WhatsApp Business e no WhatsApp Web.

Utilizar um modelo que já foi aprovado #

POST /broadcasts/{broadcastId}/template/select — copia um modelo já aprovado da sua biblioteca de modelos para a difusão, pelo que não há nada por 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 registo da biblioteca — envia apenas o id. Recebe um 400 se a difusão não for um rascunho do WhatsApp, se o modelo não estiver aprovado, se for um modelo de seguimento em vez de um de abertura, ou se a difusão tiver um anexo (os modelos da biblioteca são apenas de texto). Um id de modelo que não esteja na sua conta devolve 404.

Estimar o custo #

POST /broadcasts/{broadcastId}/estimate-cost — calcula o preço do envio antes de o confirmar. Disponível em difusões whatsapp e sms; qualquer outro canal devolve 400. A difusão necessita de um list_id, uma vez que a estimativa contabiliza a audiência.

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

Resposta do WhatsApp (200) — créditos, discriminados 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 a 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 mostrar um número. Indica-lhe quem está a ser cobrado:

O SMS sem credenciais Twilio ligadas continua a devolver as contagens de segmentos, com estimatedCostUsd: 0 — não existem preços a consultar.

Iniciar uma difusão #

POST /broadcasts/{broadcastId}/launch

O início verifica tudo primeiro e só depois avança com a difusão. Não existe início parcial: ou começa, ou nada muda e recebe um erro a explicar 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 entregue:

• Scheduled — execution_date está no futuro.
• Sending — começou agora.
• Pending Approval — o modelo do WhatsApp ainda está sob análise. Será enviado automaticamente assim que o modelo for aprovado; não chame o lançamento novamente.

Apenas uma transmissão Draft (ou uma Pending Approval cujo modelo tenha sido aprovado entretanto) pode ser lançada — qualquer outra coisa devolve 400.

Por que um lançamento é recusado #

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

Pausar e retomar #

POST /broadcasts/{broadcastId}/pause para 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 coloca-a de volta em Draft — nada estava agendado, por isso não há nada para retomar. Qualquer outro estado devolve 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" }

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 o envio após uma pausa por baixo envolvimento #

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

Enquanto uma transmissão é enviada em lotes, medimos quantas pessoas responderam a cada lote antes de iniciar o seguinte. Se quase ninguém responder, a transmissão pausa-se automaticamente — um envio que continua a insistir no silêncio é a forma mais rápida de um número ser filtrado ou bloqueado. É o botão Continuar mesmo assim no painel de controlo.

Como a taxa de resposta que causou a pausa não pode mudar enquanto a transmissão está parada, um resume simples seria apenas pausado novamente pela verificação seguinte. Este endpoint representa a decisão de continuar mesmo assim: regista a anulação nessa transmissão específica e levanta a pausa na mesma chamada, caso a transmissão tenha sido pausada por baixo envolvimento.

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 envolvimento e está agora a decorrer novamente; status é o estado para onde foi retomada.
• resumed: false — nada foi levantado, a anulação é simplesmente registada para verificações futuras. É isto que obtém se a transmissão nunca tiver sido pausada, ou se tiver sido pausada por um motivo diferente (pausou-a manualmente, atingiu um limite de envio ou demasiados envios deram erro). Essas pausas não são levantadas aqui — retome-a manualmente depois de resolver a causa.

A anulação aplica-se apenas a esta transmissão. Não é uma definição da conta e é seguro chamar duas vezes.

Duplicar uma transmissão #

POST /broadcasts/{broadcastId}/duplicate — copia o público, a mensagem e as definições para uma nova Draft. Tudo o que diz respeito à 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: numa cópia do WhatsApp, o modelo é transferido a necessitar da sua confirmação e, numa cópia para outro canal, é removido e o texto torna-se o conteúdo simples. Copiar para SMS também remove qualquer anexo, uma vez que o SMS não permite o envio de anexos.

Eliminar uma transmissão #

DELETE /broadcasts/{broadcastId}

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

Uma difusão Sending ou Scheduled é recusada com 400 — coloque-a primeiro em pausa.

Difusões que espelham uma campanha clássica #

As campanhas clássicas que enviam mensagens também aparecem nas Difusões, e a API devolve-as juntamente com as difusões nativas (possuem um source_campaign_id). Comportam-se de forma ligeiramente diferente, porque a campanha continua a estar no comando:

• Editar o público-alvo, a mensagem ou o agendamento funciona e é aplicado na campanha.
• O canal, o agente de resposta, o anexo e todos os contadores de execução são apenas de leitura aqui — 400 se tentar alterá-los. Altere-os na campanha.
• Iniciar devolve 400, direcionando-o para o editor da campanha.
• Pausar e retomar funcionam e atuam sobre a campanha.
• Eliminar devolve 400 — elimine a campanha em vez disso, e a sua entrada nas Difusões será removida com ela.
• Duplicar cria uma difusão nativa independente, que é a forma suportada de migrar uma campanha comprovada.

Erros #

Os pedidos falhados devolvem {"success": false, "error": "<message>"} com estes estados:

Próximos passos #

• Guia de Difusões — o produto por detrás destes endpoints, incluindo o ritmo e o comportamento de segurança
• API de Contactos — crie a lista para a qual uma difusão é enviada
• API de Modelos — gira os modelos WhatsApp aprovados que pode selecionar
• API de Webhooks — subscreva Broadcast Started e Broadcast Completed em vez de consultar