Notify

POST https://api.pushwoosh.com/messaging/v2/notify

Cria e agenda uma única mensagem.

Estrutura da requisição

O corpo da requisição é um NotifyRequest com exatamente um de dois tipos:

• segment: direciona um segmento de público por código de segmento, ou — sem criar um segmento primeiro — uma expressão seglang ou uma expressão de filtro estruturada.
• transactional: envia para uma lista explícita de hwids, IDs de usuário, tokens de push ou dispositivos de teste.

Shape

{
  "segment": { ... },      // OR
  "transactional": { ... },
  "transaction_id": "unique-uuid"
}

Campo	Tipo	Descrição
transaction_id	string	Opcional. Chave de idempotência para a requisição — funciona tanto com segment quanto com transactional. Uma chamada repetida com o mesmo transaction_id dentro de 5 minutos retorna o message_code original em vez de enviar uma mensagem duplicada. Use um UUID ou outro valor único por envio lógico.

Dica

Passe um cabeçalho X-Request-ID para correlacionar a mensagem criada com sua requisição para rastreamento de ponta a ponta — veja ID da Requisição.

Apenas a chave é verificada, não o payload

A desduplicação corresponde apenas ao transaction_id. Se uma nova tentativa reutilizar o mesmo transaction_id mas enviar um corpo segment / transactional diferente, o message_code original ainda será retornado e o novo corpo será descartado silenciosamente — ele não é comparado com a primeira requisição. Nunca reutilize um transaction_id em mensagens logicamente diferentes.

Dica

Este é o mesmo mecanismo de desduplicação que o transactionId na API de Mensagens legada, compartilhando a mesma janela de armazenamento de 5 minutos, então uma requisição repetida é desduplicada tanto em /createMessage quanto em Notify. Não está relacionado ao atributo transaction_id em eventos de receita PW_Conversion, que o Pushwoosh armazena como está e não usa para desduplicação.

NotifySegment

Direciona usuários que correspondem a um segmento de público ou expressão de filtro. Defina exatamente um entre code, expression ou filter_expression. Para expression e filter_expression, nenhum segmento precisa ser criado previamente — a expressão é avaliada inline apenas para este envio.

Escolhendo entre código e expressões inline

Apenas um segmento salvo referenciado por code pode usar a pré-compilação de entrega de alta velocidade. expression e filter_expression são avaliados no momento do envio e nunca são pré-compilados.

Campo	Tipo	Descrição
schedule	Schedule	Quando e como enviar. Obrigatório.
application	string	Código do Aplicativo.
platforms	array of Platform	Plataformas que a mensagem direciona.
code	string	Código do Segmento de um segmento salvo antecipadamente. Mutuamente exclusivo com expression e filter_expression.
expression	string	Expressão Seglang, avaliada apenas para este envio — nenhum segmento salvo é necessário. Mutuamente exclusivo com code e filter_expression.
filter_expression	FilterExpression	A mesma lógica que expression, como um objeto estruturado em vez de uma string seglang. Mutuamente exclusivo com code e expression. O esquema FilterExpression não está documentado publicamente — solicite-o ao suporte da Pushwoosh se precisar do formato estruturado.
payload	Payload	Payload de Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger. Mutuamente exclusivo com email_payload.
email_payload	EmailPayload	Payload de e-mail.
campaign	string	Código da Campanha para atribuir esta mensagem.
campaign_name	string	Nome interno desta mensagem, exibido como o título da linha no Message History e em sua exportação. Sem relação com campaign acima. Não agrupa mensagens nem afeta a entrega. Máximo de 255 caracteres, cortado. Omita-o ou deixe-o vazio para que o título da linha venha do próprio conteúdo do payload.
frequency_capping	FrequencyCapping	Limites de frequência por usuário.
send_rate	SendRate	Controle de velocidade para o envio.
silent_hours	SilentHours	Opcional. Envia a mensagem sem as horas de silêncio do aplicativo.
message_type	MessageType	MESSAGE_TYPE_MARKETING (padrão) ou MESSAGE_TYPE_TRANSACTIONAL. Controla a filtragem do grupo de controle.
dynamic_content_placeholders	map<string, string>	Substitui placeholders no conteúdo.
meta_data	object	Metadados de formato livre encaminhados para análises downstream.
use_latest_user_device	bool	Quando true, entrega a mensagem para o dispositivo mais recentemente ativo de cada usuário (aquele com a última Abertura de Aplicativo) em vez de para todos os dispositivos correspondidos pelo segmento. Escopo para platforms: apenas dispositivos nessas plataformas são considerados, e se nenhum tiver dados de Última Abertura de Aplicativo, o primeiro dispositivo correspondente é usado em vez de descartar o envio. O padrão é false (enviar para todos os dispositivos).
geo_zone	GeoZone	Opcional. Restringe o público aos dispositivos cuja última localização registrada está dentro de um círculo que você define nesta solicitação. É combinado com code, expression ou filter_expression por AND: o dispositivo precisa corresponder ao segmento e estar dentro do círculo. Dispositivos sem localização registrada são ignorados. Não disponível em NotifyTransactional.
control_group	string	Código ou nome de um grupo de retenção próprio do envio, a ser aplicado a esta mensagem. Ele não restringe quais grupos de controle se aplicam: todo grupo de controle ativo do aplicativo retém usuários dos envios de marketing, com este campo definido ou não. Mutuamente exclusivo com holdout_percentage.
holdout_percentage	uint32	Separa esta parcela do segmento, de 1 a 20, em um grupo de controle restrito a este envio, além dos grupos de controle ativos do aplicativo, para medir o impacto de uma única campanha sem consumir os grupos compartilhados. 0 (padrão) o mantém desativado. Mutuamente exclusivo com control_group.

