Pular para o conteúdo
Atalho: /, ⌘K ou Ctrl+K

Envie uma campanha

Crie uma campanha com destinatários, lance-a, acompanhe cada destinatário e interrompa-a, do início ao fim pela API.

Ver em Markdown

Uma campanha transforma uma lista de números em mensagens do WhatsApp enviadas em ritmo controlado e com verificações de segurança, a partir dos números de um projeto. Este guia percorre todo o caminho pela API: construir (build) a lista de destinatários, lançar, acompanhar o envio e interromper.

As campanhas são o único caminho de envio em massa na Polymorfa. Cada envio passa pelas verificações de plano, vazão, opt-out, contato e aquecimento descritas em Campanhas e segurança dos números. Para comparar de duas a quatro mensagens com parte do público antes de enviar a melhor para o restante do público, consulte Faça um teste A/B de uma campanha.

Escolha uma superfície#

Dois caminhos públicos chegam ao mesmo mecanismo de campanhas, com as mesmas verificações, os mesmos erros e os mesmos resultados.

SuperfícieCaminhoCredencial
Messaging API/messaging/projects/{projectSlug}/campaignsCredencial do projeto
Platform API/platform/campaignsChave de API da equipe com projectId, ou um token de projeto para o próprio projeto

A leitura exige campaigns:read. Criar, lançar, reagendar, pausar, retomar, interromper e excluir exigem campaigns:manage. Os exemplos abaixo usam a Messaging API; a Platform API recebe o ID da campanha no caminho. Na Platform API, uma chave de API da equipe indica o projeto com projectId em toda requisição de campanha, e um token de projeto fica vinculado ao próprio projeto e omite esse campo.

TypeScript:

No SDK TypeScript, messaging.campaigns chama a Messaging API pelo slug do projeto, e platform.campaigns chama a Platform API. Uma campanha envia por números cujo plano inclui Campanhas; quando nenhum dos números elegíveis se qualifica, a criação e o lançamento falham com 402 campaigns_not_entitled.

A Graph API não tem métodos de campanha. Ela envia um modelo de marketing por vez de um número da Meta Cloud API:

Graph API
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/$PHONE_NUMBER_ID/marketing_messages" \
  -H "Authorization: Bearer $POLYMORFA_PROJECT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "15551234567",
    "type": "template",
    "template": {
      "name": "spring_sale",
      "language": { "policy": "deterministic", "code": "en_US" }
    },
    "product_policy": "STRICT"
  }'

Crie a campanha com os destinatários#

Console

No builder de campanhas, escolha um público, importe um CSV ou cole números de telefone. O resumo da importação mostra os destinatários mantidos, os duplicados e as linhas inválidas. Para números colados, o resumo continua visível depois da importação, para que você corrija os números de origem antes de continuar.

Selecione os números que vão enviar a campanha. Números Free e Standard aparecem desativados na seleção, com uma ação de upgrade, e você pode salvar o rascunho antes de fazer o upgrade. Cada número mostra o tipo de envio. Depois que você seleciona um, os números de outro tipo de envio ficam desativados, porque uma campanha envia por um único tipo. Em Intervalo entre mensagens, escolha uma predefinição de Rápido (de 1,8 a 5 segundos entre mensagens) a Muito lento (de 2 a 5 minutos), ou escolha Personalizado para definir você mesmo a taxa e o atraso aleatório. A tabela de predefinições de intervalo lista os valores da API por trás de cada predefinição. Aguarde Rascunho salvo antes de lançar. Se o salvamento falhar, o builder mostra o motivo e marca as alterações como não salvas. Uma restrição de envio também aparece na etapa de revisão; resolva-a antes de lançar. Se o primeiro salvamento não tiver uma resposta clara, o rascunho ainda pode ter sido criado. Use Procurar rascunho salvo antes de escolher Criar outro rascunho, que pode gerar uma duplicata.

A etapa de revisão verifica de novo o público selecionado. Se a contagem de destinatários mudou desde que o rascunho foi salvo, revise a nova contagem e confirme-a antes de lançar. O builder verifica mais uma vez quando você lança; se a contagem mudar durante a revisão, ele para e pede que você confirme o público atualizado.

Escreva na mensagem qualquer instrução de opt-out. O builder não acrescenta um rodapé nem envia um pedido de consentimento separado. Revise as configurações de palavras-chave da sua equipe antes de enviar.

O agendamento usa o fuso horário local do seu navegador. Confira o fuso ao lado da data e da hora e de novo na etapa de revisão antes de agendar.

Para enviar apenas em horários definidos, ative Enviar apenas nos horários definidos na etapa de agendamento. A opção começa com segunda a sexta, das 09:00 às 18:00, no fuso horário do seu navegador. A etapa de revisão e a página da campanha mostram a janela. Consulte Escolha quando a campanha envia.

Adicione botões#

Na etapa de composição, escolha Adicionar botão. Cada mensagem aceita até 10 botões em dispositivos vinculados, incluindo no máximo 3 links ou chamadas. Selecione o botão para editar seu tipo e rótulo.

Cada resposta tem um ID, retornado quando o destinatário a seleciona. O Console gera esse ID; você pode substituí-lo por um valor como offer-interested. Editar o rótulo preserva o ID. Rótulos aceitam de 1 a 256 bytes UTF-8 em dispositivos vinculados e de 1 a 20 caracteres na API Oficial. IDs aceitam de 1 a 256 bytes UTF-8, devem ser únicos na mensagem e não podem conter caracteres de controle.

Anexos enviados pelo Console ainda não podem ser usados como cabeçalhos de mídia de campanhas. Para cabeçalhos de imagem, vídeo ou documento em dispositivos vinculados, use a API com um media.url HTTPS público. Áudio não pode ser combinado com botões. Números da API Oficial aceitam até 3 respostas; links, chamadas e cabeçalhos de mídia precisam de um modelo aprovado. Faça um envio de teste antes do lançamento.

API

Envie os destinatários na requisição, aponte para um público com recipientListId ou faça as duas coisas.

cURL
curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: september-launch-1" \
  -d '{
    "name": "September launch",
    "templateId": "'"$TEMPLATE_ID"'",
    "recipients": [
      { "phone": "+14155550100", "variables": { "first_name": "Ada" } },
      { "phone": "+442071838750", "variables": { "first_name": "Alan" } }
    ],
    "senderConfig": {
      "sessionIds": ["'"$SESSION_ID"'"],
      "throughput": { "ratePerMinute": 20, "perNumberDailyCap": 500 }
    }
  }'
