API de Presets

Um preset de push é um modelo de notificação push reutilizável — o mesmo objeto que você cria no editor de push do Painel de Controle. Esta API gerencia apenas presets de push; presets de SMS, WhatsApp, Kakao, LINE e Viber têm seus próprios serviços de preset dedicados, não abordados aqui.

Use o code de um preset para enviá-lo através de Notify (payload preset) ou de um ponto de envio de push (Send push point) da Customer Journey.

URL Base

https://rpc-api.svc-nue.pushwoosh.com

Todos os endpoints são servidos via HTTPS. Requisições e respostas usam application/json, a menos que seja especificado o contrário.

Autenticação

Toda requisição deve incluir um cabeçalho Authorization com seu token de API do servidor (Server API token):

Authorization: Api YOUR_API_TOKEN

Convenções

• Nomenclatura de campos: corpos de requisição e parâmetros de query/caminho aceitam lowerCamelCase (por exemplo, sendType, localizedProperties, searchByName) — o servidor decodifica ambos os casos. As respostas são sempre codificadas usando os nomes de campo do proto, em snake_case (localized_properties, platform_properties, per_page, e assim por diante). Os exemplos de resposta e a referência do Objeto Preset abaixo usam esse caso.
• code: toda resposta de preset carrega seu próprio código, gerado em Create. Passe este código para Get, Update, UpdatePartial, Delete, Clone, e para as APIs de mensagens/jornada acima.
• Chaves de plataforma: os mapas platforms e open_actions são indexados pelo código numérico do tipo de dispositivo (1 para iOS, 3 para Android, e assim por diante). platform_properties é indexado pelo nome enum da plataforma (IOS, ANDROID, HUAWEI_ANDROID, OSX — as únicas quatro plataformas que ele cobre).
• Campos não preenchidos: as respostas de Get, Create e Clone incluem todos os campos do Objeto Preset, mesmo quando vazios ou com valor zero. List retorna um conjunto de campos reduzido — veja Listar abaixo. Update e UpdatePartial não retornam nenhum campo de preset — veja o aviso em suas seções.

Respostas de erro

Status HTTP	Significado
400 Bad Request	Argumento inválido — um campo obrigatório está faltando ou malformado, ou uma pré-condição falhou (por exemplo, clonar sem um name).
401 Unauthorized	Cabeçalho Authorization ausente ou inválido.
403 Forbidden	O aplicativo ou preset não pertence à conta do chamador.
404 Not Found	O preset ou aplicativo não foi encontrado.
500 Internal Server Error	Falha inesperada no lado do servidor.

Delete em um preset ainda usado por um ponto de envio de push (Send push point) de uma jornada em execução ou pausada também retorna 400 Bad Request (um FailedPrecondition na transmissão) — não 409. Remova o preset da jornada primeiro.

Endpoints

Método	Caminho	Descrição
POST	/api/presets	Criar um novo preset de push
GET	/api/presets	Listar os presets de push de um aplicativo
GET	/api/presets/{code}	Obter um único preset de push
PUT	/api/presets/{code}	Atualizar um preset de push (sobrescrita completa)
PUT	/api/presets/{code}:partial	Atualizar um preset de push (parcial)
POST	/api/presets/{code}:clone	Clonar um preset de push
DELETE	/api/presets/{code}	Excluir um preset de push

Criar

Cria um novo preset de push em um aplicativo e o retorna com seu código gerado.

POST /api/presets

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
application	string	Sim	O código do aplicativo no qual o preset será criado.
name	string	Sim	Nome do preset.
sendType	string	Não	Canal do preset (por exemplo push).
isV2	boolean	Não	Fixa a flag de origem do preset. Omita para o padrão true (v2); defina como false apenas ao reproduzir um preset v1 legado.

Todos os outros campos — conteúdo localizado, plataformas, deep link, inbox, categorias, etc. — são compartilhados com Update e documentados uma vez na referência do Objeto Preset abaixo.

Exemplo de requisição