Importante

O Pushwoosh nomeia o grupo de retenção como __holdout_<campaign code> (ou __holdout_<message code> para um envio sem campaign) e reutiliza esse mesmo grupo, com sua porcentagem original, em todo envio posterior que compartilhe o código. A seleção é fixada na primeira vez que o grupo é criado. Esse grupo nunca aparece em Configurações > Grupos de controle, e redimensioná-lo, reembaralhá-lo, desativá-lo ou excluí-lo retorna FailedPrecondition, porque alterá-lo no meio da medição invalidaria a comparação.

Os dispositivos selecionados para o grupo de retenção são excluídos da entrega da mesma forma que pelos grupos de controle do aplicativo. Nada é enviado a eles, e o log de rastreamento registra o descarte como Device is in control group. Um message_type igual a MESSAGE_TYPE_TRANSACTIONAL ignora totalmente essa exclusão, assim como ocorre com os grupos de controle do aplicativo.

Definir holdout_percentage junto com control_group, ou um holdout_percentage acima de 20, retorna 400:

Invalid holdout_percentage

{
  "code": 3,
  "message": "invalid argument",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.BadRequest",
      "fieldViolations": [
        {
          "field": "holdout_percentage",
          "description": "holdout_percentage and control_group are mutually exclusive"
        }
      ]
    },
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "InvalidHoldoutPercentage",
      "domain": "api.pushwoosh.com",
      "metadata": {}
    }
  ]
}