TypeScript
const created = await messaging.campaigns.create(
  "<project-slug>",
  {
    name: "September launch",
    templateId: "<template-id>",
    recipients: [
      { phone: "+14155550100", variables: { first_name: "Ada" } },
      { phone: "+442071838750", variables: { first_name: "Alan" } },
    ],
    senderConfig: {
      sessionIds: ["<number-id>"],
      throughput: { ratePerMinute: 20, perNumberDailyCap: 500 },
    },
  },
  { idempotencyKey: "september-launch-1" },
);
const campaignId = created.data.data.id;

TypeScript:

A campanha começa como rascunho. Passe os destinatários em recipients, um público em recipientListId, ou os dois.

O campo recipients aceita no máximo 1.000 entradas e funciona no modo tudo ou nada: uma entrada inválida faz a requisição ser recusada e é identificada, para que uma campanha nunca seja criada sem alguém por omissão silenciosa. Um número repetido na requisição é mantido uma vez. Valem as mesmas regras de número e de variável dos membros de público.

senderConfig.sessionIds fixa os números que enviam a campanha. Um rascunho pode fixar números de qualquer plano. Quando você lança, todo número fixado precisa estar conectado e em um plano que inclua Campanhas. Uma campanha que não fixa nenhum número usa os números conectados e sem restrições do projeto cujos planos incluem Campanhas, com um único tipo de envio: números do WhatsApp quando houver algum pronto, senão números da Cloud API, senão números de teste. Para enviar de um conjunto específico, fixe esse conjunto.

Adicione mais destinatários enquanto a campanha ainda é um rascunho, 1.000 por requisição:

cURL
curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/recipients" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: september-launch-batch-2" \
  -d '{ "recipients": [{ "phone": "+14155550101", "variables": { "first_name": "Grace" } }] }'
TypeScript
const added = await messaging.campaigns.addRecipients("<project-slug>", campaignId, {
  recipients: [{ phone: "+14155550101", variables: { first_name: "Grace" } }],
});
console.log(added.data.data.added, added.data.data.duplicateCount, added.data.data.invalidRows);

TypeScript:

Cada chamada adiciona até 1.000 destinatários antes do lançamento. O SDK a envia uma vez e não tenta novamente. Se a resposta se perder, liste os destinatários antes de adicioná-los de novo.

O acréscimo informa added, recipientCount, duplicateCount, invalidCount e até 20 invalidRows, e ignora um número que já está na campanha. Depois que a campanha é lançada, o acréscimo retorna 409.

Envie um Idempotency-Key para que um acréscimo possa ser repetido com segurança após um timeout ou uma resposta perdida. Depois que um acréscimo dá certo, uma nova tentativa com a mesma chave e o mesmo corpo em até 24 horas não é aplicada de novo: ela retorna as contagens daquele acréscimo com Idempotent-Replayed: true, mesmo que a campanha tenha sido lançada nesse meio-tempo. Um acréscimo que falhou não deixa registro, então uma nova tentativa com a mesma chave o executa de novo. O acréscimo da Platform API aceita o mesmo cabeçalho.

Edite o rascunho#

Envie apenas os campos que você quer mudar. Na Messaging API, name, recipientListId, senderConfig, scheduledAt, sendWindow, templateId e variableMapping podem ser atualizados; qualquer outro campo é recusado com 400. templateId e variableMapping só mudam enquanto a campanha é um rascunho não lançado; depois do lançamento, um valor diferente retorna 409. Um scheduledAt não nulo precisa ser um inteiro em milissegundos Unix, de zero até o máximo de Date do JavaScript; um valor fora desse intervalo retorna 400.

cURL
curl -X PATCH "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "September launch (EU)", "senderConfig": { "sessionIds": ["'"$SESSION_ID"'"] } }'
TypeScript
await messaging.campaigns.update("<project-slug>", campaignId, {
  name: "September launch (EU)",
  senderConfig: { sessionIds: ["<number-id>"] },
});

TypeScript:

Altere um rascunho com messaging.campaigns.update(projectSlug, campaignId, body), ou com platform.campaigns.update no cliente da equipe, que indica o projeto nas opções da solicitação, como em platform.campaigns.update(campaignId, { sendWindow: null }, { projectId: "<project-id>" }).

A Platform API aceita as mesmas alterações em API Update campaign, além de messagesArray (consulte Envie várias mensagens). Depois do lançamento, um messagesArray diferente também retorna 409.

Para enviar a outro público, atualize o rascunho com outro recipientListId. Depois que a campanha é lançada, o público fica fixo e a atualização retorna 409. Mudar o público de um rascunho substitui os destinatários existentes; depois da mudança, adicione os destinatários individuais que você ainda quiser.

Um rascunho salva qualquer seleção de números, em qualquer plano; o lançamento a verifica. Depois do lançamento, um novo senderConfig precisa passar pelas verificações de lançamento e pode retornar 402 campaigns_not_entitled ou 400 invalid_parameter. Um scheduledAt diferente só é aceito antes do lançamento. Para mover um início agendado que ainda não começou, reagende-o.

Envie várias mensagens#

Uma campanha envia um modelo aprovado ou até 10 mensagens compostas, em ordem. Defina as mensagens compostas com messagesArray na requisição de criação ou atualização de campanha da Platform API. Cada mensagem tem um texto source e pode ter também media, buttons e um footer. delayAfterSec é a espera mínima, de 0 a 86.400 segundos, depois que a mensagem anterior foi aceita. Uma campanha com modelo envia apenas o modelo.

Um modelo precisa estar completo e, em números da Cloud API, aprovado para todos os números de envio. Números com dispositivos vinculados e números de teste o enviam como uma mensagem comum. Modelos de autenticação (código de uso único) não podem ser enviados por uma campanha; o lançamento retorna 400 invalid_parameter em templateId.

Shell
curl -X PATCH "https://api.polymorfa.com/platform/campaigns/$CAMPAIGN_ID?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messagesArray": [
      { "version": 2, "source": "Hi {{first_name | there}}, your order shipped." },
      { "version": 2, "source": "Track it here: https://example.com/t/{{order_id}}", "delayAfterSec": 120 }
    ],
    "templateId": null
  }'

"templateId": null faz um rascunho que tinha um modelo passar a usar as mensagens compostas; enquanto um modelo estiver definido, ele é a única mensagem enviada.

Anexe mídia com uma media.url https pública, que o número de envio baixa no momento do envio. O lançamento retorna 400 invalid_parameter, indicando a mensagem, quando um anexo não tem url.

