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

Construa (build) um público

Crie uma lista reutilizável de números e variáveis de modelo a partir de membros enviados na requisição ou de um arquivo CSV e mantenha essa lista atualizada.

Ver em Markdown

Um público é uma lista de números de telefone, cada um com as próprias variáveis de modelo, que pertence à sua equipe. Qualquer campanha em qualquer projeto dessa equipe pode usá-lo. A Polymorfa armazena os membros, faz a contagem e os copia para a campanha quando ela é lançada.

Públicos são um recurso da equipe. Use uma chave de API da equipe: campaigns:read para ler e campaigns:manage para alterar. Tokens de projeto são recusados em todas as rotas de público.

Para guardar atributos e declarações de consentimento fornecidos por você para cada número de telefone, consulte Gerenciar perfis de público.

Crie um público com membros na requisição#

Envie até 1.000 membros no corpo da requisição.

cURL
curl -X POST "https://api.polymorfa.com/platform/audiences" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "September launch",
    "members": [
      { "phone": "+14155550100", "variables": { "first_name": "Ada", "plan": "pro" } },
      { "phone": "+442071838750", "variables": { "first_name": "Alan" } }
    ]
  }'
TypeScript
const audience = await platform.audiences.create({
  name: "September launch",
  members: [
    { phone: "+14155550100", variables: { first_name: "Ada", plan: "pro" } },
    { phone: "+442071838750", variables: { first_name: "Alan" } },
  ],
});

console.log(audience.data.data.id, audience.data.data.invalidRows);

TypeScript:

Os públicos usam o cliente da equipe. create aceita até 1.000 membros e informa as linhas inválidas em invalidRows em vez de fazer a solicitação falhar.

A resposta traz o público e o que a importação fez com os dados enviados:

JSON
{
  "data": {
    "id": "3b2f0c4e-6c1a-4a9b-9a53-6b7c9d0e1f22",
    "name": "September launch",
    "source": "manual",
    "recipientCount": 2,
    "duplicateCount": 0,
    "invalidCount": 0,
    "invalidRows": []
  }
}

recipientCount é o número de membros que a Polymorfa armazenou. Uma contagem enviada na requisição é ignorada.

Importe um arquivo CSV#

A importação de um arquivo leva três requisições: peça uma URL de upload, envie o arquivo e crie o público a partir do arquivo armazenado.

Peça uma URL de upload. Ela é de uso único e expira pouco depois de ser emitida.

Shell
curl -X POST "https://api.polymorfa.com/platform/audiences/uploads" \
  -H "Authorization: Bearer $POLYMORFA_KEY"

Envie o arquivo para essa URL. A resposta traz storageId.

Shell
curl -X POST "$UPLOAD_URL" \
  -H "Content-Type: text/csv" \
  --data-binary @contacts.csv

Crie o público a partir do arquivo armazenado, passando storageId como fileId e indicando as colunas.

Shell
curl -X POST "https://api.polymorfa.com/platform/audiences" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "September launch",
    "fileId": "'"$STORAGE_ID"'",
    "mapping": {
      "phone": "Mobile",
      "variables": { "first_name": "First name", "plan": "Plan" }
    }
  }'

mapping.phone indica a coluna que contém o número. mapping.variables associa o nome de cada variável de modelo à coluna que fornece o valor. Os nomes de coluna são comparados primeiro de forma exata e, depois, sem diferenciar maiúsculas de minúsculas.

A Polymorfa lê o arquivo no servidor. O arquivo precisa estar em UTF-8 e ter uma linha de cabeçalho. O separador é detectado pela linha de cabeçalho: vírgula, ponto e vírgula ou tabulação, e vírgula quando a linha é ambígua. Campos entre aspas, aspas duplicadas dentro de um campo entre aspas, quebras de linha dentro de um campo entre aspas e finais de linha LF, CRLF ou CR são lidos corretamente. Linhas em branco são ignoradas.

Envie members ou fileId com mapping. Uma requisição com os dois é recusada.

