Notify

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

Cria e agenda uma única mensagem.

Estrutura da solicitação

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

segment: segmenta um público-alvo por código de segmento, 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.

{
  "segment": { ... }       // OR
  "transactional": { ... }
}

NotifySegment

Segmenta usuários que correspondem a um segmento de público ou expressão de filtro.

Campo	Tipo	Descrição
`schedule`	`Schedule`	Quando e como enviar. Obrigatório.
`application`	string	Código do aplicativo.
`platforms`	array de `Platform`	Plataformas que a mensagem segmenta.
`code`	string	Código do segmento. Mutuamente exclusivo com `expression` e `filter_expression`.
`expression`	string	Expressão Seglang.
`filter_expression`	`FilterExpression`	Expressão de filtro estruturada (avançado).
`payload`	`Payload`	Payload de Push / SMS / Telegram / Kakao. Mutuamente exclusivo com `email_payload`.
`email_payload`	`EmailPayload`	Payload de e-mail.
`campaign`	string	Código da campanha para atribuir esta mensagem.
`frequency_capping`	`FrequencyCapping`	Limites de frequência por usuário.
`send_rate`	`SendRate`	Controle de taxa para o envio.
`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.

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 de `Platform`	Plataformas que a mensagem segmenta.
`test_devices`	bool	Se `true`, envia apenas para os dispositivos de teste do aplicativo.
`hwids`	`{ "list": [string, ...] }`	Enviar apenas para estes hwids.
`users`	`{ "list": [string, ...] }`	Enviar apenas para estes IDs de usuário.
`push_tokens`	`{ "list": [string, ...] }`	Enviar apenas para estes tokens de push.
`payload`	`Payload`	Payload de Push / SMS / Telegram / Kakao.
`email_payload`	`EmailPayload`	Payload de e-mail.
`return_unknown_identifiers`	bool	Quando `true`, a lista `unknown_identifiers` da resposta contém os identificadores que não foram encontrados.
`campaign`, `frequency_capping`, `send_rate`, `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.

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
    }
  }'

Resposta

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

Campo	Tipo	Descrição
`message_code`	string	Código de mensagem exclusivo. Use-o com `/getMessageDetails` e endpoints de estatísticas de mensagens.
`unknown_identifiers`	array de string	Identificadores não encontrados na conta. Preenchido apenas quando `return_unknown_identifiers: true` foi definido no tipo `transactional`.

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	Horário de envio absoluto (RFC 3339). Se no passado, a mensagem é enviada imediatamente. Máximo de 14 dias no futuro.
`after`	duration	Alternativa para `at`. Enviar após este deslocamento de “agora” (por exemplo, `"3600s"`).
`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`. Significativo apenas quando `follow_user_timezone` é `true`.

FrequencyCapping

Limites de frequência por usuário para envios de marketing.

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

days (int, 1–30): janela de tempo retroativa.
count (int): máximo de mensagens permitidas dentro de days.
exclude (bool): excluir permanentemente usuários que já atingiram o limite.
avoid (bool): evitar de forma branda usuários que já atingiram o limite (eles ainda contam para as análises).

SendRate

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

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

Enum Platform

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

Enum MessageType

MESSAGE_TYPE_UNSPECIFIED: equivalente a MESSAGE_TYPE_MARKETING.
MESSAGE_TYPE_MARKETING: sujeito à filtragem de grupo de controle e ao limite de frequência.
MESSAGE_TYPE_TRANSACTIONAL: ignora a filtragem de grupo de controle e o limite de frequência. Use para confirmações de pedidos, OTPs e fluxos críticos semelhantes.

Relacionados

Referência de payload

Referência de payload de e-mail

Migração da v1