{{name}} insere uma variável do destinatário; {{name | fallback}} usa o fallback quando a variável está ausente ou vazia. Uma mensagem sem texto, mídia, botão de link ou de chamada, rodapé ou formulário de fluxo não é enviada. Em números com dispositivos vinculados, respostas, links e chamadas são controles nativos com IDs de resposta estáveis. Uma mensagem aceita até 10 botões, dos quais até 3 podem ser links ou chamadas. Imagens, vídeos e documentos se tornam o cabeçalho da mensagem com botões. A API verifica os números de envio antes do lançamento ou envio de teste. Números da Meta Cloud API aceitam até 3 respostas; outros controles e cabeçalhos de mídia precisam de um modelo aprovado. Combinações inválidas são rejeitadas, sem dividir o conteúdo em mensagens extras. Use um envio de teste da campanha para conferir o resultado. O teste de texto legado de um modelo salvo no sandbox não verifica controles nativos nem mídia.

Toda mensagem passa pelas mesmas verificações da primeira: ritmo, limites por número, cota de aquecimento, indicador de digitação e histórico de contato do destinatário. Antes de cada mensagem, a Polymorfa verifica de novo a lista de opt-outs da equipe, então um destinatário que responde STOP não recebe mais nada. O ritmo, os limites e uma campanha pausada podem tornar uma espera mais longa que delayAfterSec, nunca mais curta. Cada mensagem seguinte é enviada pelo número que enviou a primeira. Se esse número não puder enviar, a mensagem aguarda até que ele possa.

Como os resultados de várias mensagens são contados#

status, sentAt, deliveredAt, readAt e externalMessageId do destinatário descrevem a primeira mensagem. sentCount, failedCount e skippedCount da campanha contam cada destinatário uma vez.

O que aconteceResultado
A primeira mensagem falha depois de todas as tentativasO destinatário fica failed e nenhuma mensagem seguinte é enviada
Uma mensagem seguinte é enviadamessagesSent aumenta e um evento campaign.recipient_sent com aquele messageIndex é enviado
Uma mensagem seguinte falha depois de todas as tentativasO destinatário continua sent. As mensagens restantes não são enviadas, sequenceError indica a classe da falha e campaign.recipient_failed traz o messageIndex
O destinatário faz opt-out entre as mensagensAs mensagens restantes não são enviadas e sequenceError é opted_out
A campanha é interrompida entre as mensagensAs mensagens restantes não são enviadas e sequenceError é campaign_cancelled
A campanha é pausada entre as mensagensA próxima mensagem aguarda até a campanha ser retomada

Uma mensagem seguinte que falha recebe novas tentativas conforme as configurações de novas tentativas da campanha, como uma primeira mensagem. As classes de falha conversation_window_closed, recipient_not_on_whatsapp e template_not_approved não recebem novas tentativas, porque outra tentativa falharia da mesma forma.

A campanha termina quando todos os destinatários foram resolvidos e nenhuma mensagem está aguardando. nextMessageAt em um destinatário mostra quando a próxima mensagem dele está prevista.

Para enviar mais uma mensagem apenas depois que a primeira foi entregue ou lida, e nunca a quem respondeu ou fez opt-out, adicione um acompanhamento. Uma campanha com acompanhamento envia uma única primeira mensagem.

Preencha as variáveis de modelo e de mensagem#

Cada {{variable}} é preenchida por destinatário. Defina variableMapping para indicar uma variável do destinatário e um fallback opcional:

cURL
curl -X PATCH "https://api.polymorfa.com/platform/campaigns/$CAMPAIGN_ID?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "'"$TEMPLATE_ID"'",
    "variableMapping": {
      "first_name": { "source": "FirstName", "fallback": "there" },
      "coupon": { "source": "Coupon" }
    }
  }'
TypeScript
await messaging.campaigns.update("<project-slug>", campaignId, {
  templateId: "<template-id>",
  variableMapping: {
    first_name: { source: "FirstName", fallback: "there" },
    coupon: { source: "Coupon" },
  },
});

A Messaging API aceita os mesmos templateId e variableMapping quando você cria uma campanha ou atualiza um rascunho.

Cada variável é preenchida nesta ordem:

  1. O valor do destinatário para source, ou para a variável de mesmo nome quando source é omitido. Um valor vazio ou só com espaços conta como nenhum valor.
  2. O fallback do mapeamento.
  3. Um fallback escrito em uma mensagem composta como {{first_name | there}}.

{{phone}} é preenchido com o número do destinatário, a menos que o destinatário tenha a própria variável phone não vazia, que é usada no lugar. Os valores de exemplo do modelo nunca são enviados aos destinatários.

Um mapeamento tem no máximo 50 variáveis. Os nomes usam letras, dígitos, _, . ou -, e um fallback tem de 1 a 1.024 caracteres. Um mapeamento inválido retorna 400 invalid_parameter, e error.param indica o campo. templateId e variableMapping só podem mudar enquanto a campanha é um rascunho não lançado; depois, um valor diferente retorna 409.

No Console, escolha Usar um modelo na etapa Mensagem, selecione o modelo e defina o campo do destinatário e o fallback de cada variável. A prévia mostra a mensagem que um destinatário recebe.

Varie a mensagem por peso#

Para não enviar o mesmo texto a todos os destinatários, dê a uma campanha de duas a cinco alternativas em messageVariations. Cada destinatário recebe uma alternativa, escolhida por peso, e a mantém se o envio for repetido. Ao contrário de um teste A/B, nada é comparado e nenhuma vencedora é escolhida.

A variação ponderada está em beta. Um proprietário ou administrador da equipe inscreve a equipe na página Campanhas do Console. Até que a equipe esteja inscrita e o beta seja oferecido a ela, definir messageVariations, lançar uma campanha que as tenha e retomar uma campanha assim retornam 403 feature_unavailable.

Shell
curl -X PATCH "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messageVariations": [
      { "key": "hello", "weight": 60, "blueprint": { "version": 2, "source": "Hello {{first_name | there}}, your order is ready." } },
      { "key": "hi", "weight": 40, "blueprint": { "version": 2, "source": "Hi {{first_name | there}}! Your order is ready to collect." } }
    ]
  }'
  • key é única na campanha: uma letra minúscula, seguida de até 15 letras minúsculas, dígitos, _ ou -. weight é um inteiro de 1 a 99, e os pesos somam 100. source tem de 1 a 4.096 caracteres.
  • Todas as alternativas precisam usar os mesmos marcadores {{variable}} e os mesmos fallbacks em linha, para que os mesmos destinatários se qualifiquem qualquer que seja a alternativa recebida.
  • Uma campanha com alternativas envia apenas as alternativas. Ela não pode ter também mensagens compostas, um modelo ou variantes A/B.
  • As alternativas são enviadas apenas de números do WhatsApp vinculados. Selecione-os com senderConfig.sessionIds. Uma campanha cujos números passam a ser números oficiais (Cloud API) é pausada antes do próximo envio.
  • As alternativas só mudam enquanto a campanha é um rascunho não lançado. Envie null para removê-las. Depois do lançamento, uma atualização retorna 409.
  • Envios de teste de um rascunho com alternativas retornam 409 state_conflict.