Regras de números e variáveis#

RegraValor
Formato do númeroInternacional. Espaços, pontos, hifens e parênteses são ignorados; um 00 no início é lido como +; dígitos sem + são lidos como se já incluíssem o código do país
Tamanho do númeroDe 8 a 15 dígitos, incluindo o código do país, e um tamanho possível para esse país
Variáveis por membroNo máximo 50
Nome da variávelComeça com uma letra, um dígito ou _, seguido de até 63 caracteres entre letras, dígitos, _, . e -
Valor da variávelUma string, um número ou um booleano, armazenado como string de no máximo 1.024 caracteres
Membros por requisiçãoNo máximo 1.000
Linhas de dados por importação de arquivoNo máximo 100.000

Um número nacional sem código do país não pode ser resolvido e é informado como inválido. Um arquivo com mais de 100.000 linhas de dados é recusado com 413: divida-o em arquivos menores e importe cada um.

Veja o que a importação rejeitou#

Cada criação e cada acréscimo informam as linhas que não foram armazenadas, para que você corrija e reenvie apenas essas linhas:

CampoSignificado
recipientCountMembros no público após a requisição
duplicateCountEntradas válidas ignoradas porque o número se repetiu na requisição ou já está no público
invalidCountEntradas que falharam na validação
invalidRowsAté 20 exemplos, cada um com row e reason

reason é missing_phone, invalid_phone, invalid_variables ou invalid_entry. Para membros enviados na requisição, row é a posição no array, começando em 1. Para um arquivo, row é o número da linha na planilha, em que o cabeçalho é a linha 1.

Mantenha um público atualizado#

cURL
# Add up to 1,000 members
curl -X POST "https://api.polymorfa.com/platform/audiences/$LIST_ID/members" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "members": [{ "phone": "+14155550101", "variables": { "first_name": "Grace" } }] }'

# Page through members in the order they were added
curl "https://api.polymorfa.com/platform/audiences/$LIST_ID/members?limit=100" \
  -H "Authorization: Bearer $POLYMORFA_KEY"

# Remove one member
curl -X DELETE "https://api.polymorfa.com/platform/audiences/$LIST_ID/members/%2B14155550101" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
TypeScript
await platform.audiences.addMembers("<audience-id>", {
  members: [{ phone: "+14155550101", variables: { first_name: "Grace" } }],
});

TypeScript:

Percorra os membros página por página com platform.audiences.listMembers(audienceId, { cursor }), passando o page.nextCursor da página anterior.

A listagem de membros usa paginação por cursor: limit vai de 1 a 100, com padrão 25, e page.nextCursor traz a próxima página até page.hasMore ser false. Adicionar um número que já é membro faz com que ele seja ignorado e informado em duplicateCount. Remover um membro altera apenas o público. Uma campanha que já foi lançada mantém os destinatários que copiou.

Duplicar uma campanha vinculada a um público cria um rascunho com esse mesmo público. A cópia recebe os membros do público quando é lançada, incluindo as mudanças de membros desde o lançamento original. Uma campanha sem público copia os destinatários dela para o novo rascunho.

Redirecione destinatários de uma campanha anterior#

Construa (build) um público com os destinatários de uma campanha que você já enviou, filtrados pelo que aconteceu com eles, e envie a essas pessoas uma campanha de acompanhamento.

cURL
curl -X POST "https://api.polymorfa.com/platform/audiences/from-campaign" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring launch: did not read",
    "campaignId": "'"$CAMPAIGN_ID"'",
    "outcome": "not_read"
  }'
TypeScript
const followUp = await platform.audiences.createFromCampaign({
  name: "Spring launch: did not read",
  campaignId: "<campaign-id>",
  outcome: "not_read",
});
console.log(followUp.data.data.recipientCount, followUp.data.data.optedOutCount);

TypeScript:

O SDK envia essa solicitação uma única vez. Se a resposta se perder, liste os seus públicos antes de criar outro.