Exemplo: Enviar para um segmento

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "code": "active_users",
      "payload": {
        "content": {
          "localized_content": {
            "en": {
              "ios":     { "body": "Hello!" },
              "android": { "body": "Hello!" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'

NotifyTransactional

Envia para uma lista explícita de destinatários.

Campo	Tipo	Descrição
schedule	Schedule	Obrigatório.
application	string	Código do Aplicativo.
platforms	array of Platform	Plataformas que a mensagem direciona.
test_devices	bool	Se true, envia apenas para os dispositivos de teste do aplicativo.
hwids	{ "list": [string, ...] }	Envia apenas para estes hwids.
users	{ "list": [string, ...] }	Envia apenas para estes IDs de usuário.
push_tokens	{ "list": [string, ...] }	Envia apenas para estes tokens de push.
payload	Payload	Payload de Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger.
email_payload	EmailPayload	Payload de e-mail.
return_unknown_identifiers	bool	Quando true, o unknown_identifiers da resposta lista os identificadores que não foram encontrados.
registration_type	RegistrationType	O que fazer com hwids que ainda não estão registrados no Pushwoosh. O padrão é REGISTRATION_TYPE_DEFAULT, que os ignora. Defina REGISTRATION_TYPE_FORCE para registrar novos endereços de e-mail ou números de telefone e enviar para eles na mesma solicitação.
use_latest_user_device	bool	Aplica-se apenas quando você direciona users. Mesmo comportamento que no NotifySegment acima — entrega uma mensagem por usuário em vez de uma por dispositivo, com escopo para platforms. O padrão é false.
campaign, campaign_name, frequency_capping, send_rate, silent_hours, message_type, dynamic_content_placeholders, meta_data		Veja NotifySegment acima.

test_devices, hwids, users e push_tokens são mutuamente exclusivos. Exatamente um deve ser definido.

Enviar para novos endereços de e-mail e números de telefone

Para e-mail, SMS, WhatsApp, LINE, Viber e Kakao, o hwid é o próprio destino, como o endereço de e-mail ou o número de telefone. Para enviar para um hwid que ainda não está registrado, inclua-o em hwids e defina registration_type como REGISTRATION_TYPE_FORCE. O Pushwoosh o registra e entrega a mensagem na mesma solicitação, então você não precisa fazer antes uma chamada separada a /registerDevice ou /registerEmail.

registration_type funciona apenas com hwids. Com users, um ID de usuário desconhecido não é criado, qualquer que seja o valor de registration_type.

Escreva cada hwid no mesmo formato que /registerDevice armazena para aquele canal:

Canal	Formato do hwid	Exemplo
E-mail	Endereço de e-mail	new.customer@example.com
SMS	Número de telefone em formato internacional	+14155552671
WhatsApp	Número de telefone com o prefixo whatsapp:	whatsapp:+14155552671
Kakao	Número de telefone com o prefixo kakao:	kakao:+821012345678
Viber	Número de telefone com o prefixo viber:. O Pushwoosh adiciona o prefixo se ele estiver faltando	viber:+14155552671
LINE	ID de usuário do LINE	U4af4980629a1b2c3d4e5f6a7b8c9d0e1

Mantenha os prefixos whatsapp: e kakao:. Sem eles, o número é lido como um hwid de SMS. Se esse número já estiver registrado para SMS, o envio encontra o hwid de SMS, que não corresponde à plataforma direcionada, e o destinatário é ignorado.

O Pushwoosh verifica números de telefone apenas com return_unknown_identifiers: true. Nesse caso, um hwid de SMS, WhatsApp ou Kakao que não seja um número de telefone válido não é registrado e volta em unknown_identifiers. Sem essa flag, o valor é registrado como está.

REGISTRATION_TYPE_FORCE não registra hwids em plataformas de push, Telegram ou Facebook Messenger, pois elas precisam de um token do SDK ou do mensageiro. Um hwid desconhecido nessas plataformas é descartado silenciosamente. Ele não volta em unknown_identifiers, e nada é enviado para ele.

Para o WhatsApp, registrar um número não abre a janela de atendimento ao cliente de 24 horas. Um número que não enviou mensagem para você pode receber apenas um template pré-aprovado definido em whatsapp.content_id, e não whatsapp.content de formato livre.

Exemplo: Enviar para um novo endereço de e-mail

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["EMAIL"],
      "hwids": { "list": ["new.customer@example.com"] },
      "registration_type": "REGISTRATION_TYPE_FORCE",
      "email_payload": {
        "subject": { "en": "Welcome aboard" },
        "body": "<p>Thanks for signing up!</p>"
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL",
      "return_unknown_identifiers": true
    }
  }'

Exemplo: Transacional por IDs de usuário

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "users": { "list": ["user-123", "user-456"] },
      "payload": {
        "content": {
          "localized_content": {
            "en": { "ios": { "body": "Your order has shipped." } }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL",
      "return_unknown_identifiers": true,
      "use_latest_user_device": true
    }
  }'

Resposta

{
  "result": {
    "message_code": "XXXXX-XXXXX-XXXXX",
    "unknown_identifiers": []
  }
}

Campo	Tipo	Descrição
message_code	string	Código da mensagem único. Use-o com /getMessageDetails e endpoints de estatísticas de mensagens.
unknown_identifiers	array of string	Identificadores não encontrados na conta. Preenchido apenas em um envio transactional com return_unknown_identifiers: true ou com direcionamento por push_tokens. Identificadores registrados por meio de REGISTRATION_TYPE_FORCE não são listados.

/getMessageDetails não encontra uma mensagem transactional enviada imediatamente para menos de 10 usuários e menos de 10 dispositivos, porque essa mensagem não é armazenada. Veja Mensagens enviadas imediatamente para menos de 10 destinatários.

Nenhum destinatário encontrado

Com return_unknown_identifiers: true ou direcionamento por push_tokens, o Pushwoosh procura cada destinatário antes de criar a mensagem. Se nenhum deles estiver registrado, o Notify retorna HTTP 400 com este erro, e nenhuma mensagem é criada:

{
  "code": 9,
  "message": "No recipients found",
  "details": [ ... ]
}

Se pelo menos um destinatário for encontrado, a solicitação é bem-sucedida e os demais são listados em unknown_identifiers. Para enviar para novos endereços de e-mail ou números de telefone, defina registration_type como REGISTRATION_TYPE_FORCE.

Para e-mail, endereços inválidos e endereços que tiveram bounce anteriormente são removidos antes dessa verificação, sem serem listados em unknown_identifiers. Se nenhum endereço restar depois disso, o Notify retorna 200 com um message_code, mas nenhuma mensagem é criada e nada é enviado.

Tipos compartilhados

Schedule

{
  "at": "2026-05-01T12:00:00Z",
  "follow_user_timezone": true,
  "past_timezones_behaviour": "PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY"
}

Campo	Tipo	Descrição
at	timestamp	Tempo de envio absoluto (RFC 3339). Máximo de 30 dias no futuro. Com follow_user_timezone não definido ou false, um at no passado é substituído pelo momento em que a solicitação foi recebida, então a mensagem é enviada imediatamente para todos. Com follow_user_timezone: true, um at no passado é mantido como está. Veja o aviso abaixo.
after	duration	Alternativa a at. Enviar após este deslocamento de “agora” (por exemplo, "3600s"). Máximo de 30 dias.
follow_user_timezone	bool	Quando true, cada dispositivo recebe a mensagem em at no seu fuso horário local.
past_timezones_behaviour	enum	PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY (padrão), PAST_TIMEZONES_BEHAVIOUR_DO_NOT_SEND ou PAST_TIMEZONES_BEHAVIOUR_NEXT_DAY. Apenas significativo quando follow_user_timezone é true ou best_time_to_send está definido.
best_time_to_send	timestamp	Opcional. Apenas para envios a segmentos. Cada dispositivo recebe a mensagem no seu próprio melhor horário dentro de 24 horas a partir deste momento. Dispositivos sem melhor horário a recebem na data e hora de at / after no seu fuso horário local. Consulte Melhor horário de envio.

Um horário de envio no passado não é instantâneo para todos com follow_user_timezone

Com follow_user_timezone: true, um at no passado não é movido para “agora”. Sua data e hora em UTC ainda são divididas em faixas de horário local por dispositivo. Os fusos em que esse horário local ainda está por vir recebem a mensagem nesse horário. Os fusos em que ele já passou seguem past_timezones_behaviour: enviada agora, ignorada (DO_NOT_SEND) ou adiada em um dia (NEXT_DAY) nesse mesmo horário local. A mesma divisão se aplica ao envio alternativo de best_time_to_send.

Melhor horário de envio

best_time_to_send é o equivalente na API da opção Melhor horário do Control Panel. at / after define o envio alternativo para dispositivos sem dados suficientes para um melhor horário. O Pushwoosh usa a data e hora UTC de at / after e entrega o envio alternativo nessa data e hora no fuso horário local de cada dispositivo, como com follow_user_timezone: true. Isso se aplica implicitamente: deixe follow_user_timezone sem definir, pois true é rejeitado com BestTimeToSendWithUserTimezone. No exemplo abaixo, os dispositivos sem melhor horário recebem a mensagem às 18:00, horário local, em 1º de maio. Onde esse horário local já tiver passado quando o envio começar, aplica-se past_timezones_behaviour.

{
  "at": "2026-05-01T18:00:00Z",
  "best_time_to_send": "2026-05-01T00:00:00Z"
}

O Pushwoosh rejeita a solicitação com 400, a menos que todas estas condições sejam atendidas:

• A solicitação usa o tipo segment. Envios transactional não suportam best_time_to_send.
• follow_user_timezone não está definido ou é false.
• O horário de envio de at / after está no futuro. Um at no passado, after: "0s" ou um after omitido contam como “enviar agora” e são rejeitados.
• best_time_to_send não é anterior à próxima hora cheia nem está a mais de 30 dias no futuro. Ele é arredondado para baixo até a hora cheia.
• O horário de envio de at / after não é posterior a best_time_to_send mais 24 horas.

O reason do erro (no detalhe ErrorInfo) indica a verificação que falhou:

reason	Causa
BestTimeToSendWithUserTimezone	follow_user_timezone é true.
BestTimeToSendTooEarly	best_time_to_send é anterior à próxima hora cheia.
BestTimeToSendTooFarInFuture	best_time_to_send está a mais de 30 dias no futuro.
SendDateAfterBestTimeToSend	at / after é posterior a best_time_to_send mais 24 horas.
BestTimeToSendNotAllowed	best_time_to_send está definido em um envio transactional.
BestTimeToSendWithSendNow	at / after resulta em “agora” (at no passado ou after igual a zero).

GeoZone

Um círculo avulso para geo_zone, definido na própria solicitação. Não é uma geozone salva: as campanhas geográficas e a Geozones API não estão envolvidas, e nada é armazenado no aplicativo.

{ "lat": 40.7128, "lng": -74.006, "range": 500 }

Campo	Tipo	Descrição
lat	double	Latitude do centro do círculo, em graus. Obrigatório.
lng	double	Longitude do centro do círculo, em graus. Obrigatório.
range	double	Raio do círculo em metros. Obrigatório.

Cuidado

A API não valida esses valores. Um campo omitido é lido como 0, e um lat / lng fora do intervalo ou um range igual a 0 não é rejeitado. Esse envio é aceito com um código de mensagem, mas corresponde a poucos ou nenhum dispositivo, em vez de retornar 400.

FrequencyCapping

Limites de frequência por usuário para envios de marketing. Para desativar o limite, omita frequency_capping completamente, ou envie days: 0 junto com count: 0.

{ "days": 7, "count": 3, "exclude": false, "avoid": true }

• days (int, 1–30, ou 0 para desativar o limite): janela de retrospectiva. Deve ser enviado junto com count — se um for 0, o outro também deve ser 0; enviar um como 0 enquanto o outro é diferente de zero retorna 400.
• count (int, 1 ou superior, ou 0 para desativar o limite): número máximo de mensagens permitidas dentro de days. Mesma regra de pareamento que days acima.
• exclude (bool): exclui permanentemente os usuários que já atingiram o limite.
• avoid (bool): evita suavemente os usuários que já atingiram o limite (eles ainda contam para as análises).

Importante

Enviar days e count com valores de zero incompatíveis (por exemplo, {"days": 0, "count": 5}) retorna 400. Esta validação é uma alteração que quebra a compatibilidade com Notify — clientes que anteriormente dependiam de um 0 solitário ser silenciosamente ignorado agora receberão um erro.

SendRate

{ "value": 500, "bucket": "1s", "avoid": false }

Controla a velocidade do envio. value é o número de mensagens por bucket; um bucket típico é "1s".

SilentHours

{ "avoid": true }

As mensagens de marketing seguem as horas de silêncio do aplicativo por padrão: durante o período de silêncio, elas são retidas até o fim dele ou não são enviadas, dependendo das configurações do canal. Defina avoid como true para enviar esta mensagem mesmo durante o período de silêncio. Mensagens com message_type MESSAGE_TYPE_TRANSACTIONAL nunca são retidas pelas horas de silêncio, portanto não precisam deste campo.

Enum Platform

IOS, ANDROID, OSX, WINDOWS, AMAZON, SAFARI, CHROME, FIREFOX, IE, EMAIL, HUAWEI_ANDROID, SMS, WEB, KAKAO, TELEGRAM, LINE, WHATS_APP, VIBER, FB_MESSENGER.

Enum RegistrationType

• REGISTRATION_TYPE_DEFAULT: ignora identificadores que não estão registrados no Pushwoosh. Padrão.
• REGISTRATION_TYPE_NONE: envia para cada hwid listado sem salvar um dispositivo para ele.
• REGISTRATION_TYPE_FORCE: registra cada hwid desconhecido como um dispositivo no canal direcionado e, em seguida, envia para ele. Aplica-se a e-mail, SMS, WhatsApp, LINE, Viber e Kakao.

Enum MessageType

• MESSAGE_TYPE_UNSPECIFIED: equivalente a MESSAGE_TYPE_MARKETING.
• MESSAGE_TYPE_MARKETING: sujeito à filtragem do grupo de controle, ao limite de frequência e às horas de silêncio.
• MESSAGE_TYPE_TRANSACTIONAL: ignora a filtragem do grupo de controle, o limite de frequência e as horas de silêncio. Use para confirmações de pedido, OTPs e fluxos críticos semelhantes.

Relacionados

Notify em lote

Cancel

Referência de Payload

Referência de payload de e-mail

Migração da v1