Se a equipe sair do beta, uma campanha em andamento com alternativas é pausada antes do próximo envio e ainda pode ser interrompida. Retomá-la exige o beta de novo.

Envie um teste#

Antes de lançar, envie uma cópia do conteúdo de um rascunho para o seu próprio telefone. Um teste passa pelas mesmas verificações de renderização, envio e segurança da campanha lançada, a partir do número que você escolher. Ele envia todas as mensagens do rascunho em ordem, sem os intervalos entre elas, e para na primeira mensagem que não for enviada. Ele renderiza o conteúdo com os valores de exemplo selecionados para o teste, então a mensagem de cada destinatário pode ser diferente onde os valores dele forem diferentes. A chave de API precisa de campaigns:manage e campaigns:read, porque o teste pode usar valores de exemplo armazenados dos destinatários.

  • Destinatário do teste. to precisa ser o telefone de um número conectado à sua equipe, em qualquer projeto. Vincule o seu próprio telefone a um projeto para receber testes nele. Um destinatário do teste que está na lista de opt-outs da equipe é recusado.
  • Número de envio. sessionId precisa estar conectado e em um plano que inclua Campanhas, o mesmo requisito do lançamento. Quando a campanha seleciona números com senderConfig.sessionIds, teste a partir de um deles.
  • Variáveis. Sem sampleRecipientId nem variables, o primeiro destinatário da campanha preenche as variáveis, ou o primeiro membro do público quando o rascunho não tem destinatários próprios. Indique um destinatário com sampleRecipientId e substitua valores específicos com variables. O teste aplica o mapeamento de variáveis e os fallbacks da campanha a todas as mensagens do rascunho.
  • Estatísticas. Um teste não é um destinatário da campanha. Ele não altera as contagens nem as análises da campanha e não envia webhooks de campanha.
  • Limites. Uma equipe pode enviar 20 testes por hora, e no máximo 5 por hora para um mesmo destinatário do teste.
Shell
curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/test-send" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: september-launch-test-1" \
  -d '{
    "sessionId": "'"$SESSION_ID"'",
    "to": "+14155550199",
    "variables": { "first_name": "Ada" }
  }'
JSON
{
  "success": true,
  "data": {
    "id": "01924f1e-7c3a-7b1d-9e2f-3a4b5c6d7e8f",
    "campaignId": "01924f1e-6a2b-7c3d-8e4f-5a6b7c8d9e0f",
    "status": "sent",
    "from": { "sessionId": "01924f1e-5b6c-7d8e-9f0a-1b2c3d4e5f6a", "phone": "+14155550123" },
    "to": "+14155550199",
    "messageId": "3EB0C767D26A1D2E5F7A",
    "variables": { "first_name": "Ada" },
    "createdAt": 1758326300000
  }
}

A resposta chega quando o envio termina. Um teste recusado não envia nada, a menos que a tabela diga o contrário:

Status e códigoCausaO que fazer
400 invalid_parameterto não é um número conectado à sua equipe, ou sessionId não é um número pelo qual esta campanha pode enviar; error.param indica o campoEscolha um destinatário do teste ou um número de envio que atenda às regras acima
402 campaigns_not_entitledO plano do número de envio não inclui CampanhasMude o número para Pro ou teste a partir de um número Pro
409 bansafe_cold_heldO destinatário do teste nunca escreveu para o número de envio, e a campanha retém primeiras mensagensEnvie qualquer mensagem do telefone do destinatário do teste para o número de envio e teste de novo
409 state_conflictA campanha não é um rascunho, tem variantes A/B ou messageVariations, o destinatário do teste fez opt-out, ou o número de envio é um número Hybrid LinkTeste antes do lançamento ou escolha outro destinatário do teste ou outro número. Campanhas com variantes A/B ou mensagens alternativas ainda não aceitam envio de teste
422 campaign_variables_missingUma variável do conteúdo selecionado não tem valor de exemplo, valor explícito nem fallbackInforme o valor ausente ou um fallback da campanha antes de testar
429 rate_limit_exceededUm limite de envio de teste foi atingido (Polymorfa-RateLimit-Reason: campaign_test_send), ou o limite de envios de campanha do número foi atingidoAguarde Retry-After
429 bansafe_throttled, 429 bansafe_daily_allowance_reachedO número de envio está com o ritmo limitado ou usou a cota de aquecimentoAguarde Retry-After
503 session_not_readyO número de envio não está conectadoReconecte-o e teste de novo
504 result_unknownO resultado é desconhecido; o teste ainda pode chegarConfira o telefone do destinatário do teste antes de enviar outro teste. Uma nova tentativa com o mesmo Idempotency-Key não envia de novo

Na Platform API, envie o mesmo corpo para API Test send campaign, com projectId quando usar uma chave de API da equipe. No Console, escolha Enviar teste na etapa de revisão do builder ou na página de um rascunho.

Escolha quando a campanha envia#

Por padrão, uma campanha envia em qualquer horário do dia. Defina sendWindow na criação, ou em uma atualização pela Messaging API ou pela Platform API, para enviar apenas nos dias da semana e nos horários locais escolhidos:

JSON
{
  "sendWindow": {
    "timeZone": "America/Sao_Paulo",
    "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
    "hours": [
      { "start": "09:00", "end": "12:00" },
      { "start": "14:00", "end": "18:00" }
    ]
  }
}
CampoRegra
timeZoneNome de fuso horário IANA, como Europe/Lisbon ou UTC. Se você omitir, a Polymorfa armazena o fuso horário da sua equipe, ou UTC quando a equipe não tem um. A campanha sempre retorna o fuso armazenado.
daysDe um a sete valores entre monday e sunday, sem repetição.
hoursDe um a quatro intervalos. start é HH:MM no formato de 24 horas e está incluído; end é HH:MM ou 24:00 e está excluído. Os intervalos não podem se sobrepor nem passar da meia-noite. Para 20:00 a 02:00, use dois intervalos, 20:00–24:00 e 00:00–02:00; cada intervalo vale em todos os dias de days.
recipientTimeZonetrue aplica a janela no horário local de cada destinatário. O padrão é false.
timeZoneVariableVariável do destinatário que contém o fuso horário IANA dele. O padrão é timeZone.