outcomeDestinatários selecionados
deliveredO aparelho do destinatário confirmou a entrega
not_deliveredEnviada, sem confirmação de entrega
readLeram a mensagem
not_readEnviada e não lida, incluindo mensagens nunca entregues
repliedResponderam à mensagem
not_repliedEnviada, e nenhuma resposta foi atribuída ao destinatário
failedEnvios com falha confirmada; entregas incertas e resultados ambíguos mais antigos ficam de fora

Os resultados de leitura dependem das confirmações de leitura do destinatário: quem as desativou nunca fica como read. As respostas são atribuídas da mesma forma que nas análises da campanha.

A resposta é o novo público, com source definido como campaign, e mais:

CampoSignificado
recipientCountMembros no novo público
matchedCountDestinatários da campanha de origem com esse resultado
optedOutCountDestinatários correspondentes deixados de fora porque o número está na lista de opt-outs da equipe
sourceCampaignId, outcomeA origem usada para criar o público

O público é um retrato do momento em que a requisição é executada. Confirmações, leituras e respostas que chegam depois não o alteram; crie um novo público para incluí-las. Cada membro mantém as variáveis de modelo que tinha na campanha de origem. Os números na lista de opt-outs ficam de fora agora, e qualquer número que fizer opt-out antes do lançamento da campanha de acompanhamento também é ignorado no lançamento. Um número cujo perfil de público foi excluído nos últimos 30 dias também fica de fora.

projectId é opcional. Quando você o envia, a campanha precisa pertencer a esse projeto. A requisição exige uma chave de API da equipe com campaigns:manage, como as outras escritas em públicos. 404 significa que a campanha não está na sua equipe (ou não está em projectId). 409 significa que nenhum destinatário fora da lista de opt-outs tem esse resultado, e nada é criado.

No Console, abra a campanha e escolha Redirecionar… no menu de ações. A ação fica disponível depois que a campanha é lançada.

Tente novamente com segurança#

A criação de um público e a adição de membros aceitam o cabeçalho Idempotency-Key. Envie esse cabeçalho para que uma nova tentativa após um timeout ou uma resposta perdida não crie um segundo público nem informe os membros da primeira requisição como duplicados.

Shell
curl -X POST "https://api.polymorfa.com/platform/audiences/$LIST_ID/members" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-sync-2026-09-24-batch-7" \
  -d '{ "members": [{ "phone": "+14155550102" }] }'
Nova tentativa em até 24 horasResposta
Adicionar membros: mesma chave, mesma credencial, mesmo Polymorfa-Version e mesmo corpo200 com Idempotent-Replayed: true e as contagens da primeira requisição. Nada é gravado de novo
Criar: mesma chave, mesma credencial, mesmo Polymorfa-Version e mesmo corpo200 com Idempotent-Replayed: true, o público como está agora e as contagens de importação da primeira requisição. Nada é gravado de novo
Mesma chave, corpo diferente422 idempotency_conflict
Enviada enquanto a primeira requisição ainda está em execuçãoAguarda a primeira requisição e retorna o resultado dela
Depois que a primeira requisição falhouExecuta de novo. Uma requisição que falhou não deixa registro da chave

Um acréscimo repetido retorna as contagens da primeira requisição, não o tamanho atual do público. Uma criação repetida retorna o público como está agora, com duplicateCount, invalidCount e invalidRows da primeira requisição. Se esse público foi excluído, a nova tentativa retorna 410 resource_gone. Cada nova tentativa verifica seu acesso de novo, então uma nova tentativa para um público excluído, ou com uma credencial que perdeu o acesso, falha. As chaves valem apenas para a credencial que as enviou.

Use o público em uma campanha#

Defina recipientListId na campanha. Os membros são copiados para a campanha quando ela é lançada, os números na lista de opt-outs da equipe são ignorados e recipientCount é definido a partir das linhas que foram de fato criadas. Consulte Envie uma campanha e Opt-outs e respostas STOP.