{
  "application": "XXXXX-XXXXX",
  "name": "20% discount",
  "platforms": { "1": true, "3": true },
  "localizedContent": {
    "default": "Get your 20% discount right now",
    "es": "Consigue tu 20% de descuento ahora mismo"
  },
  "localizedTitle": { "default": "Hi there" },
  "openAction": { "link": { "url": "https://example.com" } },
  "categories": ["promo"]
}

Resposta

Retorna { "preset": { ... } }, o Objeto Preset criado.

Listar

Lista os presets de push de um aplicativo — um conjunto de campos reduzido, não o objeto completo — com paginação, ordenação e filtragem por nome ou categoria.

GET /api/presets

Parâmetros de query

Parâmetro	Tipo	Obrigatório	Descrição
application	string	Sim	O código do aplicativo para listar os presets.
orderBy	string	Não	NAME (padrão), CREATED ou UPDATED.
orderDirection	string	Não	ASC (padrão) ou DESC.
page	integer	Não	Índice da página baseado em zero.
perPage	integer	Não	Tamanho da página. O padrão é 100 quando omitido ou 0.
searchByName	string	Não	Correspondência de substring insensível a maiúsculas no nome ou código do preset (ILIKE %value%).
searchByCategory	array of strings	Não	Repita o parâmetro para filtrar por várias categorias, ex: ?searchByCategory=promo&searchByCategory=lifecycle.
showHidden	boolean	Não	Incluir presets marcados como hidden.

Nota

isDefault é um filtro obsoleto mantido apenas para o formulário legado de envio de push no Painel de Controle — não confie nele.

Resposta

Cada item carrega apenas: name, code, platforms, localized_content (texto simples por localidade — não localized_properties), localized_title, localized_subtitle, banner, icon, categories, journey_uuid, custom_data, is_v2, created, updated. Todos os outros campos do Objeto Preset — localized_properties, platform_properties, deeplink, richmedia, url, e assim por diante — são omitidos, mesmo que definidos no preset.

Campo	Tipo	Descrição
presets	array of objects	A página atual de presets, na forma reduzida descrita acima.
page	integer	O índice da página retornada.
per_page	integer	O tamanho da página usado para esta resposta.
total	integer	Número total de presets que correspondem aos filtros, em todas as páginas.

Exemplo de resposta

{
  "presets": [
    { "name": "20% discount", "code": "AAAAA-BBBBB", "platforms": { "1": true, "3": true }, "categories": ["promo"] }
  ],
  "page": 0,
  "per_page": 100,
  "total": 1
}

Obter

Retorna um único preset de push por seu código, com todos os campos do Objeto Preset preenchidos.

GET /api/presets/{code}

Parâmetros de caminho

Parâmetro	Tipo	Descrição
code	string	O código do preset.

Resposta

Retorna { "preset": { ... } }, o Objeto Preset completo.

Atualizar

Sobrescreve um preset de push existente por código com os campos fornecidos.

PUT /api/presets/{code}

Parâmetros de caminho

Parâmetro	Tipo	Descrição
code	string	O código do preset a ser sobrescrito.

Corpo da requisição

Mesmos campos de Criar (menos application), mais o restante dos campos do Objeto Preset. sendType é aceito, mas ignorado — o canal de um preset não pode ser alterado após a criação.

Omitir um campo nem sempre significa 'deixar inalterado'

Update reconstrói as propriedades de conteúdo do preset do zero a cada chamada: localizedProperties, platformProperties, openAction/openActions, deeplink, deeplinkParams, richmedia, url, campaignCode, filterCode, geoZones, sendRate, cappingCount/cappingDays, os três campos notification*Url, remotePage, wnsContent, originalUrl, as quatro flags *Silent, inboxImage/inboxIcon/inboxDays/inboxDate, banner, icon, customData e isV2 — omita qualquer um desses e ele será limpo (ou, para isV2, redefinido para true).

name, platforms, categories, localizedTitle, localizedSubtitle e localizedContent são a exceção: cada um só é alterado quando você o envia e permanece inalterado quando omitido.

Use Atualização Parcial se você quiser que o primeiro grupo também permaneça inalterado quando omitido.