Um destinatário cuja vez chega fora da janela não falha nem é ignorado. O destinatário continua queued e é enviado depois que a janela abrir de novo, no ritmo normal da campanha. A campanha continua running, as contagens não mudam e nenhum evento de destinatário é enviado durante a espera. Uma campanha cuja janela está fechada para todos não envia nada até a janela abrir. As mudanças de horário de verão seguem as regras do fuso horário.

Com recipientTimeZone definido como true, o fuso de cada destinatário é:

  1. o fuso na variável do destinatário indicada por timeZoneVariable, quando for um nome IANA válido;
  2. senão, o fuso do país do número de telefone, quando o país inteiro usa um único deslocamento de UTC. Por exemplo, números +44 usam Europe/London. Países com vários deslocamentos, como Estados Unidos, Brasil e México, não são resolvidos dessa forma;
  3. senão, o timeZone da janela.

Os fusos dos destinatários são resolvidos quando a campanha é lançada. Para definir um fuso você mesmo, adicione uma variável com o nome de timeZoneVariable a cada membro do público ou destinatário da requisição, por exemplo "variables": { "timeZone": "Asia/Tokyo" }. Se essa variável tiver mais de 5.000 valores distintos não vazios, o lançamento retorna 400 invalid_parameter com error.param definido como sendWindow.timeZoneVariable. Corrija os valores do público antes de lançar.

Uma janela inválida retorna 400 invalid_parameter, e error.param indica o campo, como sendWindow.hours[1]. Envie "sendWindow": null para remover a janela. Você pode mudar ou remover a janela enquanto a campanha é um rascunho ou está pausada. Uma campanha em andamento retorna 409 state_conflict: pause-a, atualize a janela e retome-a. Se uma campanha pausada ainda tiver envios em andamento, a edição retorna 409 state_conflict; tente novamente depois que esses envios forem concluídos. Um envio travado que não chegou ao provedor pode ser recuperado em uma tentativa de edição posterior. Se a entrega pode ter começado, a edição retorna 409 state_conflict enquanto esse envio está em andamento. Tente novamente depois que ele for concluído. Se o resultado dele se perder, o destinatário acaba se tornando um envio com falha e resultado desconhecido; a campanha não o envia de novo. A nova janela vale para os destinatários restantes.

Lance a campanha#

cURL
# 24 hours from now, in Unix milliseconds. Reuse this value if you retry with the same key.
SCHEDULED_AT=$(( ($(date +%s) + 86400) * 1000 ))
curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/launch" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: september-launch-start-1" \
  -d "{ \"scheduledAt\": $SCHEDULED_AT }"
TypeScript
// 24 hours from now. Reuse this value if you retry with the same key.
const scheduledAt = Date.now() + 24 * 60 * 60 * 1000;
const launched = await messaging.campaigns.launch("<project-slug>", campaignId, {
  scheduledAt,
});
await platform.operations.wait(launched.data.data.operationId);

TypeScript:

Omita scheduledAt para começar agora. launch retorna assim que o lançamento é aceito; o envio continua em segundo plano como uma operação.

O envio começa em scheduledAt, ou imediatamente quando nenhum horário de início é definido. No lançamento, a Polymorfa copia o público para a campanha, ignora os números na lista de opt-outs da equipe e define recipientCount a partir dos destinatários que existem.

Em uma campanha agendada, esse retrato é feito quando a requisição de lançamento é aceita. Adições, remoções ou alterações posteriores no público de origem não mudam os destinatários dessa campanha. Os opt-outs são verificados de novo antes do envio.

O lançamento verifica a seleção de números salva na campanha em relação aos planos dos números naquele momento, então um número que mudou de plano depois que o rascunho foi salvo é verificado no novo plano. Todo número fixado precisa estar conectado e em um plano que inclua Campanhas, e todos os números fixados precisam usar um único tipo de envio:

Status e códigoCausa
403 bansafe_team_suspendedA equipe está suspensa
402 campaigns_not_entitledO plano de um número fixado não inclui Campanhas, um número fixado não está no projeto, ou uma campanha que não fixa números não tem no projeto nenhum número em um plano que inclua Campanhas
400 invalid_parameterUm número fixado está desconectado, não tem telefone ou usa um tipo de envio diferente de outro número selecionado; error.param é senderConfig.sessionIds
400 campaign_throughput_cappedUma vazão solicitada está acima do teto de segurança; error.param indica o campo
400 invalid_parameterO modelo está incompleto; error.param é templateId
400 template_not_approvedO WhatsApp não aprovou o modelo em um número da Cloud API pelo qual a campanha pode enviar
422 campaign_variables_missingAlguns destinatários não têm valor nem fallback para uma variável; a mensagem indica as variáveis e conta os destinatários
409 campaign_approval_requiredSua equipe exige aprovação para lançamentos acima de um limite de destinatários, e este lançamento enviaria para mais destinatários. Nada foi enviado. Consulte Exija aprovação para envios grandes
409 state_conflictA campanha não é um rascunho, já foi lançada e aguarda o horário de início, ou os números de envio, o plano ou a conexão de um número selecionado mudaram enquanto o lançamento era verificado. Para mover um início agendado, reagende-o.
503 service_unavailableNão foi possível verificar os planos dos números; lance de novo

Para enviar a todos, adicione fallbacks ou mapeie outra variável do destinatário e lance de novo. Para lançar sem esses destinatários, envie "skipMissingVariables": true no corpo do lançamento. Eles são marcados como skipped, com lastError missing_variable, antes de a primeira mensagem ser enviada, e contados em skippedCount. Cada mensagem é verificada de novo pelas mesmas regras quando é enviada, então nenhum destinatário recebe uma mensagem com uma variável vazia; um destinatário ignorado nesse momento emite campaign.recipient_skipped com reason missing_variable.

Criar, lançar, reagendar, pausar, retomar, interromper e enviar teste aceitam o cabeçalho Idempotency-Key na Messaging API; a Platform API o aceita em lançar, reagendar, pausar, retomar, interromper e enviar teste. Essas requisições do ciclo de vida da campanha usam uma janela de uma hora nas duas APIs. Uma chave repetida não inicia um segundo lançamento nem um segundo envio de teste.

A primeira requisição retorna seu status e sua resposta originais. Corpos opacos de respostas de campanha não são retidos para repetição. Uma tentativa posterior pode retornar 503 idempotency_replay_unavailable; o registro ainda impede outra execução. Mantenha a mesma chave e consulte a campanha ou os eventos de mensagem para verificar o resultado. Não troque de chave para repetir uma gravação cujo resultado é desconhecido.

