polymorfa api para enviar uma requisição pela CLI com a credencial
escolhida. Passe um caminho relativo que comece com / e escolha messaging ou
platform como a superfície da credencial:
-X/--method. Forneça uma
credencial à CLI por meio de POLYMORFA_API_KEY ou de um perfil de autenticação
configurado. Mantenha as chaves da equipe em um ambiente confiável. A API
continua aplicando as permissões e o acesso a projetos dessa credencial.
Verifique a configuração da CLI
Executepolymorfa doctor antes de investigar um problema em uma requisição à
API. Ele verifica a versão do Node.js, a configuração de perfis, o acesso ao
keyring, a conectividade com a API e a autenticação da chave de API de servidor:
0 quando todas as verificações obrigatórias são concluídas.
Ele sai com 1 se uma verificação falhar ou se a validação da credencial for
ignorada. Uma credencial ausente ou várias variáveis de ambiente de credencial
fazem a verificação falhar. Um token de projeto ou de cliente é informado como
presente, mas o doctor não consegue validá-lo remotamente e sai com 1; isso
não determina se esse token pode acessar um comando específico. Use uma única
chave de API de servidor para verificar a autenticação. Uma resposta 401
falha; uma resposta 403 gera um aviso de que a chave foi autenticada, mas a
listagem de projetos foi negada. --profile <name> seleciona esse perfil em vez
das credenciais do ambiente. A saída não inclui os valores das credenciais.
Complete comandos no seu shell
Depois de instalar a CLI, carregue o script de autocompletar do seu shell:polymorfa para completar comandos, ou depois de um
comando para completar as flags dele. O script também sugere as opções fixas de
flag quando um comando as define. Ele usa informações da CLI instalada e não
consulta perfis, IDs de projeto, credenciais nem outros valores de argumento.
Você pode adicionar o comando de carregamento ao arquivo de inicialização do
seu shell para as próximas sessões.
Inicie um projeto Node
Executeinit em um diretório onde você queira um projeto inicial em Node.js e
TypeScript:
package.json, src/index.ts, .env.example e um README. Ele
recusa a execução, antes de gravar qualquer coisa, se já existir um arquivo
inicial ou um diretório src. Nenhuma credencial nem vínculo com projeto é
criado. O pacote fixa a versão de desenvolvimento exata publicada do SDK. Execute
npm install e npm run typecheck no diretório do projeto inicial e depois
defina POLYMORFA_API_KEY no seu shell ou gerenciador de segredos antes de
npm start.
Use polymorfa link separadamente quando quiser que os comandos da CLI usem um
projeto.
Inspecione sessões
Use uma chave de API da equipe comsessions:read para inspecionar os metadados
das sessões:
session list retorna todas as sessões da equipe, a menos que você passe um ID
de projeto. Use um ID de sessão dessa lista em view ou status. Esses dois
comandos recusam --project porque o ID da sessão identifica uma única sessão
em toda a equipe. status mostra o status armazenado e o motivo; ele não testa
a conexão em tempo real.
Descubra as sessões do projeto pelo MCP local
Executepolymorfa mcp tools para listar as ferramentas do MCP local.
Instale o servidor MCP local no seu cliente de agente com
polymorfa mcp install codex ou polymorfa mcp install claude. Forneça à CLI
uma chave de API da equipe com sessions:read. A ferramenta somente leitura
polymorfa_session_list exige um UUID de projeto explícito e retorna o ID, o
nome, o status armazenado e o indicador de modo de teste de cada sessão. Ela não
retorna números de telefone, credenciais nem dados de mensagens, e não testa uma
conexão em tempo real. Tokens de projeto e tokens de cliente da Messaging não
podem usar essa ferramenta.
O servidor MCP local também expõe ferramentas para iniciar, consultar o status
e parar o listener. O servidor MCP hospedado é
uma conexão separada.
Encontre documentação
Pesquise na documentação publicada:--json para receber os mesmos
resultados como um array JSON.
Abra uma página pelo caminho mostrado nos resultados:
--print para obter a URL sem abrir um navegador. Um segmento final curto
do caminho só funciona quando identifica uma única página; use o caminho
completo quando várias páginas tiverem o mesmo nome.
Encaminhe eventos para um handler local
polymorfa listen transmite os eventos do projeto e encaminha os corpos exatos
de evento disponíveis para um handler. Use uma chave da equipe ou uma credencial
de projeto com events:listen. Defina POLYMORFA_API_KEY ou
POLYMORFA_PROJECT_TOKEN, ou selecione um perfil de autenticação.
Passe o endereço do handler e grave em um arquivo privado o segredo local de
assinatura, gerado a cada execução:
event_unavailable e interrompe o encaminhamento com
forwarding_failed, em vez de enviar metadados no lugar dele. Consulte
disponibilidade da carga do evento para ver
as outras condições que podem deixar um corpo indisponível.
Verifique a assinatura local antes de processar um corpo encaminhado. Em um
handler TypeScript que usa o pré-lançamento de desenvolvimento do SDK,
passe os bytes da requisição sem parsing, o cabeçalho Polymorfa-Local-Signature
e o segredo da execução para webhooks.verifyLocal:
verifyLocal rejeita uma assinatura inválida ou um carimbo de data e hora com
mais de 300 segundos de diferença do relógio do handler. Rejeite a requisição
quando a verificação falhar. Não faça o parsing nem serialize o corpo de novo
antes da verificação. O segredo local de assinatura é separado do segredo do
seu webhook de produção.
-H adiciona um cabeçalho personalizado às requisições encaminhadas. Repita a
opção para adicionar mais cabeçalhos. Ela não substitui os cabeçalhos de
autenticação, de enquadramento do corpo nem de assinatura da Polymorfa. A CLI
não repete os valores de cabeçalho recusados. Cabeçalhos personalizados não
atravessam um redirecionamento que muda a origem. Mantenha valores secretos
fora dos argumentos de comando.
--skip-verify aceita um certificado autoassinado somente para um destino de
encaminhamento HTTPS em loopback. Ele não altera a verificação de TLS da API da
Polymorfa nem de destinos de encaminhamento públicos. Omita a opção quando o seu
handler tiver um certificado confiável. --json imprime registros JSONL para as
transições do listener, incluindo os eventos recebidos; os heartbeats do
servidor não geram registros de saída. O encaminhamento em JSON ou em um
terminal não interativo exige --forward-secret-out.
Leia todas as páginas
Para um endpoint que retornapage.nextCursor, adicione --paginate. A CLI
envia cada cursor de volta no parâmetro de consulta cursor. Ela para se a API
indicar mais páginas sem um cursor, repetir um cursor ou ultrapassar
--max-pages (100 por padrão).
--json imprime
um único documento com data definido como um array dos corpos das páginas. O
metadata dele contém o status e o ID da requisição da resposta final, quando
existirem, além da contagem de páginas. Use --include para uma saída para
humanos que inclua os metadados de cada resposta. Para reunir esses resultados
de página em um único array, combine-o com --slurp:
--paginate aceita apenas requisições GET. Deixe o parâmetro de consulta
cursor fora do caminho quando a CLI gerenciar a paginação.
Filtre ou formate uma resposta
--jq executa uma expressão jq em cada página. Ele imprime strings sem aspas e
preserva espaços e quebras de linha dentro dos valores de string:
--slurp para passar à expressão um único array com os corpos das páginas:
--template aceita caminhos, range, if e literais de string. Strings entre
aspas podem conter }} sem fechar a ação:
--jq, --template e --json são mutuamente exclusivos. --include não pode
ser combinado com nenhum dos dois filtros. --slurp exige --paginate.
Leia as análises do WhatsApp
Ative as Análises no Console e depois use uma credencial confiável comsessions:read. Selecione um projeto e, se quiser, o UUID do registro de um
número:
--session-id para ler todos os números do projeto. Uma credencial da
organização pode omitir --project para ler a equipe. Uma credencial de projeto
fica restrita ao próprio projeto. --since e --until aceitam datas com fuso
horário explícito; o intervalo máximo é de 366 dias e o padrão são os 30 dias
anteriores.
A tabela mostra atividade, taxas de leitura e de resposta, tempo de resposta e
problemas de conexão. --json retorna a resposta completa da API, incluindo
comparações por tipo e tamanho de mensagem, participação por código de chamada
e por dispositivo, respostas pelo celular, atividade dos clientes e o retrato
atual da fila de respostas. Preserve as taxas anuláveis e os indicadores de
cobertura. A saída para humanos inclui as taxas de atendimento de chamadas, as
chamadas recebidas perdidas, os tempos até o atendimento e as taxas de
retorno, mesmo quando não há telemetria de mensagens. O JSON inclui a cobertura
do tempo das chamadas, os detalhamentos de qualidade e de erros e as séries
diárias de chamadas por número. Com as análises desativadas, nenhum agregado do
negócio é retornado.
Consulte Análises do WhatsApp para ver as definições das
medições.
Exporte métricas de análises
Use a build a partir do código-fonte da CLI para gravar um snapshot compatível com coletores:--session-id para selecionar o UUID do registro de um número ou
--segments para detalhamentos por metadados. --json envolve o texto das
métricas e os metadados HTTP em uma resposta JSON. A saída padrão é o texto das
métricas. As versões publicadas da CLI podem ser anteriores a este comando.
Estes valores são gauges de janelas sobrepostas, não contadores monotônicos.
Consulte a configuração de coletores para ver
a autenticação, as definições das métricas e a configuração do OpenTelemetry.
Intervalos observados do celular
As respostas de análises incluem, emaccountActivity, as somas de duração da
atividade do celular, as contagens de intervalos concluídos, as somas e
contagens dos períodos sem atividade e as médias correspondentes. As linhas das
séries incluem somas e contagens para comparações ponderadas. As séries de
atividade usam intervalos por hora para períodos de até 48 horas e intervalos
diários em UTC para períodos mais longos. Essas observações não medem se o
celular está ligado nem o tempo online/offline verificado. Leia as
definições dos intervalos
antes de interpretá-las. A saída JSON preserva as médias ausentes como null.
Limites de gastos e ordem de cobrança
Use uma chave da organização combilling:read para leituras ou
billing:manage para gravações. As gravações exigem Pay-As-You-Go. Credenciais
de projeto e de cliente não acessam esses controles.
PUT /platform/billing/priorities.
Uma ordem desatualizada ou incompleta falha sem alterações parciais. Consulte
reorder priorities
e set a limit para ver os
corpos das requisições.
Controles financeiros por recurso
Use a credencial da organização combilling:read ou billing:manage e um UUID
de projeto, cliente ou número. Leia um único recurso antes de salvar para obter
expectedBudgetRevision e expectedPriorityRevision:
controls.json contém limitCredits, priority, expectedBudgetRevision e
expectedPriorityRevision. Um valor desatualizado retorna um conflito sem
alterar nenhuma das configurações. limitCredits: null remove o limite. A
criação de um QuickLink real aceita billingControls na entrada JSON; ela exige
uma credencial financeira da equipe e Pay-As-You-Go. Links de teste e
suplementares recusam controles financeiros iniciais.
Ranking de prioridades com financiamento misto
Leia as prioridades de um projeto comGET /platform/billing/priorities?projectId=PROJECT_UUID.
Reordene os clientes e os números reais do projeto juntos com PUT /platform/billing/priorities:
Capacidades de grupo armazenadas
As versões da CLI que contêmgroup capabilities leem as configurações de grupo
armazenadas com:
groups:read. O número vinculado precisa ser
membro atual do grupo e a equipe precisa ter acesso ao beta de capacidades do
número. Uma configuração desconhecida continua desconhecida; o comando não abre
o chat nem busca a configuração dele. Consulte
Capacidades do número.
Gerencie as chaves da organização e os tokens de projeto no Console.
A CLI não oferece comandos para criar, listar ou revogar essas credenciais. As
operações com tokens de cliente continuam disponíveis pela API pública.