A resposta não tem campo de preset

Update retorna {} — um objeto vazio. A mensagem de resposta tecnicamente define um campo preset, mas o servidor nunca o preenche. Chame Get depois se precisar do objeto atualizado de volta.

Resposta

Um objeto vazio em caso de sucesso: {}.

Atualização Parcial

Atualiza apenas os campos fornecidos de um preset de push existente por código, deixando os campos não definidos inalterados.

PUT /api/presets/{code}:partial

Parâmetros de caminho

Parâmetro	Tipo	Descrição
code	string	O código do preset a ser corrigido.

Corpo da requisição

Mesmos campos de Atualizar, menos application. Diferente de Update, todos os campos aqui — incluindo localizedProperties, platformProperties, categories e o restante do grupo de propriedades de conteúdo listado no aviso de Atualizar — permanecem inalterados quando omitidos e só são alterados quando você os envia (um campo de mapa/array que você envia ainda substitui completamente o valor existente para esse campo, mas não afeta nada que você não incluiu). sendType também é aceito, mas ignorado.

Nota

isV2 é a única exceção mesmo aqui: é reescrito em cada chamada de UpdatePartial, padronizando para true quando omitido. Envie isV2: false explicitamente se o preset precisar permanecer como um preset do estilo v1.

Exemplo de requisição

{
  "sendRate": 500,
  "cappingCount": 3,
  "cappingDays": 7
}

Resposta

Também um objeto vazio — veja o aviso acima.

Clonar

Duplica um preset de push existente, com um novo nome, no mesmo aplicativo.

POST /api/presets/{code}:clone

Nota

Diferente do Clone da API de Modelos de E-mail, este endpoint não tem um parâmetro application — ele sempre clona dentro do próprio aplicativo do preset de origem. O clone é sempre criado com hidden: false, independentemente da origem.

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
code	string	Sim	Código do preset de origem a ser duplicado.
name	string	Sim	Nome para o novo preset.

Exemplo de requisição

{ "code": "AAAAA-BBBBB", "name": "20% discount (copy)" }

Resposta

Retorna { "preset": { ... } }, o novo Objeto Preset.

Excluir

Exclui permanentemente um preset de push por código.

DELETE /api/presets/{code}

Cuidado

Falha se o preset ainda estiver sendo usado por um ponto send_push em uma jornada em execução ou pausada — remova-o da jornada primeiro. Esta ação não pode ser desfeita.

Parâmetros de caminho

Parâmetro	Tipo	Descrição
code	string	O código do preset a ser excluído.

Resposta

Um objeto vazio em caso de sucesso: {}.

Referência de objeto

Os nomes dos campos abaixo correspondem ao que Get, Create, Update e Clone realmente retornam — nomes de campo do proto em snake_case (veja Convenções). A forma lowerCamelCase usada nos exemplos de requisição acima funciona da mesma maneira na entrada.

Objeto Preset

Identidade

Campo	Tipo	Descrição
code	string	Gerado em Create. Identifica este preset em todos os outros lugares na API.
name	string	Nome do preset.
send_type	string	Canal do preset (por exemplo push).
is_v2	boolean	true para presets criados ou migrados para o modelo de conteúdo v2.
system	boolean	Marca o preset como um preset de sistema/interno.
hidden	boolean	Oculta o preset dos resultados de List (envie showHidden: true para incluí-lo).
created	string (RFC 3339)	Timestamp de criação.
updated	string (RFC 3339)	Timestamp da última atualização.

Direcionamento e conteúdo