Uma tentativa enquanto a primeira requisição ainda está em execução retorna 409 idempotency_in_progress. Reutilizar uma chave com uma requisição diferente retorna 422 idempotency_conflict. Importações de público e acréscimos de destinatários usam registros de metadados e janelas separados, descritos acima. Consulte Erros.

Exija aprovação para envios grandes#

Um proprietário ou administrador da equipe pode exigir aprovação para qualquer lançamento que enviaria para mais destinatários do que um limite. No Console, defina isso em Campanhas > Configurações. Pela API:

Shell
curl -X GET "https://api.polymorfa.com/platform/campaign-settings" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
JSON
{ "launchApproval": { "recipientThreshold": 5000 } }

Apenas um proprietário ou administrador da equipe pode mudar o limite, no Console; um valor vazio desativa a aprovação. Não há API para mudá-lo, então uma credencial não consegue desativar a aprovação que retém os próprios lançamentos.

Quando o limite está definido, um lançamento feito por uma chave de API, um token de projeto ou um membro da equipe que não é proprietário nem administrador conta os destinatários para os quais o lançamento enviaria, depois dos opt-outs. Se forem mais do que o limite, nada é enviado: a campanha continua como rascunho e o lançamento responde 409 campaign_approval_required. A mensagem de erro indica a solicitação de aprovação que foi registrada. Lançar de novo com a campanha inalterada retorna a mesma solicitação. Um lançamento feito por um proprietário ou administrador conectado ao Console não precisa de aprovação.

Liste as solicitações de uma campanha, das mais recentes para as mais antigas:

Shell
curl "https://api.polymorfa.com/platform/campaigns/$CAMPAIGN_ID/approvals?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"

Cada solicitação indica a action retida (launch, resume ou reschedule) e os reasons: audience_threshold, agent_request ou ambos. Cada solicitação tem um status:

StatusSignificado
pendingAguardando um proprietário ou administrador
approvedAprovada; a ação foi executada e operationId é a operação dela
rejectedRejeitada; a ação não foi executada e nada foi enviado
supersededUma solicitação posterior, ou uma alteração na campanha, a substituiu
expiredNão foi decidida em 72 horas

Um lançamento, uma retomada ou um novo horário de início solicitado por um agente de IA pelo servidor MCP hospedado sempre registra uma solicitação com o motivo agent_request, qualquer que seja o limite. Consulte Servidor MCP.

Um proprietário ou administrador aprova ou rejeita uma solicitação na página da campanha no Console. Aprovar lança a campanha na mesma etapa, com todas as verificações de lançamento, o horário de início solicitado e os destinatários contados para a solicitação. Se o conteúdo, os números de envio, o agendamento, o modelo ou os destinatários da campanha mudaram depois da solicitação, nada é enviado e a resposta é 409 campaign_approval_stale; lance de novo para solicitar uma nova aprovação. Uma solicitação pode ser aprovada uma vez. Um horário de início solicitado que já passou inicia a campanha quando ela é aprovada.

Reagende um lançamento agendado#

Uma campanha lançada aguarda o scheduledAt antes de enviar qualquer coisa. Até lá, você pode antecipar ou adiar esse início, ou começar a enviar agora, sem interromper e lançar a campanha de novo:

cURL
# 48 hours from now, in Unix milliseconds. Reuse this value if you retry with the same key.
SCHEDULED_AT=$(( ($(date +%s) + 172800) * 1000 ))
curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/reschedule" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: september-launch-move-1" \
  -d "{ \"scheduledAt\": $SCHEDULED_AT }"
TypeScript
// 48 hours from now. Reuse this value if you retry with the same key.
const rescheduledAt = Date.now() + 48 * 60 * 60 * 1000;
await messaging.campaigns.reschedule("<project-slug>", campaignId, {
  scheduledAt: rescheduledAt,
});

TypeScript:

reschedule envia uma chave de idempotência e faz uma única tentativa, a menos que você defina maxNetworkRetries.

Na Platform API, envie o mesmo corpo para API Reschedule campaign, com projectId no corpo quando usar uma chave de API da equipe.

scheduledAt é obrigatório. Defina-o como um horário Unix em milissegundos, ou como null para começar a enviar agora. Um horário que não está no futuro também inicia a campanha agora. A resposta é a campanha com o novo scheduledAt e o operationId da execução de entrega. Enviar de novo o horário de início atual não muda nada.

Reagendar muda apenas quando a campanha começa. Os destinatários e as mensagens continuam como estavam quando você a lançou. Cada envio ainda é verificado quando a campanha começa, da mesma forma que um início que nunca foi movido. Cada alteração aceita é registrada como uma entrada rescheduled no histórico da campanha e envia um evento campaign.rescheduled.

Status e códigoCausa
400 invalid_parameterscheduledAt está ausente, ou não é um número inteiro positivo nem null
403 bansafe_team_suspendedA equipe está suspensa. Você ainda pode interromper a campanha.
409 state_conflictA campanha já começou, terminou ou está sendo interrompida, ou nunca foi lançada. Em vez disso, lance um rascunho com scheduledAt.

Depois que uma campanha é lançada, uma atualização não muda o scheduledAt. Uma atualização que envia um scheduledAt diferente retorna 409; em vez disso, reagende a campanha.

No Console, abra uma campanha agendada e escolha Reagendar. Escolha uma nova data e hora no fuso horário do seu navegador, ou escolha Iniciar agora.

Acompanhe o envio#

Liste os destinatários na ordem da fila, com paginação por cursor. limit vai de 1 a 100, com padrão 25.

cURL
curl "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/recipients?status=skipped&reason=opted_out&limit=100" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
TypeScript
const stats = await messaging.campaigns.analytics("<project-slug>", campaignId);
console.log(stats.data.data.sentCount, stats.data.data.deliveredCount);

let cursor: string | undefined;
do {
  const page = await messaging.campaigns.listRecipients("<project-slug>", campaignId, {
    status: "skipped",
    cursor,
  });
  for (const recipient of page.data.data) console.log(recipient.phone, recipient.status);
  cursor = page.data.page.hasMore ? page.data.page.nextCursor ?? undefined : undefined;
} while (cursor);

TypeScript:

A partir da versão 0.1.0-dev.20261004041625 do SDK, os eventos de engajamento dos destinatários são tipados como CampaignRecipientDeliveredPayload, CampaignRecipientReadPayload e CampaignRecipientRepliedPayload. Com um pacote mais antigo, leia os campos documentados em event.payload.

