API de Presets

Um preset de push é um modelo de notificação push reutilizável — o mesmo objeto que você constrói 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 do Notify (payload preset) ou de um ponto de Envio de push da Customer Journey.

URL Base

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

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

Autenticação

Toda requisição deve incluir um cabeçalho Authorization com seu token de API do Servidor:

Authorization: Api SEU_TOKEN_DE_API

Convenções

• Nomenclatura de campos: corpos de requisição e parâmetros de query/path aceitam lowerCamelCase (por exemplo, sendType, localizedProperties, searchByName) — o servidor decodifica qualquer um dos 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/journey acima.
• Chaves de plataforma: os mapas platforms e open_actions são chaveados pelo código de tipo de dispositivo numérico (1 para iOS, 3 para Android, e assim por diante). platform_properties é chaveado pelo nome enum da plataforma (IOS, ANDROID, BAIDU_ANDROID, HUAWEI_ANDROID, OSX — as únicas cinco plataformas que 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á ausente 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 de uma journey em execução ou pausada também retorna 400 Bad Request (um FailedPrecondition na transmissão) — não 409. Remova o preset da journey 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 criar o preset.
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 legado v1.

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% de desconto",
  "platforms": { "1": true, "3": true },
  "localizedContent": {
    "default": "Obtenha seu desconto de 20% agora mesmo",
    "es": "Consigue tu 20% de descuento ahora mismo"
  },
  "localizedTitle": { "default": "Olá" },
  "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 e minúsculas no nome ou código do preset (ILIKE %value%).
searchByCategory	array de 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, etc. — são omitidos, mesmo que definidos no preset.

Campo	Tipo	Descrição
presets	array de objetos	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% de desconto", "code": "AAAAA-BBBBB", "platforms": { "1": true, "3": true }, "categories": ["promo"] }
  ],
  "page": 0,
  "per_page": 100,
  "total": 1
}

Obter

Retorna um único preset de push pelo 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 UpdatePartial 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: {}.

UpdatePartial

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. Ao contrário 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 totalmente o valor existente para esse campo, apenas não afeta nada que você não incluiu). sendType também é aceito, mas ignorado.

Nota

isV2 é a única exceção mesmo aqui: é reescrito a cada chamada de UpdatePartial, padronizando para true quando omitido. Envie isV2: false explicitamente se o preset precisar permanecer um preset no 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

Ao contrário 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% de desconto (cópia)" }

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 journey em execução ou pausada — remova-o da journey 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 da 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, chaveado por código de 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, chaveadas pelo nome enum da plataforma (IOS, ANDROID, BAIDU_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, chaveada por código de 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.

Inbox

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 de strings	Nomes de categoria com os quais o preset é 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 journey.
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 do 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 do FrequencyCapping do 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 / baidu_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, BAIDU_ANDROID, HUAWEI_ANDROID, OSX):

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

Relacionados

Notify

Referência de payload

Referência de pontos da Customer Journey