Campo	Tipo	Descrição
platforms	map<string, boolean>	Quais plataformas o preset visa, indexado pelo código do tipo de dispositivo (ex: "1" para iOS).
localized_properties	map<string, object>	Localidade → conteúdo rico por plataforma. Mesma forma que LocalizedContent no payload Notify — uma entrada por bloco de plataforma (ios, android, etc.). Esta é a principal maneira de definir conteúdo de push específico da plataforma.
localized_title / localized_subtitle / localized_content	map<string, string>	Localidade → texto simples. Uma alternativa mais simples a localized_properties para título, subtítulo e corpo quando você não precisa de substituições por plataforma.
platform_properties	map<string, object>	Substituições legadas por plataforma, indexadas pelo nome enum da plataforma (IOS, ANDROID, HUAWEI_ANDROID, OSX). Veja o Objeto PlatformProperties abaixo.
open_action	OpenAction	Ação acionada quando o usuário abre a notificação, aplicada a todas as plataformas. Mutuamente exclusivo com open_actions — a resposta define exatamente um.
open_actions	map<string, OpenAction>	Substituição por plataforma de open_action, indexada pelo código do tipo de dispositivo.
deeplink	string	Código de Deep Link.
deeplink_params	map<string, string>	Parâmetros passados para o deep link.
richmedia	string	Código de Rich Media aberto pela notificação.
url	string	URL aberta pela notificação, se não estiver usando um deep link ou Rich Media.

Caixa de entrada

Campo	Tipo	Descrição
inbox_image	string	URL da imagem mostrada na entrada da Caixa de Entrada de Mensagens.
inbox_icon	string	URL do ícone mostrado na entrada da Caixa de Entrada de Mensagens.
inbox_days	integer	Dias que a entrada permanece na Caixa de Entrada de Mensagens.
inbox_date	string (RFC 3339)	Data de expiração explícita para a entrada da Caixa de Entrada de Mensagens, como alternativa a inbox_days.

Organização e metadados

Campo	Tipo	Descrição
categories	array of strings	Nomes de categoria com os quais o preset está marcado.
campaign_code	string	Código de campanha ao qual este preset é atribuído.
filter_code	string	Código de Segmento / Filtro que este preset visa por padrão.
geo_zones	string	Direcionamento de Geozone, se o preset for acionado por geolocalização.
journey_uuid	string	UUID da Customer Journey que possui este preset, se foi criado a partir de um ponto de envio de push de uma jornada.
custom_data	object	JSON de forma livre encaminhado para o SDK do cliente como o parâmetro u.
banner	string	URL da imagem de big-picture / anexo.
icon	string	URL do ícone de notificação personalizado.

Limites de entrega

Campo	Tipo	Descrição
send_rate	integer	Limitação para envios usando este preset, em mensagens/segundo — o equivalente em nível de preset do SendRate de Notify.
capping_count / capping_days	integer	Limite de frequência por usuário para este preset — o equivalente em nível de preset do count / days de FrequencyCapping de Notify.

Webhooks

Campo	Tipo	Descrição
notification_sent_url	string	URL de callback solicitada quando uma notificação usando este preset é enviada.
notification_delivered_url	string	URL de callback solicitada quando uma notificação usando este preset é entregue.
notification_click_url	string	URL de callback solicitada quando uma notificação usando este preset é clicada.

Campos legados

Estes são herdados do modelo de preset v1. Eles são preenchidos para compatibilidade com o Painel de Controle, em vez de para novas integrações.

Campo	Tipo	Descrição
remote_page	string	Referência de página remota legada.
wns_content	string	JSON de modelo de toast do Windows legado, como aceito pelos métodos v1 createPreset/getPreset.
original_url	string	O valor pré-encurtamento de url, quando url foi substituído por um link encurtado.
ios_silent / android_silent / huawei_android_silent	boolean	Flags de push silencioso (apenas dados) por plataforma.

Objeto PlatformProperties

Campos disponíveis em cada entrada de platform_properties (IOS, ANDROID, HUAWEI_ANDROID, OSX):

Campo	Tipo	Descrição
badge	string	Substituição da contagem de emblemas.
sound	string	Nome do arquivo de som.
sound_off	boolean	Silenciar o som da notificação.
priority	string	Prioridade na bandeja (apenas Android/Huawei).
delivery_priority	string	Prioridade de entrega NORMAL ou HIGH (apenas Android/Huawei).
ios_interruption_level	string	passive, active, time-sensitive ou critical (apenas iOS).

Relacionados

Notify

Referência de payload

Referência de ponto da Customer Journey