JSON
{
  "success": true,
  "data": [
    {
      "id": "0c0e4f2a-2b1d-4a67-9bb2-1f7f4a2e91a3",
      "phone": "+14155550100",
      "variables": { "first_name": "Ada" },
      "variantKey": null,
      "status": "skipped",
      "attempts": 0,
      "lastError": "opted_out",
      "failureReason": "opted_out",
      "externalMessageId": null,
      "queuedAt": 1758326400000,
      "sentAt": null,
      "deliveredAt": null,
      "readAt": null,
      "failedAt": 1758326402000,
      "respondedAt": null,
      "messagesSent": 0,
      "nextMessageAt": null,
      "sequenceError": null
    }
  ],
  "page": { "nextCursor": "cjE6MjU", "hasMore": true }
}

Siga page.nextCursor até page.hasMore ser false. Filtre com status (queued, sending, sent, delivered, read, failed ou skipped), com reason ou com os dois. messagesSent, nextMessageAt e sequenceError informam o progresso de uma campanha com várias mensagens.

Motivos de falha#

failureReason é o motivo estável pelo qual um destinatário não recebeu o envio, ou pelo qual a última tentativa dele não deu certo. É null quando nada deu errado. Nunca contém o conteúdo da mensagem, o número do destinatário nem um erro bruto. Filtre por ele com reason.

failureReasonSignificado
opted_outO número está na lista de opt-outs da equipe
cold_heldO número nunca escreveu para o número de envio, e a campanha retém envios frios
campaign_cancelledA campanha foi interrompida antes de este destinatário receber o envio
invalid_recipientO número não é um endereço válido do WhatsApp
session_not_connectedO número de envio não estava conectado
ack_timeoutO WhatsApp não confirmou o envio a tempo
blocked_by_safetyUma verificação de segurança recusou o envio antes da tentativa; o destinatário aguarda a campanha ser retomada
send_failedO WhatsApp recusou o envio, ou não foi possível confirmar o resultado
missing_variableO destinatário não tinha valor nem fallback para uma variável: ignorado no lançamento com skipMissingVariables, ou quando uma mensagem foi verificada no momento do envio
frequency_capO destinatário atingiu o limite de frequência de contato móvel da equipe ou da campanha
otherQualquer outro motivo

Novos códigos podem ser adicionados, então trate um valor desconhecido como other. O campo legado lastError retorna o mesmo código normalizado de failureReason; erros brutos armazenados não são retornados.

Exporte os destinatários como CSV#

GET .../recipients/export retorna CSV na ordem da fila. Exportações sem filtro retornam até 1.000 linhas por requisição (limit, padrão 1.000). Cada página começa com uma linha de cabeçalho. Quando restam mais linhas, envie o cabeçalho de resposta Polymorfa-Next-Cursor como cursor para obter a próxima página.

Os filtros de status e de motivo de falha retornam uma página de até 1.000 destinatários correspondentes. Exportações filtradas não podem usar cursor, e limit, se enviado, precisa ser 1000; qualquer outro valor retorna 400. Se mais de 1.000 destinatários corresponderem, a API retorna 409 sem um arquivo parcial. Para resultados maiores, exporte todos os destinatários e filtre o CSV localmente. Campos entre aspas podem conter vírgulas e quebras de linha, então leia o arquivo com um parser de CSV. Salve este exemplo como um script; ele termina com um código diferente de zero se qualquer página falhar:

cURL
#!/bin/sh
set -eu
pages=$(mktemp -d)
trap 'rm -rf "$pages"' EXIT
cursor=""
page=0
while :; do
  page=$((page + 1))
  # -f exits nonzero on an HTTP error and writes no error body to the page file.
  curl -fsS -D "$pages/headers.txt" -o "$pages/$(printf '%06d' "$page").csv" \
    "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/recipients/export${cursor:+?cursor=$cursor}" \
    -H "Authorization: Bearer $POLYMORFA_KEY"
  cursor=$(grep -i '^polymorfa-next-cursor:' "$pages/headers.txt" | cut -d' ' -f2 | tr -d '\r')
  [ -n "$cursor" ] || break
done

python3 - "$pages"/*.csv > failed-recipients.csv <<'PY'
import csv, sys

writer = None
for path in sys.argv[1:]:
    with open(path, newline="", encoding="utf-8") as page:
        reader = csv.DictReader(page)
        if writer is None:
            writer = csv.DictWriter(sys.stdout, reader.fieldnames)
            writer.writeheader()
        writer.writerows(row for row in reader if row["status"] == "failed")
PY
TypeScript
// parseCsv is your CSV library's parser: one object per row, keyed by the header.
const failed: Array<Record<string, string>> = [];
let exportCursor: string | undefined;
do {
  const page = await messaging.campaigns.exportRecipients("<project-slug>", campaignId, {
    cursor: exportCursor,
  });
  failed.push(...parseCsv(page.data.csv).filter(row => row.status === "failed"));
  exportCursor = page.data.nextCursor ?? undefined;
} while (exportCursor);

TypeScript:

exportRecipients baixa o CSV uma página por vez e devolve o cursor da próxima página em nextCursor.

csv
recipientId,phone,status,failureReason,attempts,variantKey,queuedAt,sentAt,deliveredAt,readAt,failedAt,respondedAt
0c0e4f2a-2b1d-4a67-9bb2-1f7f4a2e91a3,'+14155550100,failed,invalid_recipient,3,,2026-09-20T00:00:00.000Z,,,,2026-09-20T00:04:12.000Z,

Os horários estão em ISO 8601 em UTC, e campos vazios são nulos. Um apóstrofo no início mantém os números de telefone como texto em planilhas; remova-o ao ler células de telefone no código. A exportação nunca contém conteúdo de mensagens nem variáveis de modelo. Uma página sem filtro reflete o resultado de cada destinatário no momento da requisição. Um arquivo filtrado reflete uma única leitura do banco de dados, então mudanças de status não causam omissões entre páginas filtradas. A Platform API oferece a mesma exportação em GET /platform/campaigns/{campaignId}/recipients/export?projectId=....

No Console, o painel Destinatários da campanha filtra por status e motivo, e Baixar CSV salva até 1.000 destinatários filtrados pela mesma exportação. Para resultados filtrados maiores, limpe os filtros, baixe todos os destinatários e filtre o arquivo localmente.

As análises da campanha informam o funil e o tempo de resposta:

Shell
curl "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/analytics" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
CampoSignificado
recipientCountDestinatários na campanha
sentCountMensagens aceitas pelo WhatsApp
deliveredCountDestinatários cujo aparelho confirmou a entrega
readCountDestinatários que abriram a mensagem; uma leitura implica uma entrega
failedCountEnvios que o WhatsApp recusou
skippedCountDestinatários que nunca receberam uma tentativa, como por opt-out ou retenção de envio frio
respondedCountDestinatários que responderam
responseRaterespondedCount dividido por sentCount, e 0 antes de qualquer envio
averageResponseTimeMsTempo médio do envio até a primeira resposta, e null antes da primeira resposta
minResponseTimeMs, maxResponseTimeMsPrimeira resposta mais rápida e mais lenta

Uma resposta conta uma vez por destinatário. Ela é atribuída ao destinatário mais recente para o qual o número que respondeu recebeu um envio, no mesmo número de envio, em até 7 dias depois desse envio.

Para contar quem abre um link na mensagem, consulte Rastreie links de campanha.

Inscreva um webhook de projeto em campaign.recipient_delivered, campaign.recipient_read e campaign.recipient_replied para acompanhar cada destinatário depois do envio, quando sua equipe estiver inscrita no beta de eventos de engajamento de destinatários e o lançamento gradual dele estiver ativado. As cargas do webhook incluem os IDs da campanha e do destinatário, o número de envio e o ID da mensagem original, quando disponível. O evento de resposta inclui o tempo decorrido, mas não o corpo da mensagem. Se sua equipe tem acesso ao beta do stream de eventos com credencial de servidor, as entradas dele expõem o tipo e o horário do evento sem esses campos do destinatário. Use a API de Campanhas para obter o status do destinatário a partir de uma notificação do stream. Tokens de cliente não podem abrir esse stream.

A Platform API também lista o histórico do ciclo de vida da campanha, do mais recente para o mais antigo:

Shell
curl "https://api.polymorfa.com/platform/campaigns/$CAMPAIGN_ID/events?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"

Cada entrada traz kind (launched, rescheduled, paused, resumed, cancelled, completed ou failed) e o horário em que aconteceu. Uma entrada rescheduled tem payload.previousScheduledAt e payload.scheduledAt. Uma entrada failed tem payload.reason: "all_recipients_failed". A campanha falha quando todos os destinatários terminam como falha. Se algum destinatário recebeu o envio ou foi ignorado, a campanha é concluída e as contagens mostram esses resultados.

Pause, retome e interrompa#

cURL
curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/pause" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
TypeScript
await messaging.campaigns.pause("<project-slug>", campaignId);
await messaging.campaigns.resume("<project-slug>", campaignId);

const stopped = await messaging.campaigns.stop("<project-slug>", campaignId);
if (stopped.data.data.operationId !== null) {
  await platform.operations.wait(stopped.data.data.operationId);
}

TypeScript:

create, launch, pause, resume e stop criam uma chave de idempotência quando você não passa nenhuma. Se uma resposta se perder, leia a campanha antes de tentar de novo.

Pausar retém uma campanha em andamento; os envios já em andamento terminam. Retomar envia aos destinatários restantes depois das mesmas verificações de antes da pausa, incluindo a janela de envio.

Interromper cancela. Os destinatários que ainda não receberam o envio não o recebem: cada destinatário na fila passa a ser skipped com failureReason campaign_cancelled e é contado uma vez em skippedCount. A campanha passa para cancelling e depois para cancelled quando os envios já em andamento terminam. Uma campanha sem execução de entrega ativa fica cancelled na hora, e operationId é null. A interrupção nunca é bloqueada por suspensão nem pela perda do direito do plano, então uma campanha restrita sempre pode ser interrompida.

No Console, Interrupção solicitada confirma que sua solicitação foi aceita. A página de detalhes é atualizada até a campanha chegar a Cancelada e mostra os resultados finais dos destinatários. Os envios já em andamento podem terminar durante essa transição.

Uma campanha sem execução de entrega ativa não pode ser pausada nem retomada. Interrompa-a, duplique-a e lance a cópia.

Arquive ou exclua#

Arquive uma campanha completed, failed ou cancelled quando quiser manter o histórico dela e marcá-la como arquivada. Uma campanha que ainda está iniciando, em andamento, pausada ou sendo interrompida não pode ser arquivada.

Excluir remove uma campanha draft, completed, failed, cancelled ou archived. Qualquer outra campanha, e um rascunho que ainda tem um lançamento agendado, é recusada com 409: interrompa-a primeiro e depois exclua-a. Se uma campanha concluída ou com falha ainda tiver um evento final a entregar, excluir ou arquivar retorna 409. Arquivar e excluir também aguardam o fim da execução de entrega. Tente novamente depois que o evento e a execução terminarem.

Shell
curl -X DELETE "https://api.polymorfa.com/platform/campaigns/$CAMPAIGN_ID?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"

Reenvie o que falhou#

POST .../requeue devolve os destinatários com falha para queued. Defina includeSkippedError como true para devolver à fila também os destinatários ignorados. Um número na lista de opt-outs da equipe nunca é reservado para envio, qualquer que seja o status do destinatário.

TypeScript:

No SDK, chame messaging.campaigns.requeue("<project-slug>", campaignId), com { includeSkippedError: true } para incluir os ignorados.

Se a entrega não puder começar, o destinatário continua na fila para uma nova tentativa automática. Se um envio pode ter chegado ao WhatsApp, mas o resultado não pode ser confirmado, o destinatário não recebe o envio de novo automaticamente.

Variáveis de destinatário nos botões#

O texto e os destinos dos botões são verificados depois que o mapeamento e os valores alternativos das variáveis são resolvidos. Códigos de cópia são literais: não usam variáveis de destinatário nem valores alternativos. O envio de teste é verificado antes de ser admitido. A campanha verifica os valores dos destinatários na fila no lançamento e de novo no envio. Destinatários de reserva do teste A/B são verificados só no envio, porque a variante deles é escolhida nesse momento. Um link pode usar {{shop_url}} ou um valor alternativo, como {{shop_url | https://example.com}}. O resultado deve ser uma URL HTTPS absoluta, com nome de host e no máximo 2.048 bytes UTF-8. Destinos de chamadas aceitam apenas dígitos e um + inicial opcional, com 6–20 caracteres no total.

Os rótulos, o corpo e o rodapé expandidos precisam respeitar os limites do transporte selecionado. Rótulos de respostas da API Oficial devem continuar distintos após a substituição. Botões de cópia em modelos de Dispositivo Vinculado precisam de um código não vazio de até 256 bytes UTF-8. Modelos congelados de acompanhamento passam pelas mesmas verificações de controles nativos do modelo inicial.