--- # Pushwoosh API overview **URL:** https://docs.pushwoosh.com/developer/api-reference/ Learn how to authenticate, send requests, and handle responses when working with the Pushwoosh API. --- The Pushwoosh API allows developers to interact with the Pushwoosh platform. ## What can you do with Pushwoosh API? With Pushwoosh API you gain access to an extensive library of over 100 methods enabling you to: * Send personalized push notifications * Create, import, export and manage user segments for precise targeting * Utilize bulk APIs to manage users/devices in batches * Configure applications * Track user events and add tags to users to enhance targeting and personalization * Create and manage Pushwoosh Entities such as presets, tags, events, applications, etc. * Start Pushwoosh Customer Journeys via API * Retrieve comprehensive statistics on Customer Journeys and Push/Email/SMS Campaigns. * Implement geofencing to send location-based notifications when users enter or exit specific geographic areas * Seamlessly integrate 3rd party services with Pushwoosh To explore the full range of available methods and discover the extensive capabilities of the Pushwoosh API, please refer to the [API methods reference index](https://docs.pushwoosh.com/developer/api-reference/api-methods-reference-index). ## Authentication The Pushwoosh API uses API tokens to authenticate requests. There are two types of tokens: [**Server**](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#server-api-token) and [**Device**](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token), each used for specific API scopes. Each Pushwoosh account comes with a default API Access Token created for the Pushwoosh Demo App. You can view, create, and manage your API tokens in the Pushwoosh Control Panel. [Learn more ](https://docs.pushwoosh.com/developer/api-reference/api-access-token/) ## Rate limits A rate limit is the number of requests the API can receive in a given period. While most API requests in Pushwoosh are not limited, [`/createMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api/#createmessage) and the equivalent [Messaging API v2 `Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) requests are capped at 600 per minute to ensure service quality for all users. ## Requests HTTPS is mandatory for all API requests ensuring secure data transfer. ## Responses Pushwoosh API typically returns JSON responses. ### Success and error codes #### Success codes When your API request is processed successfully, you will receive a success code as part of the response. | HTTP status code | Status message | Description | | ---------------- | -------------- | -------------------------------------------- | | 200 | OK | Pushwoosh successfully processed the request | Please note that when you get an HTTP 200 response, it means that your request was understood and processed successfully, but it doesn’t guarantee the action’s success. So make sure to check for error or warning messages (access denied, application not found, invalid API key, etc) to determine the action’s success. | Status code | Status message | | ----------- | --------------------------------------------------------------------------------------------------- | | 200 | Warnings: You have reached the subscriber limit. Push Message will be sent to 1 random device only | | 200 | Warnings: You have exceeded the number of active devices allowed on your current subscription plan. | | 210 | Access denied or application not found | | 210 | Application not found | | 210 | Application suspended | | 210 | Account not found | | 210 | Account has been suspended | | 210 | Suspended account can not use device filtration | | 210 | API token or application is not set | | 210 | Please select at least one platform | | 210 | Invalid API Token: Account not found | | 210 | No application or group code given | | 210 | API token or application or account is not set | #### Error codes In case your request isn’t correctly formatted, encounters processing issues, or experiences any other errors, Pushwoosh will send you an error code indicating the nature of the issue, helping you troubleshoot and address the problem effectively. | HTTP status code | Status message | Description | | ---------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | Bad request | The request can not be fulfilled due to bad syntax | | 401 | Unauthorized | Authentication has failed or hasn’t been provided | | 403 | Token restrictions forbid this operation. | Your access token lacks the necessary permissions to perform the requested action. To fix this, review your access token’s permissions in the Pushwoosh control panel and adjust them as needed to match the requirements for the specific operation you want to carry out. | | 404 | Resource not found | Indicates that the requested resource, such as an app, could not be located or does not exist on the server. | | 500 | Internal error | There was an unexpected issue or error on the server while processing the API request. | --- # API Access token **URL:** https://docs.pushwoosh.com/developer/api-reference/api-access-token/ Create and use API Access tokens in Pushwoosh to authenticate, manage projects, send messages, and access API features. --- API Access Token is a unique identifier assigned to a particular project or several projects in your account. It authenticates your account for managing your projects via the API, including account modifications, sending messages, editing projects, etc. ## API Access token types Pushwoosh provides two different API Access Token types: **Server** and **Device**. Each token type is only valid for its specific API scope. An authentication error will occur if the incorrect token is used. #### Server API token The Server API token is used with all API methods, except those under the Device API. It should be included in the request body in the `auth` field. #### Device API token The Device API token is used exclusively with Device API methods. It should be included in the HTTP request headers using the `Authorization` header. Below is an example of the correct header format: ```plaintext Authorization: Token ``` Replace `` with your actual Device API Token value. Methods requiring a Device API token The following API methods **require a Device API token** for authorization: * [`registerDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api/#registerdevice) * [`unregisterDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api/#unregisterdevice) * [`deleteDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api/#deletedevice) * [`setTags`](https://docs.pushwoosh.com/developer/api-reference/device-api/#settags) * [`getTags`](https://docs.pushwoosh.com/developer/api-reference/device-api/#gettags) * [`setBadge`](https://docs.pushwoosh.com/developer/api-reference/device-api/#setbadge) * [`applicationOpen`](https://docs.pushwoosh.com/developer/api-reference/device-api/#applicationopen) * [`pushStat`](https://docs.pushwoosh.com/developer/api-reference/device-api/#pushstat) * [`messageDeliveryEvent`](https://docs.pushwoosh.com/developer/api-reference/device-api/#messagedeliveryevent) * [`registerUser`](https://docs.pushwoosh.com/developer/api-reference/user-centric-api/#registeruser) * [`deleteUser`](https://docs.pushwoosh.com/developer/api-reference/user-centric-api/#deleteuser) * [`postEvent`](https://docs.pushwoosh.com/developer/api-reference/user-centric-api/#postevent) * [`registerEmail`](https://docs.pushwoosh.com/developer/api-reference/email-api/#registeremail) * [`deleteEmail`](https://docs.pushwoosh.com/developer/api-reference/email-api/#deleteemail) * [`setEmailTags`](https://docs.pushwoosh.com/developer/api-reference/email-api/#setemailtags) * [`registerEmailUser`](https://docs.pushwoosh.com/developer/api-reference/email-api/#registeremailuser) * [`getInboxMessages`](https://docs.pushwoosh.com/developer/api-reference/message-inbox/#getinboxmessages) * [`inboxStatus`](https://docs.pushwoosh.com/developer/api-reference/message-inbox/#inboxstatus) ## Create and manage API Access tokens You can view, create, and manage your API Access tokens in the **API Access** section of the Pushwoosh Control Panel. To access it, go to **Settings → API Access**. ![Pushwoosh Demo App token](https://docs.pushwoosh.com/api-reference-api-access-token-1.webp) By default, each account includes a token called **Pushwoosh Demo App**, which is set up as a server token. ### Create a new API Access token To create a new API Access token: 1. Go to the **API Access** section in the Control Panel. 2. Click **Generate New Token**. 3. In the window that appears, choose the token type: * [**Server**](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#server-api-token) used for most API methods (excluding Device API methods). * [**Device**](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) used for Device API methods only. 4. Enter a name for the token. 5. Click **Generate** to create the token. ![Generate a New Token](https://docs.pushwoosh.com/api-reference-api-access-token-4.webp) > **Important:** Be sure to give the token access to the right app in your Pushwoosh Control Panel. [Learn more](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#edit-token) The new token will appear in the API Access list. From there, you can copy its value for use in API requests or manage its access permissions as needed. ### Manage a token To manage an existing API token, click the **three-dot menu (⋮)** next to the token entry in the **API Access** section. ![Manage a token](https://docs.pushwoosh.com/api-reference-api-access-token-2.webp) The following options are available: #### Grant access to all projects Gives the token access to all projects in your account. This allows it to fully use the API across all projects. Tip Only give full access to tokens that need it. This helps keep your data secure and access controlled. #### Revoke access from all projects Removes the token’s access to all projects in your account. The token will no longer be able to use the API until access is given again. #### Edit token Opens the **Edit API Token Permissions** screen, where you can: * Change the token name * Copy the token value * Choose which projects the token can access by selecting or unselecting them in the list ![Manage a token](https://docs.pushwoosh.com/api-reference-api-access-token-3.webp) After you finish making changes, click **Save** to apply them. Tip Only give tokens access to the projects they need. This helps protect your account and control what each token can do. #### Delete token Permanently removes the token from your account. Caution This action cannot be undone. Once deleted, the token can’t be recovered. Make sure the token is no longer in use before deleting it. ## Authorizing API requests To authorize API requests, use the correct type of API Access token based on the type of API method you are calling: #### For Server API methods Include the token in the “auth” field of the request body: Example: ```json { "request": { "application": "XXXXX-XXXXX", "auth": "yxoPUlwqm…………pIyEX4H", // paste your server token here "notifications": [{ "send_date": "now", "content": "Hello world" }] } } ``` #### For Device API methods Use the **Device token**. Include it in the HTTP request header using the following format: ```plaintext Authorization: Token ``` Replace `` with your actual token value. Caution Make sure the token type matches the API method you are using. If the token does not match the required type, the request will return an authentication error. --- # Key API identifiers **URL:** https://docs.pushwoosh.com/developer/api-reference/api-identifiers/ Reference guide to all Pushwoosh API identifiers, including app codes, user IDs, tokens, tags, segments, events, and more. --- This post lists essential identifiers used in Pushwoosh API requests. These identifiers are required for authentication, message creation, targeting, segmentation, tracking, and managing users across your applications. ## General identifiers ### Application code A unique identifier assigned to each application in your Pushwoosh account. It is required in most API calls to specify the target app. **Where to find it** Pushwoosh Control Panel → Below the application name. ### API access token A unique token assigned to a Pushwoosh account, used to authenticate API requests. It enables access to manage projects, send messages, modify settings, and retrieve data. Each account has at least one token created by default. [Learn more](https://docs.pushwoosh.com/developer/api-reference/api-access-token/) **Where to find it** Pushwoosh Control Panel → API Access. ## Device identifiers ### Hardware ID A unique identifier assigned to a device by the Pushwoosh SDK. Automatically set by the SDK or passed during device registration. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) **Where to find it** * In device logs. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-knowledge-hub/device-identifiers/#how-to-obtain-hwid-and-push-token) * In [User Explorer](https://docs.pushwoosh.com/product/audience-data-and-segmentation/user-explorer/) when searching by **User ID** * In the CSV file downloaded from the [Segments list](https://docs.pushwoosh.com/product/audience-data-and-segmentation/segmentation/segments/) ### Push token A token issued by platform providers that identifies an app-device pair for delivering push notifications. Collected automatically by the SDK when push permissions are granted. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-knowledge-hub/device-identifiers/#push-token) **Where to find it** * In device logs. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-knowledge-hub/device-identifiers/#how-to-obtain-hwid-and-push-token) * In [User Explorer](https://docs.pushwoosh.com/product/audience-data-and-segmentation/user-explorer/), enter the HWID in the search field to find the associated device, then open the device details to view the push token. ### Device type Indicates the platform of the target device using a numeric code. Set automatically by the SDK. Supported values: ```plaintext 1 – iOS 3 – Android 7 – macOS 8 – Windows 9 – Amazon 10 – Safari 11 – Chrome 12 – Firefox 13 – Internet Explorer 14 – Email 16 – Baidu Android 17 – Huawei 18 – SMS 20 – Web 21 – WhatsApp 22 – Line 23 – Kakao Talk 24 – Telegram 25 – Apple Wallet 26 – Google Wallet 27 – Viber ``` ## User identifiers ### User ID A custom identifier assigned to a user, enabling cross-device and personalized targeting. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-knowledge-hub/users-userids/users-userids/) **Where to find it** Pushwoosh Control Panel → Audience → User Explorer ## Messaging identifiers ### Message code A unique identifier assigned to each message upon creation. It follows a specific format: **XXXX-XXXXXXXX-XXXXXXXX**. This code is essential for: * Tracking the status and delivery of a specific message * Canceling (or deleting) a previously sent message * Getting message statistics **Where to find it** * **Pushwoosh Control Panel:** Navigate to **Campaigns → One-time messages**, then open the **properties** of the desired message. The Message Code will be displayed there. * **[`/createMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api/#createmessage) API response:** When creating a new message via the API, the Message Code is included in the response. ### Request ID Correlates a message with the HTTP request that created it, letting you trace a single send end-to-end — from the HTTP call through Pushwoosh’s routing layer to the resulting message. Present on any message created by an HTTP call to [`/createMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api/#createmessage) or [Messaging API v2](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/), including messages sent from the Control Panel. Messages created by Journeys, cron sends, or other non-HTTP internal triggers have no Request ID. **Setting your own value** Pass an `X-Request-ID` header with the request. If the value is 8–128 characters long and contains only Latin letters, digits, dots, underscores, and hyphens, Pushwoosh reuses it; otherwise — or if the header is omitted — Pushwoosh generates one for you. An invalid value is replaced silently, so the request never fails because of it. Uniqueness isn’t enforced, so use a value that’s actually unique per request if you rely on it for tracing. **Where to find it** Pushwoosh Control Panel → open a message → **Message Details** → **Show all properties** → **Message settings** → **Request ID** (with a copy button). **Example**: `a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d` Note This is unrelated to the `request_id` field returned by asynchronous/bulk endpoints — [`/getResults`](https://docs.pushwoosh.com/developer/api-reference/scheduled-requests/) and the [Audience API](https://docs.pushwoosh.com/developer/api-reference/audience-api/) `bulk*` methods. That `request_id` is a job token you poll for a result; it has nothing to do with HTTP-level tracing. ### In-app code A unique code that identifies an [instant in-app](https://docs.pushwoosh.com/product/messaging-channels/in-apps/send-in-apps/send-instant-in-apps/) campaign. **Where to find it** Pushwoosh Control Panel → **Campaigns** → **Instant in-apps**. In the list, the code is displayed below the campaign name. **Example**: `AAAAA-BBBBB` ## Content identifiers ### Preset code An identifier for a saved message preset (for example, push or SMS). [Learn more](https://docs.pushwoosh.com/product/content/) **Where to find it** Pushwoosh Control Panel → Content → Presets. You can find the preset code in two places: * In the list view, displayed below the preset name. * In the URL when editing or creating a preset (it’s the last part of the URL). **Example**: URL: `https://app.pushwoosh.com/applications/XXXXX-XXXXX/sms-presets/edit/AAAAA-BBBBB` Preset code: `AAAAA-BBBBB` ### Rich media code Identifier for an in-app message template. [Learn more](https://docs.pushwoosh.com/product/content/in-apps/) **Where to find it** Pushwoosh Control Panel → Content → Rich media. **Example:** URL: `https://app.pushwoosh.com/applications/XXXXX-XXXXX/rich-media/AAAAA-BBBBB/statistics` Rich media code: `AAAAA-BBBBB` ### Email content code The email content code is a unique identifier for saved email content. [Learn more](https://docs.pushwoosh.com/product/content/email-content/) **Where to find it** Pushwoosh Control Panel → Content → Email content. The code is the last part of the URL. **Example**: URL: `https://app.pushwoosh.com/applications/XXXXX-XXXXX/email-content/edit/AAAAA-BBBBB` Email content code: `AAAAA-BBBBB` ## Campaign identifiers ### Campaign code A unique identifier used to reference a specific campaign for tracking, and analysis. **Where to find it** The campaign code appears in the URL when viewing campaign-related statistics in the Pushwoosh Control Panel. To locate it, go to **Statistics → Aggregated statistics**, click on the desired campaign, and copy the code found at the end of the URL. **Example:** **URL:** `https://app.pushwoosh.com/applications/XXXXX-XXXXX/statistics/aggregated-message?campaignCode=YYYYY-YYYYY` **Campaign code:** `YYYYY-YYYYY` ### Journey ID A unique identifier used to associate messages with specific marketing campaigns for tracking and performance analysis. **Where to find it** * In the URL of the campaign canvas in the Pushwoosh Control Panel. * Select a point on the canvas and press **Ctrl+I** (Cmd+I) — copies `/` to the clipboard; the Journey ID is the part before the slash. **Example:** URL: `https://app.pushwoosh.com/journeys/XXXXX-XXXXX/1/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee` Journey ID: `aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee` ## Segmentation and targeting identifiers ### Segment / Filter name The name of a predefined user segment created in Pushwoosh for audience targeting. [Learn more](https://docs.pushwoosh.com/product/audience-data-and-segmentation/segmentation/segments/) **Where to find it** Pushwoosh Control Panel → Segments. ### Segment / Filter code A unique code in the format XXXXX-XXXXX that identifies a segment (also called a filter) in Pushwoosh. This code is used in API calls, automation logic, and dynamic segmentation rules. **Where to find it** * Via the [`/listFilters`](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api/#listfilters) API method. * In the address bar when viewing a segment in the Pushwoosh Control Panel: **Example:** **URL:** `https://app.pushwoosh.com/applications/XXXXX-XXXXX/segments/XXXE9-XXX49/detail` **Segment code:** `XXXE9-XXX49` ### Tag A custom attribute assigned to users or devices. Used for dynamic segmentation and personalization. [Learn more](https://docs.pushwoosh.com/developer/guides/audience-and-segmentation/tags/) **Where to find it** Pushwoosh Control Panel → Tags or via [`/getTags`](https://docs.pushwoosh.com/developer/api-reference/device-api/#gettags) API. ## Event identifiers ### Event name The name of a tracked event (e.g., `purchase`, `login`, `subscription`). Used to trigger automated workflows or for analytics. [Learn more](https://docs.pushwoosh.com/developer/guides/audience-and-segmentation/events/) **Where to find it** Pushwoosh Control Panel → Audience → Events. ## Geolocation identifiers ### Geozone ID Identifies a geofenced area used to trigger location-based notifications. [Learn more](https://docs.pushwoosh.com/product/messaging-channels/push-notifications/geo-based-push/) **Where to find it** Pushwoosh Control Panel → Geozones. --- # API methods reference index **URL:** https://docs.pushwoosh.com/developer/api-reference/api-methods-reference-index/ Find the right API method for your needs from over 100 available methods organized by functionality and use case. --- Pushwoosh provides a vast library of over 100 API methods, categorized for various functionalities like sending notifications, managing users, and tracking analytics. ## Messaging API v2 Unified API that replaces the entire `/create*Message` family (push, email, SMS, Kakao). See the [overview](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/) and the [migration guide](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/migration-from-v1/). | | | | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) | Creates and sends a single message through any channel. Replaces `/createMessage`, `/createTargetedMessage`, `/createEmailMessage`, `/createSMSMessage`, `/createKakaoMessage`. | | [`Cancel`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/cancel/) | Cancels a previously created message before it is delivered. Use with `message_code` from [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/). | | [`Update`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/update/) | Replaces a still-scheduled message with a new definition (full replace). Use with `message_code` from [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/). | ## SMTP gateway Submit transactional email over standard SMTP instead of calling the API directly. The gateway authenticates with your application code and API token, then forwards each message to [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/). See the [SMTP gateway reference](https://docs.pushwoosh.com/developer/api-reference/smtp-gateway/). ## Messages API | | | | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | [`createMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api#createmessage) Deprecated | Creates a new push notification. Use [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) instead. | | [`deleteMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api#deletemessage) | Deletes a message (sent or scheduled) and removes it from Message History. | | [`getMessageDetails`](https://docs.pushwoosh.com/developer/api-reference/messages-api#getmessagedetails) | Retrieves the message details. | | [`createTargetedMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api#createtargetedmessage) Deprecated | Creates a new targeted push notification. Use [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) with `transactional` kind instead. | | [`getPushHistory`](https://docs.pushwoosh.com/developer/api-reference/messages-api#getpushhistory) Deprecated | Use [`/messages:list`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#messageslist) to retrieve message history with detailed data. | | [`cancelMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api#cancelmessage) | Cancels a scheduled message, keeping it in Message History. | ## Presets API | | | | ---------------------------------------------------------------------- | ---------------------------------------------------------- | | [`Create`](https://docs.pushwoosh.com/developer/api-reference/presets-api/#create) | Creates a new push preset. | | [`List`](https://docs.pushwoosh.com/developer/api-reference/presets-api/#list) | Lists an application’s push presets. | | [`Get`](https://docs.pushwoosh.com/developer/api-reference/presets-api/#get) | Retrieves a single push preset by code. | | [`Update`](https://docs.pushwoosh.com/developer/api-reference/presets-api/#update) | Overwrites a push preset by code. | | [`UpdatePartial`](https://docs.pushwoosh.com/developer/api-reference/presets-api/#updatepartial) | Updates only the supplied fields of a push preset by code. | | [`Clone`](https://docs.pushwoosh.com/developer/api-reference/presets-api/#clone) | Duplicates a push preset within the same application. | | [`Delete`](https://docs.pushwoosh.com/developer/api-reference/presets-api/#delete) | Deletes a push preset by code. | ## Device API | | | | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | [`registerDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api#registerdevice) | Registers a device for the application. | | [`unregisterDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api#unregisterdevice) | Removes the device’s push token. | | [`deleteDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api#deletedevice) | Deletes a device and all its associated data in the specified application. | | [`setTags`](https://docs.pushwoosh.com/developer/api-reference/device-api#settags) | Sets tag values for the device. | | [`getTags`](https://docs.pushwoosh.com/developer/api-reference/device-api#gettags) | Retrieves tags with their corresponding values for a specific device. | | [`setBadge`](https://docs.pushwoosh.com/developer/api-reference/device-api#setbadge) | Sends the current badge value for a device to Pushwoosh. | | [`applicationOpen`](https://docs.pushwoosh.com/developer/api-reference/device-api#applicationopen) | Registers an app open event. | | [`pushStat`](https://docs.pushwoosh.com/developer/api-reference/device-api#pushstat) | Registers a push open event. | | [`messageDeliveryEvent`](https://docs.pushwoosh.com/developer/api-reference/device-api#messagedeliveryevent) | Registers a push delivery event for the device. | ## Audience API | | | | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | [`bulkSetTags`](https://docs.pushwoosh.com/developer/api-reference/audience-api/#bulksettags) | Sets tag values for multiple devices. | | [`bulkSetTags Status`](https://docs.pushwoosh.com/developer/api-reference/audience-api/#bulksettags-status) | Returns the status of bulkSetTags operation. | | [`bulkRegisterDevice`](https://docs.pushwoosh.com/developer/api-reference/audience-api/#bulkregisterdevice) | Registers multiple devices in a single request, including optional tag values for each device. | | [`bulkRegisterDevice Status`](https://docs.pushwoosh.com/developer/api-reference/audience-api/#bulkregisterdevice-status) | Retrieves the status and results of a bulk device registration request using a request ID. | | [`bulkUnregisterDevice`](https://docs.pushwoosh.com/developer/api-reference/audience-api/#bulkunregisterdevice) | Unregisters multiple devices in a single request. | | [`bulkUnregisterDevice Status`](https://docs.pushwoosh.com/developer/api-reference/audience-api/#bulkunregisterdevice-status) | Retrieves the status and results of a bulk device unregistration request using a request ID. | ## Tags API | | | | ------------------------------------------------------ | ---------------------------------------------- | | [`addTag`](https://docs.pushwoosh.com/developer/api-reference/tags#addtag) | Creates a tag in your account. | | [`deleteTag`](https://docs.pushwoosh.com/developer/api-reference/tags#deletetag) | Removes a tag with all associated information. | | [`listTags`](https://docs.pushwoosh.com/developer/api-reference/tags#listtags) | Retrieves a list of tags on the account. | ## Segmentation (Filters) API | | | | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | [`createFilter`](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api#createfilter) | Creates a new segment. | | [`listFilters`](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api/#listfilters) | Returns a list of available segments with their conditions. | | [`deleteFilter`](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api#deletefilter) | Deletes an existing segment. | | [`exportSegment`](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api#exportsegment) | Schedules a request to export subscribers matching segment conditions. | | [`exportSegment Results`](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api#exportsegment-results) | Retrieves the CSV link for exportSegment results. | ## User-centric API | | | | ------------------------------------------------------------------------ | --------------------------------------------------------------------- | | [`registerUser`](https://docs.pushwoosh.com/developer/api-reference/user-centric-api#registeruser) | Associates external User ID with a specified device. | | [`deleteUser`](https://docs.pushwoosh.com/developer/api-reference/user-centric-api#deleteuser) | Deletes a user and all devices associated with the specified User ID. | | [`postEvent`](https://docs.pushwoosh.com/developer/api-reference/user-centric-api#postevent) | Calls the event within the app. | ## Events API | | | | ------------------------------------------------------------ | ----------------------------- | | [`createEvent`](https://docs.pushwoosh.com/developer/api-reference/events#createevent) | Creates an event for the app. | ## Applications API | | | | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [`createApplication`](https://docs.pushwoosh.com/developer/api-reference/applications#createapplication) | Creates a new application on the account. | | [`updateApplication`](https://docs.pushwoosh.com/developer/api-reference/applications#updateapplication) | Updates the application settings. | | [`deleteApplication`](https://docs.pushwoosh.com/developer/api-reference/applications#deleteapplication) | Deletes the app from the account. | | [`getApplication`](https://docs.pushwoosh.com/developer/api-reference/applications#getapplication) | Gets details about the app. | | [`getApplications`](https://docs.pushwoosh.com/developer/api-reference/applications#getapplications) | Retrieves a list of applications on the account. | | [`getApplicationFile`](https://docs.pushwoosh.com/developer/api-reference/applications#getapplicationfile) | Retrieves the configuration files related to the app. | | [`setApplicationPlatformStatus`](https://docs.pushwoosh.com/developer/api-reference/applications#setapplicationplatformstatus) | Changes the platform status of the app. | ## Campaigns API | | | | --------------------------------------------------------------------- | ------------------------------------------ | | [`createCampaign`](https://docs.pushwoosh.com/developer/api-reference/campaigns#createcampaign) | Creates a new push campaign. | | [`deleteCampaign`](https://docs.pushwoosh.com/developer/api-reference/campaigns#deletecampaign) | Deletes a particular campaign. | | [`getCampaigns`](https://docs.pushwoosh.com/developer/api-reference/campaigns#getcampaigns) | Retrieves a list of campaigns for the app. | ## App configuration API | | | | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [`configureApplication for iOS`](https://docs.pushwoosh.com/developer/api-reference/app-configuration#configureapplication-for-ios) | Configures the iOS platform for the app. | | [`configureApplication for Android`](https://docs.pushwoosh.com/developer/api-reference/app-configuration#configureapplication-for-android) | Configures the Android platform for the app. | | [`configureApplication for Mac OS X`](https://docs.pushwoosh.com/developer/api-reference/app-configuration#configureapplication-for-mac-os-x) | Configures the macOS platform for the app. | | [`configureApplication for Windows`](https://docs.pushwoosh.com/developer/api-reference/app-configuration#configureapplication-for-windows) | Configures the Windows platform for the app. | | [`configureApplication for Amazon`](https://docs.pushwoosh.com/developer/api-reference/app-configuration#configureapplication-for-amazon) | Configures the Amazon platform for the app. | | [`configureApplication for Chrome`](https://docs.pushwoosh.com/developer/api-reference/app-configuration#configureapplication-for-chrome) | Configures the Chrome platform for the app. | | [`configureApplication for Safari`](https://docs.pushwoosh.com/developer/api-reference/app-configuration#configureapplication-for-safari) | Configures the Safari platform for the app. | | [`configureApplication for Firefox`](https://docs.pushwoosh.com/developer/api-reference/app-configuration#configureapplication-for-firefox) | Configures the Firefox platform for the app. | | [`configureApplication for Email`](https://docs.pushwoosh.com/developer/api-reference/app-configuration#configureapplication-for-email) | Configures the Email platform for the app. | ## Email API | | | | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`createEmailMessage`](https://docs.pushwoosh.com/developer/api-reference/email-api#createemailmessage) Deprecated | Creates an email message. Use [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) with `platforms: ["EMAIL"]` and an [`email_payload`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/email-payload-reference/) instead. | | [`registerEmail`](https://docs.pushwoosh.com/developer/api-reference/email-api#registeremail) | Registers an email address for the app. | | [`deleteEmail`](https://docs.pushwoosh.com/developer/api-reference/email-api#deleteemail) | Removes an email address from your database. | | [`setEmailTags`](https://docs.pushwoosh.com/developer/api-reference/email-api#setemailtags) | Sets tag values for the specified email address. | | [`registerEmailUser`](https://docs.pushwoosh.com/developer/api-reference/email-api#registeremailuser) | Associates an external User ID with a specified email address. | ## Email Templates API | | | | ---------------------------------------------------------------- | ----------------------------------------------------------- | | [`Create`](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#create) | Creates a new email template in an application. | | [`List`](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#list) | Lists an application’s email templates. | | [`Get`](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#get) | Returns a single email template by code. | | [`Update`](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#update) | Updates an existing email template by code. | | [`Delete`](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#delete) | Deletes an email template and its connected preset by code. | | [`Clone`](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#clone) | Clones an email template into a destination application. | ## Test devices API | | | | ---------------------------------------------------------------------------- | ---------------------------------------------------------- | | [`createTestDevice`](https://docs.pushwoosh.com/developer/api-reference/test-devices#createtestdevice) | Registers a test device for the application. | | [`listTestDevices`](https://docs.pushwoosh.com/developer/api-reference/test-devices#listtestdevices) | Retrieves all test devices registered for the application. | ## Message inbox API | | | | ------------------------------------------------------------------------------ | ---------------------------------------------------------- | | [`getInboxMessages`](https://docs.pushwoosh.com/developer/api-reference/message-inbox/#getinboxmessages) | Retrieves the list of Inbox messages for a specified HWID. | | [`inboxStatus`](https://docs.pushwoosh.com/developer/api-reference/message-inbox#inboxstatus) | Updates the status of a specific Inbox message. | ## Statistics API ### Message statistics | | | | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | [`messages:list`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#messageslist) | Retrieves a list of sent messages. | | [`totalsByIntervals`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#totalsbyintervals) | Provides metrics and conversion data aggregated by hour. | | [`getDeliveryFunnel`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#getdeliveryfunnel) | Returns the delivery funnel for a single message, with a breakdown of where the audience is lost at each stage. | | [`getMessageLog`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#getmessagelog) | Retrieves detailed information about sent messages. | | [`linksInteractions`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#emailslinksinteractions) | Provides statistics on email link clicks. | | [`linksInteractionsDevices`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#emailslinksinteractionsdevices) | Lists users who clicked on links in emails. | | [`bouncedEmails`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#bouncedemails) | Provides information on email bounces, complaints, and bounce reasons. | ### Asynchronous message statistics export | | | | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | [`exportMessagesStatistics/export`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#export) | Queues a message history export to a CSV file, without the row limits of `messages:list`. | | [`exportMessagesStatistics/status`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#status) | Returns the progress of an export task. | | [`exportMessagesStatistics/result`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#result) | Returns the generated file name once the task has completed. | | [`exportMessagesStatistics/lastTasks`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#lasttasks) | Lists recent export tasks for an application. | | [`exportMessagesStatistics/delete`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#delete) | Deletes a task and its file before the retention window expires. | | [`exportMessagesStatistics/download`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#download) | Downloads the generated CSV file by name. | ### Application and subscriber statistics | | | | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | [`getApplicationSubscribersStats`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/application-subscriber-statistics/#getapplicationsubscribersstats) | Retrieves the app’s subscriber statistics, grouped by device type. | | [`getAppStats`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/application-subscriber-statistics/#getappstats) | Retrieves app statistics for a specific time period. | | [`getSubscribersStatistics`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/application-subscriber-statistics/#getsubscribersstatistics) | Retrieves subscriber statistics for a specific time period. | ### Campaign statistics | | | | ---------------------------------------------------------------------------------- | --------------------------------------------------------- | | [`getCampaignStats`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/campaign-statistics/) | Retrieves campaign statistics for a specific time period. | ### Events and tags statistics | | | | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | [`getEventStatistics`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/events-and-tags-statistics/#geteventstatistics) | Retrieves the number of times an event was triggered during a specific period. | | [`getTagStats`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/events-and-tags-statistics/#gettagstats) | Retrieves statistics for a specific tag. | ### In-app statistics | | | | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | [`inapps:totals`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/inapp-statistics/#inappstotals) | Retrieves impression, interaction and frequency capping totals for one or more in-app campaigns over a period. | | [`inapps:timeline`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/inapp-statistics/#inappstimeline) | Retrieves period totals and a time series of in-app metrics for a single campaign. | ## iOS Live Activities API | | | | ------------------------------------------------------------------------------------------- | -------------------------------------- | | [`startLiveActivity`](https://docs.pushwoosh.com/developer/api-reference/ios-live-activities-api#startliveactivity) | Creates a new iOS Live Activity. | | [`updateLiveActivity`](https://docs.pushwoosh.com/developer/api-reference/ios-live-activities-api#updateliveactivity) | Updates an existing iOS Live Activity. | ## Apple Wallet PassKit API | | | | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | [`Apple Wallet PassKit API`](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/) | Reference for managing Apple Wallet passes and related configuration in Pushwoosh. | ## Google Wallet API | | | | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | | [`Create a pass`](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#create-a-pass) | Creates the pass in Google Wallet and returns a save link. | | [`Validate a pass`](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#validate-a-pass) | Checks a pass configuration without creating it. | | [`Update a pass`](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#update-a-pass) | Updates an existing pass. Google delivers the change to saved devices. | | [`Get a save link`](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#get-a-save-link) | Returns an “Add to Google Wallet” save link for an existing pass. | | [`Get a pass`](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#get-a-pass) | Returns a single stored pass. | | [`List passes`](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#list-passes) | Returns a paginated list of passes for an application. | | [`Set pass state`](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#set-pass-state) | Activates or invalidates a pass. | | [`Delete a pass`](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#delete-a-pass) | Invalidates the pass in Google and removes its Pushwoosh record. | | [`Get configuration`](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#get-configuration) | Returns the Google Wallet configuration state for an application. | | [`Templates`](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#templates) | Lists pass templates or fetches one as a starting point. | ## Customer Journey API | | | | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | [`Lifecycle`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/lifecycle/) | Starts, pauses, finishes, drafts, or archives a journey by its UUID. | | [`Create and update`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/create-update/) | Creates a new journey definition or replaces an existing one. | | [`Start by API`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/start-by-api/) | Injects users into the API entry point of a running journey. | | [`Get Journey stats`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/statistics/) | Obtains stats for a specific journey by its ID. | | [`Remove users from journeys`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/drop-users/) | Removes one or more users from all or selected active journeys. | ## Scheduled requests API | | | | ---------------------------------------------------------------------- | -------------------------------------------- | | [`getResults`](https://docs.pushwoosh.com/developer/api-reference/scheduled-requests#getresults) | Retrieves the result of a scheduled request. | ## SMS API | | | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | | [`createSMSMessage`](https://docs.pushwoosh.com/developer/api-reference/sms#createsmsmessage) Deprecated | Creates a new SMS message. Use [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) with `platforms: ["SMS"]` instead. | ## WhatsApp API | | | | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | [`createWhatsAppMessage`](https://docs.pushwoosh.com/developer/api-reference/whatsapp#createwhatsappmessage) Deprecated | Creates a new WhatsApp message. Use [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) with `platforms: ["WHATS_APP"]` instead. | ## LINE API | | | | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | [`createLineMessage`](https://docs.pushwoosh.com/developer/api-reference/line-api/) Deprecated | Creates a new LINE message. Use [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) with `platforms: ["LINE"]` instead. | ## Kakao API | | | | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`createKakaoMessage`](https://docs.pushwoosh.com/developer/api-reference/kakao/#createkakaomessage) Deprecated | Sends a Kakao message using an approved template. Use [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) with `platforms: ["KAKAO"]` instead. | ## Geozones API | | | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | [`getNearestZone`](https://docs.pushwoosh.com/developer/api-reference/geozones#getnearestzone) | Retrieves the parameters of the nearest geozone and the distance to it. Also records the device location for geo push notifications. | | [`addGeoZone`](https://docs.pushwoosh.com/developer/api-reference/geozones#addgeozone) | Adds a Geozone to a specific app. | | [`updateGeoZone`](https://docs.pushwoosh.com/developer/api-reference/geozones#updategeozone) | Updates Geozone properties such as name, status, content, and range. | | [`deleteGeoZone`](https://docs.pushwoosh.com/developer/api-reference/geozones#deletegeozone) | Removes Geozones from the app. | | [`addGeoZoneCluster`](https://docs.pushwoosh.com/developer/api-reference/geozones#addgeozonecluster) | Adds a Geozone Cluster to the app. | | [`deleteGeoZoneCluster`](https://docs.pushwoosh.com/developer/api-reference/geozones#deletegeozonecluster) | Removes a Geozone Cluster from the app. | | [`listGeoZones`](https://docs.pushwoosh.com/developer/api-reference/geozones#listgeozones) | Retrieves a list of Geozones for the app. | | [`listGeoZoneClusters`](https://docs.pushwoosh.com/developer/api-reference/geozones#listgeozoneclusters) | Retrieves a list of Geozone clusters for the app. | --- # App configuration API **URL:** https://docs.pushwoosh.com/developer/api-reference/app-configuration/ Configure app platforms using API methods for iOS, Android, macOS, Amazon, Chrome, Safari, and Firefox push notification services. --- ## configureApplication for iOS Configures iOS platform for the app. `POST` `https://api.pushwoosh.com/json/1.3/configureApplication` #### Request Body | Name | Type | Description | | -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- | | auth | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel | | application | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | device_type | integer | Must be 1 for iOS | | ios_key_management_type | string | ”manual” | | ios_key_file | string | Base64-encoded iOS key file content | | ios_key_password | string | Password for iOS key file | | ios_gateway | integer | ”0” for sandbox, “1” for production | | ios_framework | string | Possible values: “native”, “cordova”, “titanium” | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "providers": { "ios": true, "amazon": false, "android": false, "baidu_android": false, "chrome": false, "email": false, "firefox": false, "huawei_android": false, "internet_explorer": false, "osx": false, "safari": false, "sms": false, "web": false, "whats_app": false, "windows": false } } } ``` Example ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX", // required. Pushwoosh application code "device_type": 1, // required. 1 for iOS "ios_key_management_type": "manual", // required. "manual" "ios_key_file": "MIIMY...BAQ==", // required. base64-encoded iOS key file content "ios_key_password": "password", // required. "ios_gateway": 1, // required. "0" (sandbox) | "1" (production) "ios_framework": "native" // required. possible values: "native", "cordova", "titanium", // "marmalade", "adobeAir", "corona", "xamarin", // "phoneGapBuild", "triggerIO", "unity" } } ``` ## configureApplication for Android Configures Android platform for the app. `POST` `https://api.pushwoosh.com/json/1.3/configureApplication` #### Request Body | Name | Type | Description | | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from your Pushwoosh Control Panel. | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | device_type* | integer | Must be 3 for Android. | | android_framework* | string | Android framework. Possible values: native, cordova, marmalade, adobeAir, corona, xamarin, phoneGapBuild, triggerIO, titanium, unity. | | android_fcm_service_account* | object | FCM service account key (JSON file generated in Firebase project settings). | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "providers": { "ios": false, "amazon": false, "android": true, "baidu_android": false, "chrome": false, "email": false, "firefox": false, "huawei_android": false, "internet_explorer": false, "osx": false, "safari": false, "sms": false, "web": false, "whats_app": false, "windows": false } } } ``` - Example ```json { "request": { "auth": "Z2PLR....IRwTqHwCr", "application": "87E33-XXXXX", "device_type": 3, "android_fcm_service_account": { "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "client_email": "****@foobar.iam.gserviceaccount.com", "client_id": "115********6584854983", "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/firebase-adminsdk-zffgu%40foobar.iam.gserviceaccount.com", "private_key": "-----BEGIN PRIVATE KEY-----\nuH/OU/fIL+i6Wm8as...\n-----END PRIVATE KEY-----\n", "private_key_id": "e3749********6d9", "project_id": "app-android", "token_uri": "https://oauth2.googleapis.com/token", "type": "service_account", "universe_domain": "googleapis.com" }, "android_framework": "native" } } ``` ## configureApplication for Mac OS X Configures Mac OS X platform for the app. `POST` `https://api.pushwoosh.com/json/1.3/configureApplication` #### Request Body | Name | Type | Description | | ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | device_type* | integer | Must be 7 for Mac OS X. | | macos_key_management_type* | string | Only “manual” type is available currently. | | macos_cert_file | string | Base64-encoded Mac OS X certificate file content. | | macos_key_file | string | Base64-encoded Mac OS X key file content. | | macos_key_password | string | Key file password. | | macos_gateway* | integer | Push gateway. “0” for sandbox, “1” for production. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "providers": { "ios": false, "amazon": false, "android": false, "baidu_android": false, "chrome": false, "email": false, "firefox": false, "huawei_android": false, "internet_explorer": false, "osx": true, "safari": false, "sms": false, "web": false, "whats_app": false, "windows": false } } } ``` Example ```json { "request":{ "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX", // required. Pushwoosh application code "device_type": 7, // required. 7 for Mac OS X "macos_key_management_type": "manual", // required. "manual" "macos_cert_file": "iVBORw0KGgoAAAANSUhEUgAABB…", // optional. Base64-encoded content of Mac OS X certificate file "macos_key_file": "iVBORw0KGgoAAAANSUhEUgAABB…", // optional. Base64-encoded content of Mac OS X key file "macos_key_password": "PASSWORD", // optional. Key file password "macos_gateway": 1 // required. push gateway. "0" for sandbox or "1" for production } } ``` ## configureApplication for Windows Configures Windows platforms for the app. `POST` `https://api.pushwoosh.com/json/1.3/configureApplication` #### Request Body | Name | Type | Description | | -------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | device_type* | integer | Must be 8 for Windows. | | wns_psid* | string | Package security identifier from Windows Store for the app. Starts with “ms-app://“. | | wns_secret* | string | Client Secret from Windows Store for the app. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "providers": { "ios": false, "amazon": false, "android": false, "baidu_android": false, "chrome": false, "email": false, "firefox": false, "huawei_android": false, "internet_explorer": false, "osx": false, "safari": false, "sms": false, "web": false, "whats_app": false, "windows": true } } } ``` Example ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX", // required. Pushwoosh application code "device_type": 8, // required. 8 for Windows "wns_psid": "ms-app://…", // required. package security identifier of the app from Windows Store "wns_secret": "CLIENT_SECRET" // required. Windows client secret } } ``` ## configureApplication for Amazon Configures Amazon platform for the app. `POST` `https://api.pushwoosh.com/json/1.3/configureApplication` #### Request Body | Name | Type | Description | | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | device_type* | integer | Must be 9 for Amazon. | | adm_cid* | string | Amazon client ID. | | adm_secret* | string | Amazon client secret. | | adm_framework* | string | Amazon framework. Possible values: *native, unity, adobeAir.* | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "providers": { "ios": false, "amazon": true, "android": false, "baidu_android": false, "chrome": false, "email": false, "firefox": false, "huawei_android": false, "internet_explorer": false, "osx": false, "safari": false, "sms": false, "web": false, "whats_app": false, "windows": false } } } ``` Example ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX", // required. Pushwoosh application code "device_type": 9, // required. 9 for Amazon "adm_cid": "CLIENT_ID", // required. Amazon client ID "adm_secret": "CLIENT_SECRET", // required. Amazon Client Secret "adm_framework": "native" // required. possible values: native, unity, adobeAir. } } ``` ## configureApplication for Chrome Configures Chrome platform for the app. `POST` `https://api.pushwoosh.com/json/1.3/configureApplication` #### Request Body | Name | Type | Description | Required | | ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- | -------- | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | Required | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | Required | | device_type* | integer | Must be 11 for Chrome. | Required | | chrome_fcm_service_account* | object | FCM service account key (JSON file generated in Firebase project settings). | Required | | chrome_vapid_key* | string | Public VAPID (Voluntary Application Server Identification) key used for push notification authentication in Chrome. | Required | | chrome_vapid_private_key* | string | Private VAPID key used for signing and sending push notifications in Chrome. | Required | ```json { "status_code": 200, "status_message": "OK", "response": { "providers": { "ios": false, "amazon": false, "android": false, "baidu_android": false, "chrome": true, "email": false, "firefox": false, "huawei_android": false, "internet_explorer": false, "osx": false, "safari": false, "sms": false, "web": false, "whats_app": false, "windows": false } } } ``` * Example ```json { "request": { "auth": "Z2PLR....IRwTqHwCr", "application": "87E33-XXXXX", "device_type": 11, "chrome_fcm_service_account": { "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "client_email": "****@foobar.iam.gserviceaccount.com", "client_id": "11529......6584854983", "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/****foobar.iam.gserviceaccount.com", "private_key": "-----BEGIN PRIVATE KEY-----\nuH/OU/fIm8as...\n-----END PRIVATE KEY-----\n", "private_key_id": "e3749......e66d9", "project_id": "app-chrome", "token_uri": "https://oauth2.googleapis.com/token", "type": "service_account", "universe_domain": "googleapis.com" }, "chrome_vapid_key": "BEr....KPqQvCbU", "chrome_vapid_private_key": "ee....flOqmSo" } } ``` ## configureApplication for Safari Configures Safari platform for the app. `POST` `https://api.pushwoosh.com/json/1.3/configureApplication` #### Request Body | Name | Type | Description | | ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | device_type* | integer | Must be 10 for Safari. | | safari_key_management_type* | string | Only “manual” type is available currently. | | safari_website_name | string | Website name. | | safari_allowed_domains | array | Ex: ”, ” | | safari_url_template* | string | Safari URL template formatted as “https://%@“. | | safari_icon_file | string | Base64-encoded content of 256x256px png file. | | safari_key_file* | string | Base64-encoded Safari .p12 key file content. | | safari_key_password | string | Password to the key file. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "providers": { "ios": false, "amazon": false, "android": false, "baidu_android": false, "chrome": false, "email": false, "firefox": false, "huawei_android": false, "internet_explorer": false, "osx": false, "safari": true, "sms": false, "web": false, "whats_app": false, "windows": false } } } ``` Example ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX", // required. Pushwoosh application code "device_type": 10, // required. 10 for Safari "safari_key_management_type": "manual", // required. "manual" "safari_website_name": "WEBSITE_NAME", // optional. "safari_allowed_domains": [ // optional. "https://site1.com", "https://site2.com" ], "safari_url_template": "https://%@", // required. "safari_icon_file": "iVBORw0KGgoAAAANSUhEUgAABB…", // optional. Base64-encoded content of 256x256px png file "safari_key_file": "MIIMY...BAQ==", // required. base64-encoded Safari .p12 key file content "safari_key_password": "PASSWORD" // optional. Password to the key file above } } ``` ## configureApplication for Firefox Configures Firefox platform for the app. `POST` `https://api.pushwoosh.com/json/1.3/configureApplication` #### Request Body | Name | Type | Description | Required | | -------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------- | -------- | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | Required | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | Required | | device_type* | integer | Must be 12 for Firefox. | Required | | firefox_is_enabled | boolean | Enables push notifications for Firefox. | Optional | | firefox_fcm_service_account* | object | JSON generated in Firebase project settings. | Required | | firefox_vapid_key* | string | Public VAPID (Voluntary Application Server Identification) key used for push notification authentication in Firefox. | Required | | firefox_vapid_private_key* | string | Private VAPID key used for signing and sending push notifications in Firefox. | Required | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "providers": { "ios": false, "amazon": false, "android": false, "baidu_android": false, "chrome": false, "email": false, "firefox": true, "huawei_android": false, "internet_explorer": false, "osx": false, "safari": false, "sms": false, "web": false, "whats_app": false, "windows": false } } } ``` - Example ```json { "request": { "auth": "Z2PLR....IRwTqHwCr", "application": "87E33-XXXXX", "device_type": 12, "firefox_fcm_service_account": { "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "client_email": "****@foobar.iam.gserviceaccount.com", "client_id": "115........6584854983", "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/****@foobar.iam.gserviceaccount.com", "private_key": "-----BEGIN PRIVATE KEY-----\n****uH/OU/fILL****fMJZ+i6****um8as.....\n-----END PRIVATE KEY-----\n", "private_key_id": "e3........8e66d9", "project_id": "app-firefox", "token_uri": "https://oauth2.googleapis.com/token", "type": "service_account", "universe_domain": "googleapis.com" }, "firefox_vapid_key": "BEr....KPqQvCbU", "firefox_vapid_private_key": "ee....flOqmSo" } } ``` ## configureApplication for Email Configures Email platform for the app. `POST` `https://api.pushwoosh.com/json/1.3/configureApplication` #### Request Body | Name | Type | Description | | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | device_type* | integer | Must be 14 for Email. | | email_from_email* | string | Sender email address. Should be valid and verified. | | email_from_name* | string | Sender name. | | email_reply* | string | Email address to reply to. Should be valid and verified. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "providers": { "ios": false, "amazon": false, "android": false, "baidu_android": false, "chrome": false, "email": true, "firefox": false, "huawei_android": false, "internet_explorer": false, "osx": false, "safari": false, "sms": false, "web": false, "whats_app": false, "windows": false } } } ``` Example ```json { "request":{ "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX", // required. Pushwoosh application code "device_type": 14, // required. 14 for email "email_from_email": "email@domain.com", // required. Email address should be valid and verified "email_from_name": "SENDER_NAME", // required. Name to display in the "From" email field "email_reply": "email@domain.com" // required. Email address to reply should be valid and verified } } ``` --- # Apple Wallet PassKit API **URL:** https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/ Create, update, and manage Apple Wallet passes (.pkpass) programmatically through the Pushwoosh PassKit Designer API. --- The PassKit Designer API lets you create, update, download, and manage [Apple Wallet passes](https://docs.pushwoosh.com/product/messaging-channels/apple-wallet-passes/) programmatically. It supports the same operations the pass builder in the Control Panel performs. Use it to issue loyalty cards, coupons, event tickets, boarding passes, and store cards, and to push live updates to passes already installed on your users’ devices. Prerequisite: PassKit certificate Before you can create passes for an application, an iOS PassKit signing certificate must be configured for that application. The certificate is managed in the Pushwoosh Control Panel. Without it, `create` and `update` requests fail. See [Apple Wallet pass configuration for iOS](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-wallet-pass-configuration/). ## Base URL ```plaintext https://apple-passkit.svc-nue.pushwoosh.com ``` All endpoints are served over HTTPS. Requests and responses use `application/json` unless noted otherwise. ## Authentication Every request must include an `Authorization` header with your [Pushwoosh API access token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/): ```plaintext Authorization: Token ``` The account that owns the token must own the application referenced by `applicationCode`. A request for an application that belongs to another account returns `403 Forbidden`. ## Conventions * **Field naming:** JSON fields use `lowerCamelCase` (for example, `passTypeIdentifier`, `serialNumber`, `backgroundColor`). * **Unpopulated fields:** responses include all fields, even when empty or zero-valued. * **Binary data:** `bytes` fields such as `pkpassData` and image `data` are Base64-encoded strings in JSON. * **Serial numbers:** the `serialNumber` is always assigned by the server when a pass is created. Any value you send on create is ignored; it identifies the pass for all later operations. ### Error responses The API maps internal status codes to HTTP status codes: | HTTP status | Meaning | | :------------------------ | :--------------------------------------------------------- | | `400 Bad Request` | Invalid argument—a required field is missing or malformed. | | `401 Unauthorized` | Missing or invalid `Authorization` header. | | `403 Forbidden` | The application does not belong to the caller’s account. | | `404 Not Found` | The pass, template, or application was not found. | | `503 Service Unavailable` | The service is at capacity or temporarily unavailable. | ## Endpoints | Method | Path | Description | | :------- | :---------------------------------------------------- | :------------------------------------------ | | `POST` | `/api/pass/validate` | Validate a pass configuration | | `POST` | `/api/pass/create` | Create a new `.pkpass` | | `POST` | `/api/pass/update/{serialNumber}` | Update an existing pass and notify devices | | `GET` | `/api/passes` | List all passes for an application | | `GET` | `/api/pass/{applicationCode}/{serialNumber}` | Get a single pass | | `GET` | `/api/pass/{applicationCode}/{serialNumber}/download` | Download the `.pkpass` of an existing pass | | `DELETE` | `/api/pass/{applicationCode}/{serialNumber}` | Delete a pass | | `GET` | `/api/pass/{serialNumber}/registrations` | List devices registered for a pass | | `GET` | `/api/config` | Get the application’s PassKit configuration | | `GET` | `/api/templates` | List available pass templates | | `GET` | `/api/templates/{filename}` | Get a single template | ## Create a pass Generates, signs, and stores a new pass, then returns its server-assigned serial number. `POST` `/api/pass/create` Tip To obtain the `.pkpass` file itself, call [Download a pass](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#download-a-pass) (or build an [install link / QR code](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#share-a-pass-as-a-qr-code)) with the returned serial. ### Request body | Parameter | Type | Required | Description | | :---------------- | :--------------- | :------- | :----------------------------------------------------------------------------------------------------- | | `pass` | object | Yes | The [pass object](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#pass-object) describing the pass. | | `images` | array of objects | No | [Pass images](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#pass-image-object) (icon, logo, etc.). `icon` and `logo` are required for a valid pass. | | `userId` | string | Yes | The Pushwoosh User ID the pass is issued to. | | `applicationCode` | string | Yes | The [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). | Note On create, if `teamIdentifier`, `passTypeIdentifier`, or `organizationName` are omitted, they default to the values from the application’s configured certificate. `formatVersion` defaults to `1`. The `serialNumber` is assigned server-side. ##### Request example ```json { "applicationCode": "XXXXX-XXXXX", "userId": "user-123", "pass": { "description": "Acme loyalty card", "logoText": "Acme", "backgroundColor": "rgb(60, 65, 76)", "foregroundColor": "rgb(255, 255, 255)", "labelColor": "rgb(255, 255, 255)", "storeCard": { "primaryFields": [ { "key": "balance", "label": "BALANCE", "value": "1200 pts" } ], "secondaryFields": [ { "key": "member", "label": "MEMBER", "value": "Jane Doe" } ] }, "barcodes": [ { "format": "PKBarcodeFormatQR", "message": "1234567890", "messageEncoding": "iso-8859-1" } ] }, "images": [ { "imageType": "icon", "data": "", "contentType": "image/png" }, { "imageType": "logo", "data": "", "contentType": "image/png" } ] } ``` ### Response | Field | Type | Description | | :------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `serialNumber` | string | Server-assigned unique identity of the created pass. Use it to fetch the pass ([Get a pass](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#get-a-pass)) or download the `.pkpass` ([Download a pass](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#download-a-pass)). | | `message` | string | Result message. | ##### Response example ```json { "serialNumber": "a1b2c3d4-1234-5678-9abc-def012345678", "message": "Pass created successfully" } ``` ## Validate a pass Checks a pass configuration against Apple’s specifications without creating a file. Useful before calling create. `POST` `/api/pass/validate` ### Request body | Parameter | Type | Required | Description | | :-------- | :----- | :------- | :------------------------------------------- | | `pass` | object | Yes | The [pass object](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#pass-object) to validate. | ### Response | Field | Type | Description | | :--------- | :--------------- | :------------------------------------ | | `valid` | boolean | Whether the pass passes validation. | | `errors` | array of strings | Blocking problems that must be fixed. | | `warnings` | array of strings | Non-blocking advisories. | ## Update a pass Regenerates the pass with new content, re-signs it, increments its update tag, and sends a **silent push notification** to every device that registered the pass. iOS then fetches and installs the updated version in the background. `POST` `/api/pass/update/{serialNumber}` ### Path parameters | Parameter | Type | Description | | :------------- | :----- | :---------------------------------------------------- | | `serialNumber` | string | The serial number returned when the pass was created. | ### Request body | Parameter | Type | Required | Description | | :---------------- | :----- | :------- | :--------------------------------------------------------- | | `updates` | object | Yes | The full [pass object](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#pass-object) with the new content. | | `applicationCode` | string | Yes | The Pushwoosh application code. | The `serialNumber` (from the path) and the pass’s authentication token are preserved by the server regardless of what you send. ### Response | Field | Type | Description | | :---------- | :------ | :--------------------------------- | | `success` | boolean | Whether the update succeeded. | | `updateTag` | integer | New update tag (a Unix timestamp). | | `message` | string | Result message. | ## List passes Returns a paginated, sorted list of the passes stored for an application. `GET` `/api/passes?applicationCode=XXXXX-XXXXX&page=0&perPage=20` ### Query parameters | Parameter | Type | Required | Description | | :---------------- | :------ | :------- | :------------------------------------------------------- | | `applicationCode` | string | Yes | The Pushwoosh application code. | | `orderBy` | string | No | Sort field: `UPDATED` (default) or `CREATED`. | | `orderDirection` | string | No | Sort direction: `DESC` (default, newest first) or `ASC`. | | `page` | integer | No | Zero-based page index. Defaults to `0`. | | `perPage` | integer | No | Page size. `0` or omitted uses the server default. | ### Response | Field | Type | Description | | :-------- | :--------------- | :----------------------------------------------------------- | | `passes` | array of objects | The current page of [pass records](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#pass-record-object). | | `page` | integer | The returned page index. | | `perPage` | integer | The page size used for this response. | | `total` | integer | Total number of passes for the application across all pages. | ##### Response example ```json { "passes": [ /* pass records */ ], "page": 0, "perPage": 20, "total": 137 } ``` ## Get a pass Returns a single stored pass, including its full pass object. `GET` `/api/pass/{applicationCode}/{serialNumber}` ### Path parameters | Parameter | Type | Description | | :---------------- | :----- | :------------------------------ | | `applicationCode` | string | The Pushwoosh application code. | | `serialNumber` | string | The pass serial number. | ### Response Returns `{ "pass": { ... } }`, a single [pass record](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#pass-record-object). ## Download a pass Returns the stored `.pkpass` file of an existing pass. `GET` `/api/pass/{applicationCode}/{serialNumber}/download` ### Response | Field | Type | Description | | :----------- | :-------------- | :------------------- | | `pkpassData` | string (Base64) | The `.pkpass` file. | | `filename` | string | Suggested file name. | ## Delete a pass Removes a pass record and its stored `.pkpass` file. `DELETE` `/api/pass/{applicationCode}/{serialNumber}` ### Response | Field | Type | Description | | :-------- | :------ | :---------------------------- | | `success` | boolean | Whether the pass was deleted. | | `message` | string | Result message. | ## Get pass registrations Lists the devices that have added the pass and are registered for updates. `GET` `/api/pass/{serialNumber}/registrations?applicationCode=XXXXX-XXXXX` ### Response Returns `{ "registrations": [ ... ] }`, where each item has: | Field | Type | Description | | :------------------------ | :----- | :---------------------------------- | | `deviceLibraryIdentifier` | string | Apple device library identifier. | | `pushToken` | string | The pass push token for the device. | ## Get configuration Returns the PassKit configuration resolved for an application from its certificate. `GET` `/api/config?applicationCode=XXXXX-XXXXX` ### Response | Field | Type | Description | | :------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------- | | `teamIdentifier` | string | Apple Team ID from the certificate. | | `passTypeIdentifier` | string | Pass Type ID from the certificate. | | `organizationName` | string | Organization name from the certificate. | | `hasCertificate` | boolean | Whether a certificate is configured. | | `webServiceUrl` | string | Base URL of the pass web service. Clients build an install link by appending `/v1/passes/{passType}/{serial}?token={authToken}`. | ## Templates List the available pass templates, or fetch one as a [pass object](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#pass-object) you can use as a starting point. `GET` `/api/templates` — returns `{ "templates": [ { "filename", "name", "description", "style" } ] }`. `GET` `/api/templates/{filename}` — returns `{ "template": { ...pass object... } }`. ## Share a pass as a QR code To let users add a pass by scanning a QR code (or tapping a link), encode the pass **install URL** into a QR code. The URL is built from values you already get back from the API: ```plaintext {webServiceUrl}/v1/passes/{passTypeIdentifier}/{serialNumber}?token={authenticationToken} ``` | URL part | Where to get it | | :-------------------- | :----------------------------------------------------------------------------- | | `webServiceUrl` | [`GET /api/config`](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#get-configuration) → `webServiceUrl` | | `passTypeIdentifier` | [pass record](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#pass-record-object) → `pass.passTypeIdentifier` (from list/get) | | `serialNumber` | [pass record](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#pass-record-object) → `serialNumber` | | `authenticationToken` | [pass record](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#pass-record-object) → `pass.authenticationToken` | Example: ```plaintext https://apple-passkit.svc-nue.pushwoosh.com/v1/passes/pass.com.acme.loyalty/a1b2c3d4-1234-5678-9abc-def012345678?token=AbC123XyZ ``` Render this URL as a QR code with any QR library. When a user scans it, their device opens the link, downloads the latest `.pkpass`, and Wallet prompts them to add it—which also registers the device for updates. ## Object reference ### Pass object | Field | Type | Description | | :------------------------------------------------------------------ | :----------- | :------------------------------------------------------------------------------------ | | `formatVersion` | integer | Pass format version. Defaults to `1`. | | `passTypeIdentifier` | string | Apple Pass Type ID (`pass.com.yourcompany.passtype`). Defaults from the certificate. | | `serialNumber` | string | Assigned by the server on create; identifies the pass. | | `teamIdentifier` | string | Apple Team ID. Defaults from the certificate. | | `organizationName` | string | Organization shown on the pass. Defaults from the certificate. | | `description` | string | Human-readable description (required by Apple). | | `boardingPass` / `coupon` / `eventTicket` / `storeCard` / `generic` | object | The pass style. **Exactly one** must be set. See [field groups](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#field-group-object). | | `backgroundColor` | string | Background color, `rgb(r, g, b)`. | | `foregroundColor` | string | Foreground (text) color, `rgb(r, g, b)`. | | `labelColor` | string | Field label color, `rgb(r, g, b)`. | | `logoText` | string | Text shown next to the logo. | | `suppressStripShine` | boolean | Disable the shine effect on the strip image. | | `barcodes` | array | [Barcodes](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#barcode-object) shown on the pass. | | `locations` | array | [Locations](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#location-object) that make the pass relevant. | | `beacons` | array | [Beacons](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#beacon-object) that make the pass relevant. | | `relevantDate` | string | ISO 8601 date when the pass becomes relevant. | | `maxDistance` | integer | Max distance (meters) for location relevance. | | `expirationDate` | string | ISO 8601 expiration date. | | `voided` | boolean | Marks the pass as void. | | `groupingIdentifier` | string | Groups related passes (event tickets/boarding passes). | | `userInfo` | object (map) | Arbitrary key/value app data. | Note `authenticationToken` and `webServiceUrl` are managed by the service and don’t need to be set by API clients. ### Field group object Each pass style (`boardingPass`, `coupon`, `eventTicket`, `storeCard`, `generic`) groups [fields](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#field-object) into areas: | Field | Type | Description | | :---------------- | :---- | :--------------------------------------------------------- | | `headerFields` | array | Shown in the pass header (visible when stacked in Wallet). | | `primaryFields` | array | Most prominent fields. | | `secondaryFields` | array | Below the primary fields. | | `auxiliaryFields` | array | Additional fields below secondary. | | `backFields` | array | Shown on the back of the pass. | `boardingPass` additionally has `transitType` (`PKTransitTypeAir`, `PKTransitTypeTrain`, `PKTransitTypeBus`, `PKTransitTypeBoat`, or `PKTransitTypeGeneric`). ### Field object | Field | Type | Description | | :------------------------ | :--------------- | :------------------------------------------------------------------ | | `key` | string | Unique field key within the pass. | | `label` | string | Field label. | | `value` | string | Field value (text or number as string). | | `changeMessage` | string | Message shown when the value changes (use `%@` as the placeholder). | | `textAlignment` | string | `PKTextAlignment` value. | | `dateStyle` / `timeStyle` | string | `PKDateStyle` for date/time formatting. | | `isRelative` | boolean | Show the date relative to now. | | `numberStyle` | string | `PKNumberStyle` for number formatting. | | `currencyCode` | string | ISO 4217 currency code. | | `dataDetectorTypes` | array of strings | Data detectors to apply to the value. | ### Barcode object | Field | Type | Description | | :---------------- | :----- | :------------------------------------------------------------------------------------------------- | | `format` | string | `PKBarcodeFormatQR`, `PKBarcodeFormatPDF417`, `PKBarcodeFormatAztec`, or `PKBarcodeFormatCode128`. | | `message` | string | Data encoded in the barcode. | | `messageEncoding` | string | Text encoding, typically `iso-8859-1`. | | `altText` | string | Text shown below the barcode. | ### Location object | Field | Type | Description | | :------------- | :----- | :------------------------------------------------ | | `latitude` | number | Latitude. | | `longitude` | number | Longitude. | | `altitude` | number | Altitude in meters. | | `relevantText` | string | Text shown on the lock screen near this location. | ### Beacon object | Field | Type | Description | | :-------------- | :------ | :---------------------------------------------- | | `proximityUuid` | string | iBeacon proximity UUID. | | `major` | integer | Major value. | | `minor` | integer | Minor value. | | `relevantText` | string | Text shown on the lock screen near this beacon. | ### Pass image object | Field | Type | Description | | :------------ | :-------------- | :--------------------------------------------------------------------------------------------------- | | `imageType` | string | One of `icon`, `logo`, `strip`, `background`, `footer`, `thumbnail`. `icon` and `logo` are required. | | `data` | string (Base64) | Image bytes. | | `contentType` | string | MIME type, for example `image/png`. | ### Pass record object Returned by list/get endpoints. | Field | Type | Description | | :------------------- | :------ | :------------------------------------------------- | | `serialNumber` | string | Pass serial number. | | `passTypeIdentifier` | string | Pass Type ID. | | `organizationName` | string | Organization name. | | `description` | string | Pass description. | | `createdAt` | string | Creation timestamp (RFC 3339). | | `updatedAt` | string | Last update timestamp (RFC 3339). | | `updateTag` | integer | Current update tag. | | `pass` | object | The full [pass object](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/#pass-object), for editing. | | `userId` | string | Pushwoosh User ID the pass was issued to. | --- # Applications API **URL:** https://docs.pushwoosh.com/developer/api-reference/applications/ Create, update, delete, and manage applications using API methods for app configuration and settings. --- ## createApplication `POST` `https://api.pushwoosh.com/json/1.3/createApplication` Creates a new application on the account. #### Request Body | Name | Type | Description | | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | authorize_all_tokens | boolean | Allows all API tokens to communicate with this app. | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | icon | string | Base64-encoded binary content of png file. | | sdk_ios | string | iOS SDK type. Possible values: “pw” or “corona”. For Corona, push payload is different. | | sdk_android | string | Android SDK type. Possible values: “pw”, “corona”, “phonegap”. AppPresser users select “phonegap”. | | title* | string | Title for the new app in Pushwoosh. | Example response: ```json { "status_code": 200, "status_message": "OK", "response": { "application": "1DC69-73EDB" } } ``` Example code: ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "icon": "iVBORw0KGgoAAAANSUhEUgAAA...", // optional. Base-64 encoded binary content of png file "authorize_all_tokens": true, // optional. If true, allows all api tokens to communicate with this app "sdk_ios": "pw", // optional. Possible values are "pw" or "corona" "sdk_android": "pw", // optional. Possible values are "pw", "corona", or "phonegap" "title": "APP_TITLE" // required. Title for the new app in Pushwoosh } } ``` ## updateApplication `POST` `https://api.pushwoosh.com/json/1.3/updateApplication` Updates the application settings. #### Request Body | Name | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | icon | string | Base64-encoded binary content of png file. | | sdk_ios | string | iOS SDK type. Possible values: “pw” or “corona”. For Corona, push payload is different. | | sdk_android | string | Android SDK type. Possible values: “pw”, “corona”, “phonegap”. AppPresser users select “phonegap”. | | title | string | New title for the app in Pushwoosh. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` Example ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX", // required. application code of the app you want to update "icon": "iVBORw0KGgoAAAANSUD6...", // optional. Base-64 encoded binary content of png file "sdk_ios": "pw", // optional. Possible values are "pw" or "corona" "sdk_android": "pw", // optional. Possible values are "pw", "corona", or "phonegap" "title": "APP_TITLE" // optional. New title for the app in Pushwoosh } } ``` ## deleteApplication `POST` `https://api.pushwoosh.com/json/1.3/deleteApplication` Deletes the app from the account. #### Request Body | Name | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` Example ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX" // required. Pushwoosh application code } } ``` ## getApplication `POST` `https://api.pushwoosh.com/json/1.3/getApplication` Gets details about the app. #### Request Body | Name | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "application": { "adm_cid": "", "adm_secret": "", "android_api_type": "x31", "android_gcm_api_key": "x7836363631366236353566366236353739", "android_sdk": "x7077", "icon_url": null, "ios_gateway": "x783330", "ios_key_management_type": "x783631373537343666", "ios_key_password": "x7836353336363236353335333736353333", "ios_sdk": "x7077", "title": "0 Application For test", "providers": { "ios": true, "amazon": false, "android": false, "baidu_android": false, "chrome": false, "email": false, "firefox": false, "huawei_android": false, "internet_explorer": false, "osx": false, "safari": false, "sms": false, "web": false, "whats_app": false, "windows": false }, "languages": { "en": "34", "zh": "12", "sv": "7", "de": "6", "pt": "6" } } } } ``` ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX" // required. Pushwoosh application code } } ``` ## getApplications `POST` `https://api.pushwoosh.com/json/1.3/getApplications` Gets the list of applications on the account. Can return result with pagination. #### Request Body | Name | Type | Description | | ------ | ------- | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | page | integer | The page number for pagination. | #### Example request ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "page": 2 // optional. The page number for pagination } } ``` #### Response If there are more than 100 applications in the account, the response includes `current page` and `total amount of pages`. #### Example Response ```json { "status_code": 200, "status_message": "OK", "response": { "page": 1, // Current page "total": 2, // Total amount of pages "applications": [{ "APPLICATION_CODE": "MyApp1" }, { "APPLICATION_CODE": "MyApp2" }] } } ``` ## getApplicationFile `POST` `https://api.pushwoosh.com/json/1.3/getApplicationFile` Gets the configuration files related to the app. #### Request Body | Name | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | file* | string | Identifier of the file to retrieve. See values below. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` Example ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX", // required. Pushwoosh application code "file": "ios_auto_privatekey" // required. identifier of the file to retrieve. See values below } } ``` #### Possible values for the “file” parameter: `“ios_auto_privatekey” | “ios_manual_privatekey” | “ios_auto_certificate” | “ios_manual_certificate” | “ios_push_certificate” | “ios_provisioning_profile” | “macos_manual_privatekey” | “macos_manual_certificate” | “macos_push_certificate” | “safari_manual_privatekey” | “safari_push_certificate” | “safari_push_package” | **Response example**: ```plaintext -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- -----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY----- ``` ## setApplicationPlatformStatus `POST` `https://api.pushwoosh.com/json/1.3/setApplicationPlatformStatus` Changes the platform’s status of the app. #### Request Body | Name | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | platform* | integer | The platform type. See platform types list below. | | status* | string | ”enable” or “disable” | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "message": "iOS pushes are disabled", "available_platforms": { "iOS": false, "Android": true, "OS X": false, "Windows": false, "Amazon": false, "Safari": false, "Chrome": true, "Firefox": false, } } } ``` Example ```json { "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "platform": 1, // required. 1 — iOS; 3 — Android; 7 — Mac OS X; 8 — Windows; // 9 — Amazon; 10 — Safari; 11 — Chrome; 12 — Firefox; "status": "disable" // required. "disable" or "enable" } } ``` --- # Audience API **URL:** https://docs.pushwoosh.com/developer/api-reference/audience-api/ Register and tag multiple devices in one request with the Audience API. Use request IDs to track registration and tag updates. --- Note The `request_id` used throughout this page is a job token for polling a `bulk*` operation’s status, unrelated to the message [Request ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#request-id) used for HTTP-level tracing. ## bulkSetTags `POST` `https://api.pushwoosh.com/api/v2/audience/bulkSetTags` Sets tag values for the list of devices. Important When using the `bulkSetTags` method, ensure that tag values are set for a minimum of 50 devices. To set tags for a single device, use the [`setTags`](https://docs.pushwoosh.com/developer/api-reference/device-api/#settags) method. #### Request Body | Name | Type | Description | | ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | application* | String | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | auth* | String | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | create_missing_tags | Boolean | If true, missing tags are created automatically. | | devices* | Object | Array of devices. | | devices.hwid | String | Can be used to identify a device instead of user_id or push_token. [Learn more](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) | | devices.user_id | String | Can be used to identify a user instead of hwid or push_token. [Learn more](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) | | devices.push_token | String | Can be used to identify a device instead of hwid or user_id. [Learn more](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#push-token) | | devices.list_operator | String | Defines how to set values for [tags](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#tag) of the list type: set, append, or remove | | devices.tags* | Object | Values to set for the tags specified. | * OK ```json { "request_id": "request_id to use in GET method to obtain job status", "status": "Pending" } ``` * Error ```json { "message": "invalid request" } ``` Request: ```json { "application": "application code", // required. Pushwoosh app code "auth": "Pushwoosh auth token", // required. API access token from Pushwoosh Control Panel "create_missing_tags": false, // optional. Should automatically create missing tags "devices": [{ // required. Array of devices "hwid": "device hwid", // optional. Can be used to identify a device instead of // "user_id" or "push_token". "user_id": "user ID", // optional. Can be used to identify a user instead of "hwid" or "push_token". "push_token": "device push token", // optional. Can be used to identify a device instead of "hwid" or "user_id". "list_operator": "set", // required. For list tags. Defines how to set values for // tags of the list type: set, append, or remove "tags": { // required. Values to set for the tags specified. "tag_name": "tagvalue", // use correct value type "tag_name2": "tagvalue2" } }] } ``` Response: ```json { "request_id": "request_id to use in GET method to obtain job status", "status": "Pending" } ``` ## bulkSetTags status `GET` `https://api.pushwoosh.com/api/v2/audience/bulkSetTags/{request_id}?detailed=false` Returns the status of `/bulkSetTags` operation #### Path Parameters | Name | Type | Description | | ----------- | ------ | -------------------------------------------- | | request_id | String | request id from previous `/bulkSetTags` call | #### Query Parameters | Name | Type | Description | | -------- | ------- | ------------------------------------------------------- | | detailed | Boolean | (true/false) whether to return detailed per-device info | Response: ```json { "request_id": "id of the request", "status": "Completed", // also "Pending", "Failed" "progress": 100, // jobs progress 0-100 "devices_success": 100, // good devices "devices_not_found": 0, // devices not found in Pushwoosh "devices_failed": 0, // errored "devices": [{ // device report (only in detailed = true) "hwid": "device hwid", "status": "done", // also "failed", "not found" "tags": { "tagName": "ok", "tagName2": "tag not found", "tagName3": "wrong value. expect :string" } }] } ``` ## bulkRegisterDevice Registers multiple devices in Pushwoosh in a single request. It also allows specifying various tags for each device. `POST` `https://api.pushwoosh.com/api/v2/audience/bulkRegisterDevice` ### Request body parameters | Parameter | Type | Required | Description | | :---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | application | string | Yes | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | auth | string | Yes | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token). | | devices | array | Yes | An array of device objects. Each object represents a device and its associated data. See details in the **Device object parameters** table below. | #### Device object parameters | Parameter | Type | Required | Description | | -------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | hwid | string | Yes | [The hardware ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) or unique identifier for the device. | | push_token | string | Yes | [Push token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#push-token) for the device. | | platform | integer | Yes | The platform identifier. [Learn more](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#platforms) | | list_operator | string | No | Determines the action for list-type tags: - **“append”**: Add the specified value to the tag list. - **“remove”**: Remove the specified value from the tag list. **Note**: If the `list_operator` parameter is not specified, all existing values in the tag list will be replaced with the provided values. | | tags | object | No | Custom [tags](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#tag) assigned to the device. Tags are key-value pairs used for segmentation. | #### Request example ```json { "application": "application code", // required. Pushwoosh app code "auth": "Pushwoosh auth token", // required. API access token from Pushwoosh Control Panel "devices": [{ // required. Array of devices "hwid": "device hwid", // required. Unique identifier for the device (can be an email). "push_token": "device push token", // required. Push notification token for the device. "platform": 14, // required. Device platform (e.g., 14 for email). "list_operator": "append", // optional. For list tags. Adds or removes the specified value(s) from the tag of list type. "tags": { // optional. Values to set for the specified tags. "language": "en", // use correct value type. "CSV_Import": "summer_camp" } }, { "hwid": "device hwid 2", // required. Unique identifier for the second device. "push_token": "device push token 2", // required. Push notification token for the device. "platform": 14, // required. Device platform. "list_operator": "remove", // optional. Adds or removes values from tags of the list type. "tags": { // optional. Values to remove from the specified tags. "language": "en", "CSV_Import": "summer_camp2" } }, { "hwid": "device hwid 3", // required. Unique identifier for the third device. "push_token": "device push token 3", // required. Push notification token for the device. "platform": 14, // required. Device platform. "tags": { // optional. Values to set for the specified tags. "language": "en", "CSV_Import": "summer_camp3" } }] } ``` ### Response The method responds with an operation ID, which can be used to track the status and results of the bulk registration process. ```json { "request_id": "request_id to use in GET method to obtain job status", "status": "Pending" } ``` ## bulkRegisterDevice status You can check the status of a bulk registration process by making the following **GET** request: `GET` `https://api.pushwoosh.com/api/v2/audience/bulkRegisterDevice/{request_id}?detailed=true` | Parameter | Type | Required | Description | | ----------- | ------- | -------- | ------------------------------------------------------------------------------------ | | request_id | string | Yes | The request ID returned by the POST request. | | detailed | boolean | No | If set to `true`, the response includes detailed results for each registered device. | #### Example response ```json { "request_id": "9a2e1a14-XXXX-46c3-XXXX-c254b25d3782", "status": "Completed", "progress": 100, "devices_success": 4, "devices": [ { "hwid": "user1@example.com", "status": "done" }, { "hwid": "user2@example.com", "status": "done" }, { "hwid": "user3@example.com", "status": "done" }, { "hwid": "invalid_email@example.com", "status": "failed" } ] } ``` ## bulkUnregisterDevice Unregisters multiple devices from Pushwoosh in a single request. `POST` `https://api.pushwoosh.com/api/v2/audience/bulkUnregisterDevice` ### Request body parameters | Parameter | Type | Required | Description | | :---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | application | string | Yes | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | auth | string | Yes | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) | | devices | array | Yes | An array of device objects. Each object represents a device and its associated data. See details in the **Device object parameters** table below. | #### Device object parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ | | hwid | string | Yes | The hardware ID or unique identifier for the device. [Learn more](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) | #### Request example ```json { "application": "application code", // required. Pushwoosh app code "auth": "Pushwoosh auth token", // required. API access token from Pushwoosh Control Panel "devices": [{ // required. Array of devices "hwid": "device hwid", // required. Unique identifier for the device (can be an email). }, { "hwid": "device hwid 2", // required. Unique identifier for the second device. }, { "hwid": "device hwid 3", // required. Unique identifier for the third device. }] } ``` ### Response The method responds with an operation ID, which can be used to track the status and results of the bulk process. ```json { "request_id": "request_id to use in GET method to obtain job status", "status": "Pending" } ``` ## bulkUnregisterDevice status You can check the status of a bulk un-registration process by making the following **GET** request: `GET` `https://api.pushwoosh.com/api/v2/audience/bulkUnregisterDevice/{request_id}?detailed=true` | Parameter | Type | Required | Description | | ----------- | ------- | -------- | -------------------------------------------------------------------------------------- | | request_id | string | Yes | The request ID returned by the POST request. | | detailed | boolean | No | If set to `true`, the response includes detailed results for each unregistered device. | #### Example response ```json { "request_id": "9a2e1a14-XXXX-46c3-XXXX-c254b25d3782", "status": "Completed", "progress": 100, "devices_success": 4, "devices": [ { "hwid": "user1@example.com", "status": "done" }, { "hwid": "user2@example.com", "status": "done" }, { "hwid": "user3@example.com", "status": "done" }, { "hwid": "invalid_email@example.com", "status": "failed" } ] } ``` --- # Campaigns API **URL:** https://docs.pushwoosh.com/developer/api-reference/campaigns/ Create and delete campaigns using API methods to organize and track push notification campaigns. --- ## createCampaign `POST` `https://api.pushwoosh.com/json/1.3/createCampaign` Creates a push campaign within the app. #### Request Body | Name | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | name* | string | Campaign name. | | description | string | Campaign description. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "campaign": "XXXXX-XXXXX" } } ``` ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX", // required. Pushwoosh application code "name": "CAMPAIGN_NAME", // required. "description": "CAMPAIGN_DESCRIPTION" // optional. } } ``` ## deleteCampaign `POST` `https://api.pushwoosh.com/json/1.3/deleteCampaign` Deletes a particular campaign. #### Request Body | Name | Type | Description | | ---------- | ------ | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | campaign* | string | [Code of a campaign](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#campaign-code) to delete. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` Example ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "campaign": "XXXXX-XXXXX" // required. ID of a campaign to delete } } ``` ## getCampaigns `POST` `https://api.pushwoosh.com/json/1.3/getCampaigns` Retrieves the list of campaigns for the app. #### Request Body | Name | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | cursor | string | Indicates the last campaign retrieved in the previous request. | | limit | integer | The max number of campaigns for a single response. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "campaigns": [{ "code": "7CFF3-63A7B", "name": "CAMPAIGN_NAME_1", "description": "DESCRIPTION1" }, { "code": "C284C-33DD3", "name": "CAMPAIGN_NAME_2", "description": "DESCRIPTION2" }], "limit": 100, "cursor": "+4PxJPhhwITD4PFsiKui1BA==" } } ``` Example ```json { "request": { "auth": "jLbec2UW........ztFSOf5Za", // required. API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX", // required. Pushwoosh application code "cursor": "+4PxJPhhwITD4PFsiKui1BA==", // optional. Indicates the last campaign retrieved in the previous request. "limit": 100 // optional. The max number of campaigns // for a single response. } } ``` --- # Customer Journey API overview **URL:** https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/ REST/JSON API to create, update, and manage Customer Journeys, trigger API entries, and read journey statistics. --- The Customer Journey API lets a backend manage [Customer Journeys](https://docs.pushwoosh.com/product/customer-journey/pushwoosh-journey-overview/) programmatically: create and edit journey definitions, move journeys through their lifecycle (start, pause, finish, draft, archive), trigger a running journey from your own systems, and pull per-journey statistics. It is the same API the Customer Journey builder uses, exposed over REST/JSON through a gRPC-Gateway bridge. ## Base URL The gRPC-Gateway methods and the legacy external methods are served on different hosts: | Methods | Base URL | | -------------------------------------------------------------------------- | ------------------------------------------- | | gRPC-Gateway: `/api/v3/journeygateway/...` (lifecycle, create, update) | `https://journey-api.svc-nue.pushwoosh.com` | | Legacy external: `/api/journey/...` (start by API, statistics, drop users) | `https://journey.pushwoosh.com` | Tip If you use a dedicated region or private deployment, confirm the exact base URLs with your Pushwoosh Customer Success Manager. ## Authentication Every request must include an `Authorization` header with a server-side Pushwoosh [API access token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#server-api-token): ```plaintext Authorization: Api YOUR_API_TOKEN ``` Note The token is bound to the account that owns it. All operations apply to that account. Use the same token you issue for other server-to-server API calls, and never expose it in client applications. ## Methods ### Manage journeys * [Lifecycle](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/lifecycle/): `POST /api/v3/journeygateway/{action}`. Start, pause, finish, draft, or archive a journey by its UUID. * [Create and update](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/create-update/): `POST /api/v3/journeygateway` and `PUT /api/v3/journeygateway/{uuid}`. Create a new journey definition or replace an existing one. ### Trigger journeys * [Start by API](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/start-by-api/): `POST /api/journey/{id}/start/external`. Inject users into the API entry point of a journey that is already running. ### Statistics and audience * [Get Journey stats](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/statistics/): `GET /api/journey/{id}/statistics/external`. Per-point delivery and conversion metrics. * [Remove users from journeys](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/drop-users/): `POST /api/journey/drop-users/external`. Drop users from all or selected active journeys. ### Reference * [Journey object](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/): the shape of the journey definition (info, params, points, comments) returned by the lifecycle, create, and update methods. * [Point reference](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/): the `point_data` structure for each point type: entry, timing, splitting, action, and messaging elements. ## Lifecycle start vs Start by API Customer Journey has two operations that sound similar but behave differently. [Lifecycle start](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/lifecycle/#endpoints) changes the journey state (for example, from Draft to **Running**). [Start by API](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/start-by-api/) injects users into an already-running journey. The table below compares them side by side. | | Lifecycle Start | Start by API | | ---------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------ | | Endpoint | `POST /api/v3/journeygateway/start` | `POST /api/journey/{id}/start/external` | | What it does | Activates the journey and moves it into the **Running** state | Injects users into the **API entry point** of an already-running journey | | Journey state required | Draft or Paused | Running (with an API Start point) | | Run frequency | Once per state change | Repeatedly, as users need to enter | ## Request and response format * Content type: `application/json`. * The `v3` field names use `snake_case`. Enum values are serialized as their string names (for example, `"STATUS_RUNNING"`, `"POINT_TYPE_SEND_PUSH"`). * The gRPC-Gateway methods (`/api/v3/journeygateway/...`) return the [journey object](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/) on success and the standard gRPC-Gateway error envelope on failure: `{ "code": ..., "message": ..., "details": [...] }`. * The legacy external methods (`/api/journey/...`) return a method-specific JSON body on success and `{ "success": false, "message": ... }` with HTTP `400` on validation errors. ## Quick start Start a journey ```bash curl -X POST https://journey-api.svc-nue.pushwoosh.com/api/v3/journeygateway/start \ -H "Authorization: Api YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "uuid": "11111111-2222-3333-4444-555555555555" }' ``` ## Next steps [Lifecycle ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/lifecycle/) [Create and update ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/create-update/) [Start by API ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/start-by-api/) [Get Journey stats ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/statistics/) [Remove users from journeys ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/drop-users/) [Journey object ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/) [Point reference ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/) --- # Create and update **URL:** https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/create-update/ Create a new Customer Journey definition or replace an existing one through the /api/v3/journeygateway endpoints. --- These endpoints create and edit the journey definition: its title, settings, and the points on the canvas. They do not start the journey. Use [Lifecycle](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/lifecycle/) for that. Both accept and return the [journey object](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/). Tip Writing a full journey graph in JSON is hard. Each point has its own channel fields and conditions ([Point reference](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/)). The most reliable workflow is to build the journey once in the [Customer Journey builder](https://docs.pushwoosh.com/product/customer-journey/pushwoosh-journey-overview/), read it back from a create/update response, then use these endpoints to clone or adjust it programmatically. ## Create `POST` `https://journey-api.svc-nue.pushwoosh.com/api/v3/journeygateway` Creates a new journey in the `STATUS_DRAFT` state. ### Request | Field | Required | Type | Description | | ---------- | -------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | `title` | Yes | string | Journey name. | | `params` | Yes | [`JourneyParams`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#journeyparams) | Journey-wide configuration. `params.application_code` is required. | | `points` | No | array of [`Point`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#point) | Journey elements on the canvas and their connections. | | `comments` | No | array of [`JourneyComment`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#journeycomment) | Canvas comments. | ##### Request example Create a journey ```bash curl -X POST https://journey-api.svc-nue.pushwoosh.com/api/v3/journeygateway \ -H "Authorization: Api YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Welcome series", "params": { "application_code": "XXXXX-XXXXX" }, "points": [], "comments": [] }' ``` ### Response Returns the new [journey object](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/). Read the journey’s UUID from `info.uuid` and use it for subsequent update and lifecycle calls. ##### Response example ```json { "info": { "uuid": "11111111-2222-3333-4444-555555555555", "title": "Welcome series", "status": "STATUS_DRAFT", "params": { "application_code": "XXXXX-XXXXX" } }, "points": [], "comments": [] } ``` ## Full journey example A complete `Create` body for a small welcome flow. The graph is: ```plaintext Start by segment ──default──▶ Send push ──default──▶ Wait 1 day ──default──▶ Boolean splitter ──output1──▶ Send email ──default──▶ Exit └──default───────────────────────────▶ Exit ``` Points are wired together through each output’s `info.next_point_uuid`. Note the [output keys](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#output-keys): every point uses `default`, except the boolean splitter, which adds `output1` for the matched-condition branch (`default` is its fallback). The exit point has no outputs. ```json { "title": "Welcome series", "params": { "application_code": "XXXXX-XXXXX", "user_id_track_change_policy": "TRACK" }, "points": [ { "uuid": "11111111-1111-1111-1111-111111111111", "title": "New signups", "point_type": "POINT_TYPE_START_BY_SEGMENT", "position": { "x": 80, "y": 200 }, "outputs": [ { "identity": { "key": "default", "order": 0 }, "info": { "title": "", "next_point_uuid": "22222222-2222-2222-2222-222222222222" } } ], "point_data": { "start_by_segment": { "application_code": "XXXXX-XXXXX", "filter_code": "AAAAA-BBBBB" } } }, { "uuid": "22222222-2222-2222-2222-222222222222", "title": "Welcome push", "point_type": "POINT_TYPE_SEND_PUSH", "position": { "x": 340, "y": 200 }, "outputs": [ { "identity": { "key": "default", "order": 0 }, "info": { "title": "", "next_point_uuid": "33333333-3333-3333-3333-333333333333" } } ], "point_data": { "send_push": { "application_code": "XXXXX-XXXXX", "title": "Welcome!", "content": "Thanks for joining — here's how to get started." } } }, { "uuid": "33333333-3333-3333-3333-333333333333", "title": "Wait 1 day", "point_type": "POINT_TYPE_WAIT", "position": { "x": 600, "y": 200 }, "outputs": [ { "identity": { "key": "default", "order": 0 }, "info": { "title": "", "next_point_uuid": "44444444-4444-4444-4444-444444444444" } } ], "point_data": { "delay": { "sec": 86400 } } }, { "uuid": "44444444-4444-4444-4444-444444444444", "title": "Opened the push?", "point_type": "POINT_TYPE_BOOLEAN_SPLITTER", "position": { "x": 860, "y": 200 }, "outputs": [ { "identity": { "key": "output1", "order": 1 }, "info": { "title": "Matched", "next_point_uuid": "55555555-5555-5555-5555-555555555555" } }, { "identity": { "key": "default", "order": 0 }, "info": { "title": "Everyone else", "next_point_uuid": "66666666-6666-6666-6666-666666666666" } } ], "point_data": { "boolean_splitter": { "split_strategy": "SPLIT_FILTER", "load_policy": "ALL", "filter_code": "CCCCC-DDDDD" } } }, { "uuid": "55555555-5555-5555-5555-555555555555", "title": "Follow-up email", "point_type": "POINT_TYPE_SEND_EMAIL", "position": { "x": 1120, "y": 120 }, "outputs": [ { "identity": { "key": "default", "order": 0 }, "info": { "title": "", "next_point_uuid": "66666666-6666-6666-6666-666666666666" } } ], "point_data": { "send_email": { "application_code": "XXXXX-XXXXX", "preset_code": "12345-67890" } } }, { "uuid": "66666666-6666-6666-6666-666666666666", "title": "Exit", "point_type": "POINT_TYPE_EXIT", "position": { "x": 1380, "y": 200 }, "outputs": [], "point_data": { "terminator": {} } } ], "comments": [] } ``` ## Update `PUT` `https://journey-api.svc-nue.pushwoosh.com/api/v3/journeygateway/{uuid}` Replaces the definition of an existing journey. Send the **complete** definition. The points and comments you submit replace the current ones. ### Path parameters | Name | Type | Description | | ------ | ------ | ----------------------------------------------------------------------------- | | `uuid` | string | [Journey ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#journey-id) to update. | ### Request | Field | Type | Description | | ---------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `title` | string | New journey name. | | `params` | [`JourneyParams`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#journeyparams) | New journey-wide configuration. | | `points` | array of [`Point`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#point) | New full set of points. | | `comments` | array of [`JourneyComment`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#journeycomment) | New full set of comments. | | `autosave` | bool | When `true`, the change is treated as an editor autosave. Defaults to `false`. | ##### Request example Rename and reconfigure a journey ```bash curl -X PUT https://journey-api.svc-nue.pushwoosh.com/api/v3/journeygateway/11111111-2222-3333-4444-555555555555 \ -H "Authorization: Api YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Welcome series v2", "params": { "application_code": "XXXXX-XXXXX" }, "points": [], "comments": [] }' ``` ### Response Returns the updated [journey object](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/). ## Update and resume `POST` `https://journey-api.svc-nue.pushwoosh.com/api/v3/journeygateway/{uuid}/resume` Applies edits to a journey and resumes it in a single call. This is the equivalent of an [Update](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/create-update/#update) followed by a lifecycle [Start](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/lifecycle/). The request body matches [Update](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/create-update/#update). Use this when editing a paused journey you want to put back into the `STATUS_RUNNING` state. ## Rename `POST` `https://journey-api.svc-nue.pushwoosh.com/api/v3/journeygateway/{uuid}/rename` Changes only the journey title, without touching its points or settings. | Field | Required | Type | Description | | ------- | -------- | ------ | ----------------- | | `title` | Yes | string | New journey name. | ##### Request example Rename a journey ```bash curl -X POST https://journey-api.svc-nue.pushwoosh.com/api/v3/journeygateway/11111111-2222-3333-4444-555555555555/rename \ -H "Authorization: Api YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Welcome series (Q3)" }' ``` ## Related [Journey object ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/) [Lifecycle ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/lifecycle/) [Start by API ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/start-by-api/) --- # Remove users from journeys **URL:** https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/drop-users/ Remove a list of users from all or specific active Customer Journeys. --- `POST` `https://journey.pushwoosh.com/api/journey/drop-users/external` Removes a list of users from all or specific active journeys. ## Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------------------ | -------------------------------------------------------------------------------- | | Content-Type | Yes | `application/json` | | | Authorization | Yes | `Api ` | [Server API token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#server-api-token). | ## Request body | Field | Required | Type | Description | | --------------- | ----------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------- | | `user_ids` | Yes | `string[]` | List of [User IDs](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) to remove from journeys. | | `journey_uuids` | Required if `all_journeys` is not provided or `false` | `string[]` | List of [Journey IDs](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#journey-id) to remove users from. | | `all_journeys` | Required if `journey_uuids` is not provided | `boolean` | If `true`, users are removed from all journeys. If `false`, `journey_uuids` must be provided. | Note At least one of `all_journeys` (set to `true`) or `journey_uuids` (non-empty array) must be provided. ### Request examples #### Remove users from all journeys ```json { "user_ids": ["user1", "user2", "user3"], "all_journeys": true } ``` #### Remove users from specific journeys ```json { "user_ids": ["user1", "user2"], "journey_uuids": ["journey-uuid-1", "journey-uuid-2"] } ``` ### Response example * 200 ```json { "success": true } ``` * 400 If the request is invalid, the API returns HTTP `400` with a descriptive `message`. ```json { "success": false, "message": "user_ids must be provided" } ``` ```json { "success": false, "message": "journey_uuids must be provided if all_journeys is false" } ``` ## Related [Get Journey stats ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/statistics/) [Start by API ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/start-by-api/) [Lifecycle ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/lifecycle/) --- # Journey object **URL:** https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/ Reference for info, params, points, and comments in the Customer Journey definition, as returned and accepted by v3 endpoints. --- The [lifecycle](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/lifecycle/), [create, and update](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/create-update/) methods all return a journey object with the same top-level shape: Shape ```json { "info": { ... }, // read-only metadata (responses only) "params": { ... }, // journey-wide configuration (create / update) "points": [ ... ], // canvas nodes and their connections "comments": [ ... ] // canvas comments } ``` When you **create** or **update** a journey you send `title`, `params`, `points`, and `comments`. Responses return `info` (which contains `params`) plus `points` and `comments`. ## Info Read-only journey metadata. Returned by every v3 method. Not part of the request body. | Field | Type | Description | | -------------------- | -------------------------------------- | ------------------------------------------------------------------- | | `uuid` | string | [Journey ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#journey-id). | | `title` | string | Journey name. | | `status` | [`JourneyStatus`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#journeystatus-enum) | Current state. | | `created_at` | string | Creation timestamp (ISO 8601). | | `updated_at` | string | Last update timestamp (ISO 8601). | | `is_first_activated` | bool | Whether the journey has been started at least once. | | `params` | [`JourneyParams`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#journeyparams) | Journey-wide configuration. | | `category_uuid` | string | UUID of the category, or empty if uncategorized. | | `pointCounts` | map | Count of points by type. | | `campaign_type` | [`CampaignType`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#campaigntype-enum) | How users enter the journey. | | `stop_reason` | string | Why the journey stopped, if applicable. | | `last_edited_by` | `User` | User who last edited the journey. | | `dynamic_entry` | bool | Whether dynamic entry is enabled. | ## JourneyParams Journey-wide configuration. Sent on create/update and returned inside `info.params`. | Field | Type | Description | | ----------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `application_code` | string | [Application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) the journey belongs to. Required on create. | | `silent_hours` | [`SilentHours`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#silenthours) | Hours during which messages are suppressed, per channel. | | `capping` | [`EntryCapping`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#entrycapping) | Limits on how often a user can re-enter the journey. | | `conversion_window` | [`ConversionWindow`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#conversionwindow) | Window for attributing goal conversions. | | `user_id_track_change_policy` | [`UserIDTrackChangePolicy`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#useridtrackchangepolicy-enum) | How to handle a user’s ID changing mid-journey. | ### SilentHours Suppresses sending during quiet hours. Configured **per channel**: each channel takes its own `SilentHoursParams`: | Field | Type | Description | | ----------------- | ------------------- | ------------------------------------ | | `push_params` | `SilentHoursParams` | Silent hours for push notifications. | | `inapp_params` | `SilentHoursParams` | Silent hours for in-app messages. | | `email_params` | `SilentHoursParams` | Silent hours for emails. | | `sms_params` | `SilentHoursParams` | Silent hours for SMS. | | `whatsapp_params` | `SilentHoursParams` | Silent hours for WhatsApp. | | `line_params` | `SilentHoursParams` | Silent hours for LINE. | Each `SilentHoursParams` is: | Field | Type | Description | | ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | bool | Whether silent hours apply to this channel. | | `from_time` | `Time` | Start of the quiet window: `{ "hour": 0–23, "minute": 0–59 }`. | | `to_time` | `Time` | End of the quiet window. | | `week_days` | bool[] | Seven booleans for the days the window applies (Monday = index 0). | | `behavior` | enum | What to do when a message falls inside silent hours: `WaitAndSend` (hold, then send when the window ends), `DropAndGo` (skip the message, continue the journey immediately), or `WaitAndDrop` (wait out the window, then continue without sending). | ### EntryCapping Limits how often the same user can enter the journey. | Field | Type | Description | | ------------ | ------ | --------------------------------------------------- | | `is_enabled` | bool | Whether entry capping is on. | | `period` | uint64 | Minimum number of seconds between a user’s entries. | ### ConversionWindow | Field | Type | Description | | --------- | ------ | ---------------------------------------------------------------------------------------- | | `seconds` | uint64 | How long after entering a journey a user’s goal completion still counts as a conversion. | ## Point A point is a node on the journey canvas: an entry point, a message, a delay, a splitter, and so on. | Field | Type | Description | | ------------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uuid` | string | Unique ID of the point within the journey. Must be a canonical [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122) UUID: 32 hex digits in 8-4-4-4-12 groups. | | `title` | string | Display name of the point. | | `point_type` | [`PointType`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#pointtype-enum) | The kind of node. | | `outputs` | array of [`PointOutput`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#pointoutput) | Connections to downstream points. | | `position` | [`Position`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#position) | Canvas coordinates. | | `point_data` | object | Exactly one nested key, matching `point_type` (see the [point types](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#point-types-and-point_data) table). | Note All UUIDs (`info.uuid`, every point `uuid`, and each output’s `next_point_uuid`) must be canonical RFC 4122 UUIDs (8-4-4-4-12 hex groups). ### PointOutput A point’s outputs are its outgoing branches. Their keys are **not free-form**. The validator expects an exact set of keys for each point type, and rejects a journey whose point has the wrong number of outputs or a key it does not recognize. | Field | Type | Description | | ---------------------- | ------ | ------------------------------------------------------------------- | | `identity.key` | string | Branch key. Must follow the [output key rules](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#output-keys) below. | | `identity.order` | int | Display order of the branch. | | `info.title` | string | Optional branch label. | | `info.next_point_uuid` | string | UUID of the next point this branch connects to. | #### Output keys The default (first) branch is always named `"default"`. Additional branches are named `"output1"`, `"output2"`, … (the prefix `output` followed by a 1-based index). Two point types break this rule, noted below. | Point type | Expected output keys | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | Entry points (`START_BY_SEGMENT`, `START_BY_API`, `EVENT`), `INAPP`, `SET_TAGS`, `WEBHOOK`, `AUDIENCE_SYNC`, and message points with no splitter (`SEND_PUSH`, `SEND_EMAIL`, `SEND_SMS`, `SEND_WHATSAPP`, `SEND_LINE`, `SEND_KAKAO`, `SEND_TELEGRAM`, `SEND_DATA`) | `default` | | `GOAL_EVENT`, `EXIT` | none (no outputs) | | `FILTER` | `default`, `output1` | | `BOOLEAN_SPLITTER` | `default`, then `output1` … `outputN` (one extra branch per condition. A simple yes/no split is `default` + `output1`) | | `WAIT` (delay) | `default`. A dynamic delay with branch splitting adds `output1` | | `WAIT_EVENT` | `default` is the **event-not-triggered** branch. `output1` (or, with a conditions script, one branch per condition) is the triggered path | | `SEND_PUSH` with a splitter | `default`, `output1` (and `output2` when both the message and delivery splitters are on) | | `SEND_EMAIL` / `SEND_SMS` / `SEND_LINE` / `SEND_WHATSAPP` with a splitter | `default`, `output1` | | `SEND_WHATSAPP` with a quick-reply preset | `default`, plus one branch per quick reply. The key is the quick-reply value itself | | `AB_SPLITTER` | `output0`, `output1`, `output2`, … (one per variant. **There is no `default` branch**) | ### Position | Field | Type | Description | | ----- | ----- | ------------------------------------ | | `x` | float | Horizontal coordinate on the canvas. | | `y` | float | Vertical coordinate on the canvas. | ## Point types and point_data `point_data` is a one-of: it carries exactly one nested object whose key is determined by the point’s `point_type`. | `point_type` | `point_data` key | Purpose | | ----------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- | | `POINT_TYPE_START_BY_SEGMENT` | `start_by_segment` | Entry: users matching a segment. | | `POINT_TYPE_EVENT` | `message_bus` | Entry: users triggering an event. | | `POINT_TYPE_START_BY_API` | `start_by_api` | Entry: users injected via the [Start by API](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/start-by-api/) call. | | `POINT_TYPE_WAIT` | `delay` | Wait for a fixed or dynamic interval. | | `POINT_TYPE_WAIT_EVENT` | `wait_event` | Wait until an event happens. | | `POINT_TYPE_SEND_PUSH` | `send_push` | Send a push notification. | | `POINT_TYPE_SEND_EMAIL` | `send_email` | Send an email. | | `POINT_TYPE_SEND_SMS` | `send_sms` | Send an SMS. | | `POINT_TYPE_SEND_WHATSAPP` | `send_whatsapp` | Send a WhatsApp message. | | `POINT_TYPE_SEND_TELEGRAM` | `send_telegram` | Send a Telegram message. | | `POINT_TYPE_SEND_KAKAO` | `send_kakao` | Send a Kakao message. | | `POINT_TYPE_SEND_LINE` | `send_line` | Send a LINE message. | | `POINT_TYPE_SEND_DATA` | `send_data` | Send a silent data message. | | `POINT_TYPE_INAPP` | `inapp` | Show an in-app message. | | `POINT_TYPE_BOOLEAN_SPLITTER` | `boolean_splitter` | Split users by a condition (segment, tags, or event). | | `POINT_TYPE_AB_SPLITTER` | `ab_splitter` | Split users into A/B groups. | | `POINT_TYPE_FILTER` | `filter` | Allow only users matching a filter to continue. | | `POINT_TYPE_SET_TAGS` | `set_tags` | Update user tags. | | `POINT_TYPE_WEBHOOK` | `web_hook` | Send an outbound HTTP request. | | `POINT_TYPE_GOAL_EVENT` | `goal_event` | Track a conversion goal. | | `POINT_TYPE_AUDIENCE_SYNC` | `audience_sync` | Sync users to an external audience. | | `POINT_TYPE_EXIT` | `terminator` | Exit the journey. | Note The per-type `point_data` payloads are documented in the [Point reference](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/). Entry, timing, splitting, and action points are covered in full there. Messaging points are covered at the envelope level with links to the relevant channel docs. ### Example point A “set tags” point with a single downstream connection: ```json { "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "title": "Tag as engaged", "point_type": "POINT_TYPE_SET_TAGS", "position": { "x": 480, "y": 120 }, "outputs": [ { "identity": { "key": "default", "order": 0 }, "info": { "title": "", "next_point_uuid": "ffffffff-1111-2222-3333-444444444444" } } ], "point_data": { "set_tags": { "application_code": "XXXXX-XXXXX", "tags": [ { "name": "engaged", "value": "true" } ] } } } ``` ## JourneyComment | Field | Type | Description | | ------------ | ----------------------- | ------------------------------- | | `id` | string | Comment UUID. | | `message` | string | Comment text. | | `position` | [`Position`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#position) | Canvas coordinates. | | `index` | int | Display order. | | `created_at` | string | Creation timestamp (ISO 8601). | | `deleted` | bool | Whether the comment is deleted. | ## Enums ### JourneyStatus enum `STATUS_DRAFT`, `STATUS_RUNNING`, `STATUS_FINISHED`, `STATUS_ARCHIVED`, `STATUS_PAUSED`, `STATUS_UNKNOWN`. ### CampaignType enum * `TriggerBased`: users enter on an event. * `AudienceBased`: users enter from a segment. * `APIBased`: users enter via the Start by API call. * `Mixed`: more than one entry type. * `Unknown`: entry type not determined. ### PointType enum See the [point types](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#point-types-and-point_data) table above for the full list and the `point_data` key each maps to. ### UserIDTrackChangePolicy enum Controls what happens to a user who is mid-journey when their [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) changes: * `DEFAULT`: default behavior. * `TRACK`: keep tracking the user under the new ID. * `DROP`: remove the user from the journey when their ID changes. ## Related [Point reference ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/) [Create and update ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/create-update/) [Lifecycle ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/lifecycle/) --- # Lifecycle **URL:** https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/lifecycle/ Start, pause, finish, draft, or archive a Customer Journey by its UUID through the /api/v3/journeygateway endpoints. --- The lifecycle endpoints move a journey between states. Pass the journey’s [Journey ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#journey-id) as `uuid` in the request body. The call returns the updated [journey object](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/). A journey is always in one of these states: | Status | Meaning | | ----------------- | -------------------------------------- | | `STATUS_DRAFT` | Being edited. Does not process users. | | `STATUS_RUNNING` | Active, processing users. | | `STATUS_PAUSED` | Temporarily halted, can be resumed. | | `STATUS_FINISHED` | Completed, no longer processing users. | | `STATUS_ARCHIVED` | Archived for storage. | ## Endpoints All lifecycle calls use the same request body: [Journey ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#journey-id) passed as `uuid`. They differ only in the path: | Action | Method & path | Resulting state | | ------- | ------------------------------------- | ----------------- | | Start | `POST /api/v3/journeygateway/start` | `STATUS_RUNNING` | | Pause | `POST /api/v3/journeygateway/pause` | `STATUS_PAUSED` | | Finish | `POST /api/v3/journeygateway/finish` | `STATUS_FINISHED` | | Draft | `POST /api/v3/journeygateway/draft` | `STATUS_DRAFT` | | Archive | `POST /api/v3/journeygateway/archive` | `STATUS_ARCHIVED` | ## Request | Field | Required | Type | Description | | ------ | -------- | ------ | ------------------------------------------------------------------------------------------------ | | `uuid` | Yes | string | [Journey ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#journey-id) of the journey to transition. | Body ```json { "uuid": "11111111-2222-3333-4444-555555555555" } ``` The API validates the current state before transitioning. For example, starting a journey that is already finished, or pausing one that is not running, returns an error. Note To start a journey **and** apply pending edits in one call, use [Update and resume](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/create-update/#update-and-resume) instead of `start`. ### Request examples #### Start a journey ```bash curl -X POST https://journey-api.svc-nue.pushwoosh.com/api/v3/journeygateway/start \ -H "Authorization: Api YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "uuid": "11111111-2222-3333-4444-555555555555" }' ``` #### Pause a journey ```bash curl -X POST https://journey-api.svc-nue.pushwoosh.com/api/v3/journeygateway/pause \ -H "Authorization: Api YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "uuid": "11111111-2222-3333-4444-555555555555" }' ``` ## Response Returns the updated [journey object](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/): `info`, `points`, and `comments`. The `info.status` field reflects the new state. ### Response example ```json { "info": { "uuid": "11111111-2222-3333-4444-555555555555", "title": "Welcome series", "status": "STATUS_RUNNING", "created_at": "2026-05-01T09:00:00Z", "updated_at": "2026-06-17T12:00:00Z", "params": { "application_code": "XXXXX-XXXXX" }, "campaign_type": "TriggerBased" }, "points": [], "comments": [] } ``` See the [journey object reference](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/) for the full field list. ## Related [Create and update ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/create-update/) [Start by API ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/start-by-api/) [Journey object ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/) --- # Point reference **URL:** https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/ Per-type point_data structures for Customer Journey points covering entry, timing, splitting, action, and messaging. --- Every [point](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#point) carries a `point_data` object with exactly one nested key, matching the point’s `point_type` (see the [point-type → key mapping](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#point-types-and-point_data)). This page documents the structure under each key. Note Entry, timing, splitting, action, and conversion points are documented in full below. For messaging points (`send_*`, `inapp`), this page covers only the structural fields: which preset or content to reference and which channel settings to pass. The message content itself is defined in the preset and documented in the [Presets API](https://docs.pushwoosh.com/developer/api-reference/presets-api/) and per-channel docs. Some fields reference nested objects that mirror the controls in the Customer Journey builder. ## Entry points A journey needs at least one entry point. All entry points have a single `default` output. ### start_by_segment Enters users who match a segment. `POINT_TYPE_START_BY_SEGMENT`. | Field | Type | Description | | ------------------ | --------------- | ---------------------------------------------------------------------------------------------------------------- | | `application_code` | string | [Application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). | | `filter_code` | string | [Segment/filter code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#segment--filter-code) that defines the audience. | | `repeat` | `SegmentRepeat` | Optional recurring-entry schedule (see [SegmentRepeat](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/#segmentrepeat)). | | `start_at` | timestamp | Do not process before this time (ISO 8601). | | `is_deactivated` | bool | Whether this entry point is turned off. | ### message_bus (event entry) Enters users when they trigger an event. `POINT_TYPE_EVENT`. | Field | Type | Description | | ------------------ | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `event_name` | string | [Event name](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#event-name) to listen for. | | `application_code` | string | [Application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). | | `event_conditions` | `PointEventCondition[]` | Conditions matched against the event’s attributes. | | `active_period` | `Period` | Time window during which the trigger is active. | | `multi_entry` | `MultiEntry` | How a user may enter more than once (see [MultiEntry](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/#multientry)). | | `attribute_entry` | `AttributeEntry` | Enroll the user IDs carried in an event attribute instead of the user who triggered the event (see [AttributeEntry](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/#attributeentry)). | | `allow_reenter` | bool | Whether users may re-enter the journey. | ##### AttributeEntry Enrolls the [User IDs](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) carried in an event attribute, instead of the user who triggered the event. Mirrors [Users from an event attribute](https://docs.pushwoosh.com/product/customer-journey/journey-elements/entry-elements/trigger-based-entry/#users-from-an-event-attribute) in the Customer Journey builder. | Field | Type | Description | | ---------------- | ------ | ------------------------------------------------------------------------------------------------- | | `enabled` | bool | Whether to enroll users named in an event attribute rather than the user who triggered the event. | | `attribute_name` | string | Name of the event attribute that holds the User ID (or list of User IDs) to enroll. | ### start_by_api Entry point fed by the [Start by API](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/start-by-api/) call. `POINT_TYPE_START_BY_API`. | Field | Type | Description | | ------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `application_code` | string | [Application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). | | `attributes` | string[] | Names of the custom attributes that can be passed in the `attribute_values` of a [Start by API](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/start-by-api/#request-body) request. | | `is_deactivated` | bool | Whether this entry point is turned off. | ## Timing points ### delay (wait) Pauses each user for a fixed or computed interval. `POINT_TYPE_WAIT`. The `point_data.delay` object sets exactly one of the following interval keys: | Interval key | Type | Description | | ---------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------- | | `sec` | uint64 | Wait a fixed number of seconds. | | `exact_time` | [`ExactTime`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/#time-objects) | Wait until a time of day (`hour`, `minute`). | | `exact_date_time` | [`ExactDateTime`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/#time-objects) | Wait until an absolute date and time. | | `exact_week_days_time` | `ExactWeekDaysTime` | Wait until specific times on specific weekdays (map of day `0`=Monday … `6`=Sunday → `ExactTime`). | | `dynamic_time` | [`DynamicTime`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/#dynamictime) | Wait relative to a value from a tag or event. | A `dynamic_time` with `split_branches: true` adds an `output1` branch (see [output keys](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#output-keys)). #### DynamicTime | Field | Type | Description | | --------------------------------------------- | --------------------------- | -------------------------------------------------------------------- | | `from` | enum `DynamicTimeFrom` | Whether the base time comes from a tag or an event. | | `direction` | enum `DynamicTimeDirection` | Offset before or after the base time. | | `duration` | uint64 | Size of the offset. | | `unit` | enum `DynamicTimeUnit` | Unit of `duration` (minutes, hours, days, …). | | `split_branches` | bool | Split users into separate branches when their computed times differ. | | `tag_name` | string | Tag holding the base time (when `from` is a tag). | | `event_name` / `event_attribute` / `point_id` | string | Event source of the base time (when `from` is an event). | ### wait_event Waits until users trigger an event (or a timeout). `POINT_TYPE_WAIT_EVENT`. The `default` output is the **not-triggered** path. The triggered path is `output1` or, with a script, one branch per condition. | Field | Type | Description | | ------------------- | ---------------------- | ------------------------------------------------------------------------------------------------- | | `events` | `PointWaitEventInfo[]` | Events to wait for. | | `conditions_script` | string | Optional script for complex multi-event logic. Its parsed condition names become the output keys. | | `multi_entry` | `MultiEntry` | Re-entry behavior. | ## Splitting and filtering points ### boolean_splitter Routes users down branches based on a condition. `POINT_TYPE_BOOLEAN_SPLITTER`. | Field | Type | Description | | -------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------- | | `split_strategy` | enum | `SPLIT_FILTER` (by segment), `SPLIT_TAGS` (by tag conditions), or `SPLIT_EVENTS` (by event conditions). | | `load_policy` | enum | `ALL` (any of the user’s devices may match) or `FILTER` (only the current device). | | `filter_code` | string | Segment code, when `split_strategy` is `SPLIT_FILTER`. | | `filter_expressions` | `FilterExpression[]` | Tag conditions, when `split_strategy` is `SPLIT_TAGS`: one extra `output` branch per expression. | | `event` | `BooleanSplitterEventInfo` | Event conditions, when `split_strategy` is `SPLIT_EVENTS`: one extra `output` branch per condition. | ### ab_splitter Randomly splits users into weighted variants. `POINT_TYPE_AB_SPLITTER`. Output keys are `output0`, `output1`, … (one per entry in `split`, indexed from 0. There is no `default`). | Field | Type | Description | | -------------------- | --------- | -------------------------------------------------------------------------------------- | | `split` | uint32[] | Percentage for each branch. Must sum to 100. Index `i` maps to output key `output{i}`. | | `auto_select_winner` | bool | Whether to automatically pick a winning branch. | | `winner_strategy` | enum | `ANY_GOAL` or `SPECIFIC_GOAL`. | | `goal_uuid` | string | Goal used to determine the winner (with `SPECIFIC_GOAL`). | | `winner_split` | uint32 | Winning branch number (1-based, `0` = no winner yet). | ### filter Lets only matching users continue (`default`), routing the rest to `output1`. `POINT_TYPE_FILTER`. | Field | Type | Description | | ------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `filter` | enum `Filter` | A predefined check: `EMAIL_EXISTS`, `PUSH_TOKEN_EXISTS`, `SMS_TOKEN_EXISTS`, `WHATSAPP_TOKEN_EXISTS`, `LINE_TOKEN_EXISTS`, or `CUSTOM`. | | `filter_raw` | string | Custom filter expression, when `filter` is `CUSTOM`. | ## Action points ### set_tags Updates tags on the user. `POINT_TYPE_SET_TAGS`. | Field | Type | Description | | ------------------ | ---------------- | ------------------------------------------------------------------------------- | | `application_code` | string | [Application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). | | `tags` | [`Tag`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/#tag)[] | Tags to write. | #### Tag | Field | Type | Description | | ------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Tag name. | | `type` | enum `TagType` | Data type and operation: `TYPE_STRING`, `TYPE_INTEGER`, `TYPE_DATE`, `TYPE_BOOLEAN`, `TYPE_LIST`, `TYPE_LIST_APPEND`, `TYPE_LIST_REMOVE`, `TYPE_DYNAMIC`, … | | *value* | oneof | Exactly one value key matching `type`: `str`, `int`, `bool`, `date`, `price`, `version`, `timezone`, `list`, or `dynamic`. | ### web_hook Sends an outbound HTTP request. `POINT_TYPE_WEBHOOK`. Single `default` output. | Field | Type | Description | | ------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------ | | `method` | string | HTTP method (`GET`, `POST`, `PUT`, …). | | `url` | string | Target URL. | | `request_template` | string | Request body template. Supports [Liquid](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/) templating. | | `headers` | map | HTTP headers. | | `disabled` | bool | Read-only. `true` when Pushwoosh auto-disabled the webhook after repeated errors. | | `reactivate` | bool | Write-only. Set `true` to re-enable a disabled webhook. | ## Conversion points ### goal_event Tracks a conversion goal. `POINT_TYPE_GOAL_EVENT`. Has no outputs. | Field | Type | Description | | ------------------ | ----------------------- | ------------------------------------------------------------------------------- | | `event_name` | string | Goal event name. | | `application_code` | string | [Application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). | | `event_conditions` | `PointEventCondition[]` | Conditions matched against the goal event’s attributes. | | `is_throw_out` | bool | Whether to remove the user from the journey once the goal is reached. | | `is_cancel_event` | bool | Whether this is a negative (cancellation) goal. | ## Exit points ### terminator Ends the journey for the user. `POINT_TYPE_EXIT`. Empty object (`{}`) and no outputs. ```json { "point_type": "POINT_TYPE_EXIT", "point_data": { "terminator": {} }, "outputs": [] } ``` ## Messaging points All messaging points send through a channel and share a common envelope. Each has a single `default` output unless a splitter is enabled (see [output keys](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/#output-keys)). Common fields: | Field | Type | Description | | ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `application_code` | string | [Application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). | | `preset_code` | string | [Preset](https://docs.pushwoosh.com/developer/api-reference/presets-api/) (template) to send. `inapp` uses `richmedia_code` instead. | | `content` / `title` | string | Inline message content, when not using a preset (channel-dependent). | | `campaign_code` | string | [Campaign code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#campaign-code) for tracking. Created automatically if omitted. | | `split_params` | [`BehaviorSplitter`](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/#behaviorsplitter) | Optional: wait for an interaction and branch on it. | | `message_type` | enum | [Marketing vs transactional](https://docs.pushwoosh.com/product/messaging-channels/marketing-vs-transactional/) message type (controls control-group handling). | Point types and their notable extra fields: | Point type | `point_data` key | Notes | | -------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------- | | `POINT_TYPE_SEND_PUSH` | `send_push` | `split_params` (behavior) plus a delivery splitter can produce up to three outputs. `send_by_user_id`, `wait_optimal_time`. | | `POINT_TYPE_SEND_EMAIL` | `send_email` | `liquid_template_params`, `personalise`. See the [Email API](https://docs.pushwoosh.com/developer/api-reference/email-api/). | | `POINT_TYPE_SEND_SMS` | `send_sms` | See [SMS](https://docs.pushwoosh.com/developer/api-reference/sms/). | | `POINT_TYPE_SEND_WHATSAPP` | `send_whatsapp` | A quick-reply preset adds one output per reply (key = reply value). See [WhatsApp](https://docs.pushwoosh.com/developer/api-reference/whatsapp/). | | `POINT_TYPE_SEND_TELEGRAM` | `send_telegram` | Telegram channel. | | `POINT_TYPE_SEND_KAKAO` | `send_kakao` | See [Kakao](https://docs.pushwoosh.com/developer/api-reference/kakao/). | | `POINT_TYPE_SEND_LINE` | `send_line` | See [LINE API](https://docs.pushwoosh.com/developer/api-reference/line-api/). | | `POINT_TYPE_SEND_DATA` | `send_data` | Silent data message (no UI). | | `POINT_TYPE_INAPP` | `inapp` | Uses `richmedia_code`, `expire_in_days`, `capping`. | ## Shared types ### SegmentRepeat | Field | Type | Description | | ----------- | ------------------- | -------------------------------------------- | | `enabled` | bool | Whether recurring entry is on. | | `frequency` | string | `daily`, `weekly`, `monthly`, or `dates`. | | `every` | uint32 | Repeat every N periods. | | `dates` | string[] | Specific dates, when `frequency` is `dates`. | | `time` | `SegmentRepeatTime` | Time-of-day configuration. | ### Time objects * `ExactTime`: `{ "hour": 0–23, "minute": 0–59 }`. * `ExactDateTime`: `{ "year", "month": 1–12, "day": 1–31, "hour": 0–23, "minute": 0–59 }`. ### BehaviorSplitter | Field | Type | Description | | ---------- | ------ | ---------------------------------------------------- | | `enabled` | bool | Whether to wait for an interaction and branch on it. | | `interval` | uint64 | Seconds to wait for the interaction. | ### MultiEntry Controls how many active sessions a user can have in the journey at the same time. Mirrors [Control how many sessions a user can have at the same time](https://docs.pushwoosh.com/product/customer-journey/journey-elements/entry-elements/trigger-based-entry/#control-how-many-sessions-a-user-can-have-at-the-same-time) in the Customer Journey builder. Used by the [event entry point](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/#message_bus-event-entry) and [wait_event](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/#wait_event). | Field | Type | Description | | ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | bool | Whether a user can have multiple active sessions at the same time. `false`: one active session per user. `true`: multiple active sessions per user. | | `attribute_name` | string | Optional. Event attribute that scopes each session. When set, a user can have one active session per distinct value of this attribute (for example, one per `order_id`). Events with the same value share one session. Leave empty to scope all of the user’s entries together. | ## Related [Journey object ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/journey-object/) [Create and update ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/create-update/) [Presets API ](https://docs.pushwoosh.com/developer/api-reference/presets-api/) --- # Start by API **URL:** https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/start-by-api/ Inject users into the API entry point of a running Customer Journey using /api/journey/{id}/start/external. --- `POST` `https://journey.pushwoosh.com/api/journey/{id}/start/external` Enters a set of users into a journey’s **API entry point**. Use it to drive journeys from your own backend. For example, start an onboarding flow when a user completes signup on your server. Tip Do not confuse this call with [Lifecycle start](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/lifecycle/#endpoints), which activates a journey and moves it into **Running**. Start by API injects users into a journey that is already running. See the [comparison table](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/#lifecycle-start-vs-start-by-api). ## Prerequisites * The journey is in the **Running** state. * The journey contains exactly one API entry point (the “Start by API” element), and that element is not deactivated. * The attribute names you send match the attributes configured on that API entry point. Rate limit Each API entry point accepts **one request per minute**. A second request within that window returns an error (`Enhance your calm! only one request per minute is allowed`). Batch your recipients into a single request rather than sending many small ones. ## Path parameters | Name | Type | Description | | ---- | ------ | ------------------------------------------------------------------------------------------ | | `id` | string | [Journey ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#journey-id) of the running journey. | ## Request headers | Name | Required | Value | | --------------- | -------- | -------------------------------------------------------------------------------------------------------------- | | `Content-Type` | Yes | `application/json` | | `Authorization` | Yes | `Api `. See [Server API token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#server-api-token). | ## Request body The body has a single `payload` object. You must provide **exactly one** of `users`, `hwids`, or `filter` to select who enters the journey. | Field | Type | Description | | -------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `payload.users` | string[] | [User IDs](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) to enter. Mutually exclusive with `hwids` and `filter`. | | `payload.hwids` | string[] | [HWIDs](https://docs.pushwoosh.com/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) to enter. Mutually exclusive with `users` and `filter`. | | `payload.filter` | string | A [seglang](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api/segmentation-language/) expression selecting the audience. Mutually exclusive with `users` and `hwids`. | | `payload.attribute_values` | map | Optional. Values for the custom attributes defined on the API entry point. Each key must match a configured attribute name. | ### Request examples ##### Enter specific users ```bash curl -X POST 'https://journey.pushwoosh.com/api/journey//start/external' \ -H 'Authorization: Api YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "payload": { "users": ["user-123", "user-456"] } }' ``` ##### Enter specific users with attributes ```json { "payload": { "users": ["user-123", "user-456"], "attribute_values": { "promo_code": "SUMMER25", "tier": "gold" } } } ``` ##### Enter an audience by filter ```json { "payload": { "filter": "A(\"XXXXX-XXXXX\").tags(\"City\").eq(\"London\")" } } ``` ## Response * 200 ```json { "request_uuid": "9f8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d" } ``` | Field | Type | Description | | -------------- | ------ | ---------------------------------------------------------------------------------- | | `request_uuid` | string | Identifier of the accepted entry request. The request is processed asynchronously. | * 400 Validation errors return HTTP `400` with a descriptive message. Common cases: | Message | Cause | | ----------------------------------------------------------- | ------------------------------------------------------------------- | | `one of users, hwids or filter must be provided` | None of the three selectors was set. | | `only one of users, hwids or filter must be provided` | More than one selector was set. | | `Journey is not running` | The journey is not in the Running state. | | `zero api start points` | The journey has no API entry point. | | `there is more then one api start point` | The journey has more than one API entry point. | | `point is deactivated` | The API entry point is deactivated. | | `unknown attribute: ` | An `attribute_values` key is not configured on the API entry point. | | `Enhance your calm! only one request per minute is allowed` | Rate limit hit (one request per minute per entry point). | ## Related [Lifecycle ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/lifecycle/) [Get Journey stats ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/statistics/) [Segmentation language ](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api/segmentation-language/) --- # Get Journey stats **URL:** https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/statistics/ Retrieve per-point delivery and conversion statistics for a Customer Journey by its ID. --- `GET` `https://journey.pushwoosh.com/api/journey/{id}/statistics/external` Returns statistics for a Customer Journey by its ID. Replace `{id}` in the URL with the [Journey ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#journey-id) from the journey canvas page URL: ![Journey ID in the Journey canvas URL](https://docs.pushwoosh.com/api-reference-customer-journey-statistics-1.webp) Send a GET request with no body. #### Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------------------ | -------------------------------------------------------------------------------- | | Authorization | Yes | `Api ` | [Server API token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#server-api-token). | #### Request example ```shell curl --location --request GET 'https://journey.pushwoosh.com/api/journey//statistics/external' \ --header 'Authorization: Api ' ``` #### Response example * 200 ```json { "payload": { "title": "Journey Title", "points": [{ "pointTitle": "First Point Title", "campaignCode": "AAAAA-00000", "presetCode": "12345-67890", "pointStat": { "sent": 22648, "opened": 60, "conversion": 0.26492405510420347 } }] } } ``` #### In-app `pointStat` fields The fields inside `pointStat` depend on the journey element’s channel. In-app elements return the metrics below instead of the `sent`, `opened`, and `conversion` fields shown in the response example above. | Field | Type | Description | | -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `shows` | number | Number of times in-app messages were displayed to users. Labeled **Impressions** in [Journey statistics](https://docs.pushwoosh.com/product/statistics-and-analytics/journey-statistics/overall-journey-statistics/#metrics-by-channel). | | `interactions` | number | Number of user interactions with the in-app message (for example, button clicks). Labeled **Interactions** in [Journey statistics](https://docs.pushwoosh.com/product/statistics-and-analytics/journey-statistics/overall-journey-statistics/#metrics-by-channel). | | `skipped` | number | Number of times users skipped or dismissed the in-app message without interacting. Labeled **In-App Skips** in [Journey statistics](https://docs.pushwoosh.com/product/statistics-and-analytics/journey-statistics/overall-journey-statistics/#metrics-by-channel). | #### In-app response example ```json { "payload": { "title": "Journey Title", "points": [{ "pointTitle": "In-App element title", "campaignCode": "AAAAA-00000", "presetCode": "12345-67890", "pointStat": { "shows": 3148, "interactions": 2759, "skipped": 36 } }] } } ``` ## Related [Remove users from journeys ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/drop-users/) [Lifecycle ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/lifecycle/) [Start by API ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/start-by-api/) --- # Device API **URL:** https://docs.pushwoosh.com/developer/api-reference/device-api/ Register devices, manage tags, track events, and handle device-related operations using Device API methods. --- ## registerDevice `POST` `https://api.pushwoosh.com/json/1.3/registerDevice` Called internally from the SDK. Registers device for the application. ##### Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | ##### Request body | Name | Type | Description | | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | push_token | string | [Push token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#push-token) for the device. | | language | string | Language locale of the device. Must be a lowercase two-letter code according to ISO-639-1 standard. | | hwid* | string | Unique string to identify the device (IDFV on iOS, randomly generated value on Android). [Learn more](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) | | timezone | integer | Timezone offset in seconds for the device. | | device_type* | integer | [Device type](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#device-type). See possible values below. | | email | string | Email address to register (use for email users instead of HWID and push token). | | tags | object | Tag values to assign to the device registered. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` Example ```json { "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "push_token": "dec301908b9ba8XXXXX57a58e40f96f5XXXXX2068674f5XXXXa25cdc250a2a41", // optional. "hwid": "1CA6XXXXX-8DAC-XXXXX-XXXXX-B756288B6D3C", // required. Hardware device ID "idfa": "AEBE52E7-0XXXXX-455A-XXXXX-E57283966239", // optional. "timezone": 3600, // optional. Offset in seconds "device_type": 1, // required. See the possible values below. For emails, // use the "emails" params as described below. "email": "email_address@domain.com", // use instead of "hwid" and "push_token" to register // the email address for your email project "language": "en", // optional. ISO 639-1|639-2 language code "userId": "Alex", // optional. "tags": { // optional. Tag values to set for the device registered "StringTag": "string value", "IntegerTag": 42, "ListTag": ["string1", "string2"], // sets the list of values for Tags of List type "DateTag": "2024-10-02 22:11", // note the time should be in UTC "BooleanTag": true // valid values are: true, false }, // system tags, optionals "app_version": "1.2.3", "device_model": "Samsung SM-G355H", "os_version": "2.3", // optional encryption keys for chrome/firefox "public_key": "BNmDO4BTKEMJqaqprTf7t/HBXXXXX/orcXXXXX/scS5CFP6XXXXXHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=", "auth_token": "RlRmCXXXXX/s7XXXXXjKFzoQ==", // optional FCM keys for Chrome (for XMPP) "fcm_token": "BNmDO4BTKEMJXXXXXprTf7t/XXXXXBQ/orXXXXXc/scS5CFP6zhQGIHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=", "fcm_push_set": "RlXXXXXGM/s7XXXXXjKFzoQ==" } } ``` Possible device types: * 1 – iOS * 3 – Android * 7 – Mac OS X * 8 – Windows * 9 – Amazon * 10 – Safari * 11 – Chrome * 12 – Firefox * 13 – Internet Explorer * 14 – Email * 16 – Baidu Android * 17 – Huawei * 18 – SMS * 20 – Web * 21 – WhatsApp * 22 – Line * 23 – Kakao Talk * 24 – Telegram * 25 – Apple Wallet * 26 – Google Wallet * 27 – Viber ### Registering email devices To **register a email subscriber** for your app, send the `"email": "email_address@domain.com"` param in your `/registerDevice` or [`/registerEmail`](https://docs.pushwoosh.com/developer/api-reference/email-api#registeremail) request as follows: ##### Request example ```json { "request":{ "application": "XXXXX-XXXXX", // required. Pushwoosh application code "email": "email_address@domain.com", // required. Email address to register for your email project "language": "en", // optional. ISO 639-1|639-2 language code "userId": "Alex", // optional. "tags": { // optional. Tag values to set for the device registered "StringTag": "string value", "IntegerTag": 42, "ListTag": ["string1", "string2"], // sets the list of values for Tags of List type "DateTag": "2024-10-02 22:11", // note the time should be in UTC "BooleanTag": true // valid values are: true, false } } } ``` ### Registering WhatsApp devices To register a WhatsApp device for your app, follow these guidelines: * **hwid**: Ensure this field includes the whatsapp: prefix followed by the phone number in E.164 format (e.g., whatsapp:+0000000000). The phone number must be valid, which Pushwoosh will verify. * **Push token**: A push token is not required, as hwid will automatically function as the push token. * **device_type**: Set this field to 21 to specify WhatsApp as the platform. ##### Request example ```json { "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "whatsapp:+0000000000", // required. WhatsApp prefix and valid phone number "timezone": 3600, // optional. Time offset in seconds "device_type": 21, // required. WhatsApp device type is 21 "language": "en", // optional. ISO 639-1|639-2 language code "userId": "Alex", // optional. User identifier "tags": { // optional. Tag values for custom segmentation "StringTag": "string value", "IntegerTag": 42, "ListTag": ["string1", "string2"], "DateTag": "2024-10-02 22:11", // UTC format "BooleanTag": true }, "app_version": "1.2.3", // optional. Application version "device_model": "Samsung SM-G355H", // optional. Device model "os_version": "2.3" // optional. Operating system version } } ``` ### Registering SMS devices To register an SMS device for your app, follow these guidelines: * **hwid**: Ensure this field includes the phone number in E.164 format (e.g., +0000000000). The phone number must be valid, which Pushwoosh will verify. * **Push token**: A push token is not required, as hwid will automatically function as the push token. * **device_type**: Set this required field to 18 to designate SMS as the platform. ##### Request example ```json { "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "+0000000000", // required. Valid phone number in E.164 format "timezone": 3600, // optional. Time offset in seconds "device_type": 18, // required. SMS device type is 18 "language": "en", // optional. ISO 639-1|639-2 language code "userId": "Alex", // optional. User identifier "tags": { // optional. Tag values for custom segmentation "StringTag": "string value", "IntegerTag": 42, "ListTag": ["string1", "string2"], "DateTag": "2024-10-02 22:11", // UTC format "BooleanTag": true }, "app_version": "1.2.3", // optional. Application version "device_model": "Samsung SM-G355H", // optional. Device model "os_version": "2.3" // optional. Operating system version } } ``` **Status codes**: | HTTP Status code | status_code | Description | | ---------------- | ------------ | -------------------------------------------------- | | 200 | 200 | Device successfully registered | | 200 | 210 | Argument error. See status_message for more info. | | 400 | N/A | Malformed request string | | 500 | 500 | Internal error | ## unregisterDevice `POST` `https://api.pushwoosh.com/json/1.3/unregisterDevice` Removes the device’s push token. The unregistered device is still counted in Total Devices and can be reached with In-Apps. Called internally from the SDK. ##### Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | ##### Request body | Name | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------ | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | hwid* | string | [Hardware device ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) used in /registerDevice request. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` Example ```json { "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "8f65b16XXXXXe7a6beceXXXXX530fb2" // required. Hardware device ID used in /registerDevice API } } ``` Note For emails call [`/deleteEmail`](https://docs.pushwoosh.com/developer/api-reference/email-api/#deleteemail). **Status codes**: | HTTP Status code | status_code | Description | | ---------------- | ------------ | -------------------------------------------------- | | 200 | 200 | Device successfully unsubscribed | | 200 | 210 | Argument error. See status_message for more info. | | 400 | N/A | Malformed request string | | 500 | 500 | Internal error | ## deleteDevice `POST` `https://api.pushwoosh.com/api/v2/device-api/deleteDevice` Deletes a device and all its associated data identified by the specified [HWID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) within the application. Unlike [`/unregisterDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api/#unregisterdevice), which only removes the push token and keeps the device record, `/deleteDevice` fully removes the device. The request is processed asynchronously, and the endpoint returns `200 OK` as soon as the delete request has been accepted for processing. #### Request headers | Name | Required | Value | Description | | ------------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | | Content-Type | Yes | application/json | | #### Request body | Name | Required | Type | Description | | ----------- | -------- | ------ | ---------------------------------------------------------------------------------------------------- | | application | Yes | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | hwid | Yes | string | [Hardware device ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) of the device to delete. | #### Request example ```json { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "8f65b16df378e7a6bece9614e1530fb2" // required. Hardware device ID of the device to delete } ``` #### Response example * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` ##### Status codes | HTTP Status code | status_code | Description | | ---------------- | ------------ | -------------------------------------------------- | | 200 | 200 | Delete request accepted | | 200 | 210 | Argument error. See status_message for more info. | | 400 | N/A | Malformed request string | | 401 | N/A | Missing or invalid Authorization token | | 500 | 500 | Internal error | ## setTags `POST` `https://api.pushwoosh.com/json/1.3/setTags` Sets tags values for the device. Called from the SDK. ##### Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | ##### Request body | Name | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------ | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | hwid* | string | [Hardware device ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) used in /registerDevice request. | | tags* | object | JSON object of tags to set, send “null” to remove the value. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` Note The method is called from the SDK. It is possible to call it remotely from your backend, however you need to maintain an up-to-date database of hwid’s on the backend side. Example ```json { "request":{ "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "8f65b16XXXXXe7a6becXXXXXe1530fb2", // required. Hardware device ID used in /registerDevice API "tags": { // required. "StringTag": "string value", "IntegerTag": 42, "ListTag": ["string1", "string2"], // sets the list of values for Tags of List type "DateTag": "2024-10-02 22:11", // note the time is in UTC "BooleanTag": true // valid values are - true, false } } } ``` ### Increment Integer tag values To **increment** a value of the Integer Tag, use the `operation` parameter with the “increment” value as follows: ```json { "request":{ "application": "12345-67890", // required. Pushwoosh application code "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // required. hardware device ID used in /registerDevice API "tags": { // required. "Level": { // Tag name "operation": "increment", // overwrites the integer tag in increments of the following value "value": 1 // increment for the tag value } } } } ``` ### Decrement Integer tag values To **decrement**, use the negative numbers as the value for the “increment” operation (-1, -2, -3,-n): ```json { "request":{ "application": "12345-67890", // required. Pushwoosh application code "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // required. Hardware device ID used in /registerDevice API "tags": { // required "Level": { // Tag name "operation": "increment", // overwrites the integer tag in decrement of the following value "value": -1 // decrement for the tag value } } } } ``` ### Append List tag values To **extend the List Tag with new values**, use the `operation` parameter with the “append” value as follows: Example ```json { "request": { "hwid": "3d124a79XXXXf189XXXX7dfd9XXXXafd", // required. Hardware device ID used in /registerDevice API "application": "6XXXX-XXXX3", // required. Pushwoosh application code "tags": { // required. "ListTag": { // Tag name "operation": "append", // appends following values to the Tag's list of values "value": [ // values to append "tag2", "tag3" ] } } } } ``` ### Remove List tag values To remove some values from the List Tag, use the “remove” operation as follows: ```json { "request":{ "application": "12345-67890", // required. Pushwoosh application code "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // required. Hardware device ID used in /registerDevice API "tags": { // required. "In-App Product": { // Tag name "operation": "remove", // removes the following values from the list tag "value": "outwear_02" // value or values to remove } } } } ``` ### Set tags by UserID To set tags for all devices associated to a particular [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id), use the “userId” parameter instead of “hwid”. Caution Make sure the tag you’re setting values for is [user-specific](https://docs.pushwoosh.com/developer/guides/audience-and-segmentation/tags/#tag-scope-general-vs-user-specific). Example ```json { "request":{ "application": "AAAAA-BBBBB", // Pushwoosh app code "userId": "some_user", // user ID you'd like to set tags for "tags": { // tags and values to set "Language": "es" } } } ``` Note For emails call [`/setEmailTags`](https://docs.pushwoosh.com/developer/api-reference/email-api/#setemailtags). **Status codes:** | HTTP Status code | status_code | Description | | ---------------- | ------------ | -------------------------------------------------- | | 200 | 200 | Tags have been successfully set | | 200 | 210 | Argument error. See status_message for more info. | | 400 | N/A | Malformed request string | | 500 | 500 | Internal error | ## getTags `POST` `https://api.pushwoosh.com/json/1.3/getTags` Retrieves a list of tags with corresponding values for the specific device. ##### Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | ##### Request body | Name | Type | Description | | ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | userId | string | [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) to be used instead of “hwid”. If used together with a “hwid”, the “hwid” prevails. | | hwid | string | [Hardware device ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) used in `/registerDevice` request. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "result": { "Language": "fr" } } } ``` Example ```json { "request":{ "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "HWID", // optional. Hardware device ID used in /registerDevice API "userId": "USER_ID" // optional. Can be used instead of "hwid" to retrieve tags for a specific user } } ``` ## setBadge `POST` `https://api.pushwoosh.com/json/1.3/setBadge` Sends current badge value for a device to Pushwoosh. Called internally from the SDK. ##### Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | ##### Request body | Name | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | hwid* | string | [Hardware device ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) used in /registerDevice request. | | badge* | integer | Current badge on the application. | * 200 ```json { "status_code": 200, "status_message": "OK" } ``` Example ```json { "request":{ "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "8f65b16dXXXXe7a6XXXX9614XXXX0fb2", // required. Hardware device ID used in /registerDevice API "badge": 4 // required. Current badge on the application } } ``` Called from the SDK internally. Sends current badge value for a device to Pushwoosh. This happens internally when app changes badge value on iOS device. Allows auto-incrementing badges to work properly. Caution This method **IS NOT** used to update the badge value on the device. Instead please use [`/createMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api/#createmessage) request with the `"ios_badges"` parameter. ## applicationOpen `POST` `https://api.pushwoosh.com/json/1.3/applicationOpen` Registers an app open event. Called internally from the SDK. ##### Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | ##### Request body | Name | Type | Description | | ------------- | ------ | -------------------------------------------------------------------------------------------------------------- | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | hwid* | string | [Hardware device ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) used in `/registerDevice` request. | * 200 ```json { "status_code": 200, "status_message": "OK" } ``` Example ```json { "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "8f65b16dXXXXe7a6XXXX9614eXXXXfb2" // required. Hardware device ID used in /registerDevice API } } ``` ## pushStat `POST` `https://api.pushwoosh.com/json/1.3/pushStat` Registers a push open event. Called internally from the SDK. ##### Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | ##### Request body | Name | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------ | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | hwid* | string | [Hardware device ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) used in /registerDevice request. | | userId | string | [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) to associate with the push open event. | | hash | string | Hash tag received in push notification (“p” parameter of the push payload). | * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` Example ```json { "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "8f65b16dfXXXX7a6beXXXX14e1530fb2", // required. Hardware device ID used in /registerDevice API "userId": "USER012345", // optional. The user id to associate with the push open event "hash": "HASH_TAG" // optional. Hash tag received in push notification // ("p" parameter in the push payload) } } ``` ## messageDeliveryEvent `POST` `https://api.pushwoosh.com/json/1.3/messageDeliveryEvent` Registers push delivery event for the device. Called internally from the SDK. ##### Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | ##### Request body | Name | Type | Description | | ------------- | ------ | -------------------------------------------------------------------------------------------------------------- | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | hwid* | string | [Hardware device ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) used in `/registerDevice` request. | | hash | string | Hash tag received in push notification (“p” parameter of the push payload). | * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` Example ```json { "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "8f65b16dfXXXX7a6bece9XXXX1530fb2", // required. Hardware device ID used in /registerDevice API "hash": "HASH_TAG" // optional. Hash tag received in push notification // ("p" parameter in the push payload) } } ``` --- # Email API **URL:** https://docs.pushwoosh.com/developer/api-reference/email-api/ Create email messages, register email addresses, and manage email-related operations using Email API methods. --- /createEmailMessage is deprecated New integrations should use [Messaging API v2](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/) — pass `platforms: ["EMAIL"]` and an [`email_payload`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/email-payload-reference/) block to `Notify`. See the [migration guide](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/migration-from-v1/#from-createemailmessage). ## createEmailMessage Deprecated Creates an email message. `POST` `https://api.pushwoosh.com/json/1.3/createEmailMessage` ### Request body parameters | Name | Type | Required | Description | | ------------- | -------- | :------: | ------------------------------------------------------------------------------------------------------------ | | auth | `string` | Yes | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application | `string` | Yes | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | notifications | `array` | Yes | JSON array containing email message details. See the **Notifications Parameters** table below. | Tip Pass an `X-Request-ID` header to correlate the created message with your request for end-to-end tracing — see [Request ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#request-id). #### Notifications parameters | Name | Type | Required | Description | | ------------------------------ | -------------------- | :------------------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | send_date | `string` | Yes | Defines when to send the email. Format: `YYYY-MM-DD HH:mm` or `"now"`. | | preset | `string` | Yes | [Email preset code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#email-content-code). Copy from the URL bar of the **Email Content Editor** in the Pushwoosh Control Panel. | | subject | `string` or `object` | No | Subject line of the email. The email will always be in the language of the content. If `subject` does not contain a matching language for `content`, the subject will be empty. | | content | `string` or `object` | No | The email body content. Can be a string for plain HTML content or an object for localized versions. | | attachments | `array` | No | The email attachments. Only two attachments are available. Each attachment must not exceed 1MB (base64 encoded). | | list_unsubscribe | `string` | No | Allow to set custom URL for “Link-Unsubscribe” header. | | campaign | `string` | No | [Campaign code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#campaign-code) to associate the email with a specific campaign. | | ignore_user_timezone | `boolean` | No | If `true`, sends the email immediately, ignoring user timezones. | | timezone | `string` | No | Sends the email according to the user’s timezone. Example: `"America/New_York"`. | | filter | `string` | No | Sends the email to users matching a [specific filter condition](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#segment--filter-name). | | devices | `array` | No | List of email addresses (max 1000) to send targeted emails. If used, the message is sent only to these addresses. Ignored if the Application Group is used. | | use_auto_registration | `boolean` | No | If `true`, automatically registers emails from the `devices` parameter. | | users | `array` | No | If set, the email message will only be delivered to the specified [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id)s (registered via /registerEmail call). Not more than 1000 user IDs in an array. If the “devices” parameter is specified,the “users” parameter will be ignored. | | dynamic_content_placeholders | `object` | No | Placeholders for dynamic content instead of device tag values. | | conditions | `array` | No | Segmentation conditions using tags. Example: `[["Country", "EQ", "BR"]]`. | | from | `object` | No | Specify a custom sender name and email, overriding the default in application properties. | | reply-to | `object` | No | Specify a custom reply-to email, overriding the default in application properties. | | bcc | `array` | No | BCC (Blind Carbon Copy): array of email addresses that receive a copy of the email without other recipients seeing them. | | email_type | `string` | No | Specify the email type: `"marketing"` or `"transactional"`. If omitted, users with `PW_ControlGroup: true` will not receive the message. | | email_category | `string` | Required when `email_type` is `"marketing"`. | Specify one of the category names configured in the [subscription preference center](https://docs.pushwoosh.com/product/messaging-channels/emails/email-preferences/) (e.g. Newsletter, Promotional, Product Updates). | | transactionId | `string` | No | Unique message identifier to prevent re-sending in case of network problems. Stored on the side of Pushwoosh for 5 minutes. | | capping_days | `integer` | No | The number of days (max 30) to apply frequency capping per device. **Note:** Ensure [Global frequency capping](https://docs.pushwoosh.com/product/messaging-channels/global-frequency-capping/) is configured in the Control Panel. | | capping_count | `integer` | No | The max number of emails that can be sent from a specific app to a particular device within a `capping_days` period. In case the message created exceeds the `capping_count` limit for a device, it won’t be sent to that device. | | capping_exclude | `boolean` | No | If set to `true`, this email will not be counted towards the capping for future emails. | | capping_avoid | `boolean` | No | If set to `true`, capping will not be applied to this specific email. | | send_rate | `integer` | No | Limit how many messages can be sent per second across all users. Helps prevent backend overload during high-volume sends. | | send_rate_avoid | `boolean` | No | If set to true, throttling limit will not be applied to this specific email. | ### Request example ```json { "request": { "auth": "API_ACCESS_TOKEN", // required. API access token from Pushwoosh Control Panel "application": "APPLICATION_CODE", // required. Pushwoosh application code. "notifications": [{ "send_date": "now", // required. YYYY-MM-DD HH:mm OR 'now' "preset": "ERXXX-32XXX", // required. Copy Email preset code from the URL bar of // the Email Content editor page in Pushwoosh Control Panel. "subject": { // optional. Email message subject line. "de": "subject de", "en": "subject en" }, "content": { // optional. Email body content. "de": "de Hello, moto", "default": "default Hello, moto" }, "attachments": [{ // optional. Email attachments "name": "image.png", // "name" - file name "content": "iVBANA...AFTkuQmwC" // "content" - base64 encoded content of the file }, { "name": "file.pdf", "content": "JVBERi...AFTarEGC" }], "list_unsubscribe": "URL", // optional. Allow to set custom URL for "Link-Unsubscribe" header "campaign": "CAMPAIGN_CODE", // optional. To assign this email message to a particular campaign, // add a campaign code here. "ignore_user_timezone": true, // optional. "timezone": "America/New_York", // optional. Specify to send the message according to // timezone set on user's device. "filter": "FILTER_NAME", // optional. Send the message to specific users meeting filter conditions. "devices": [ // optional. Specify email addresses to send targeted email messages. "email_address1", // Not more than 1000 addresses in an array. "email_address2" // If set, the message will only be sent to the addresses on ], // the list. Ignored if the Application Group is used. "use_auto_registration": true, // optional. Automatically register emails specified in "devices" parameter "users": [ // optional. If set, the email message will only be delivered to the "userId1", // specified user IDs (registered via /registerEmail call). "userId2" // Not more than 1000 user IDs in an array. ], // If the "devices" parameter is specified, // the "users" parameter will be ignored. "dynamic_content_placeholders": { // optional. Placeholders for dynamic content instead of device tag values. "firstname": "John", "firstname_en": "John" }, "conditions": [ // optional. Segmentation conditions, see remark below. ["Country", "EQ", "BR"], ["Language", "EQ", "pt"] ], "from": { // optional. Specify a sender name and sender email address "name": "alias from", // to replace the default "From name" and "From email" "email": "from-email@email.com" // set up in application properties. }, "reply-to": { // optional. Specify an email address to replace the "name": "alias reply to ", // default "Reply to" set up in application properties. "email": "reply-to@email.com" }, "bcc": [ // optional. BCC: array of email addresses that receive a copy without other recipients seeing them. "bcc1@example.com", "bcc2@example.com" ], "email_type": "marketing", // optional. "marketing" or "transactional". // If omitted, users with PW_ControlGroup: true will not receive the message. "email_category": "category name",// required when email_type is "marketing". Category name. "transactionId": "unique UUID", // optional. Unique message identifier to prevent re-sending // in case of network problems. Stored on the side // of Pushwoosh for 5 minutes. // Frequency capping params. Ensure that Global frequency capping is configured in the Control Panel. // Frequency capping does not apply to transactional messages. // In all other cases, including omitted "email_type", frequency capping applies. "capping_days": 30, // optional. Amount of days for frequency capping (max 30 days) "capping_count": 10, // optional. The max number of emails that can be sent from a // specific app to a particular device within a 'capping_days' // period. In case the message created exceeds the // 'capping_count' limit for a device, it won't // be sent to that device. "capping_exclude": true, // optional. If set to true, this email will not // be counted towards the capping for future emails. "capping_avoid": true, // optional. If set to true, capping will not be applied to // this specific email. "send_rate": 100, // optional. Throttling limit. // Limit how many messages can be sent per second across all users. // Helps prevent backend overload during high-volume sends. "send_rate_avoid": true, // optional. If set to true, throttling limit will not be applied to // this specific email. }] } } ``` ### Response examples * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` * 403 ```json { "status_code": 403, "status_message": "Token restrictions forbid this operation", "response": null } ``` ### Tag conditions Each tag condition is an array like `[tagName, operator, operand]` where * tagName: name of a tag * operator: “EQ” | “IN” | “NOTEQ” | “NOTIN” | “LTE” | “GTE” | “BETWEEN” * operand: string | integer | array | date #### Operand description * EQ: tag value is equal to operand; * IN: tag value intersects with operand (operand must always be an array); * NOTEQ: tag value is not equal to an operand; * NOTIN: tag value does not intersect with operand (operand must always be an array); * GTE: tag value is greater than or equal to operand; * LTE: tag value is less than or equal to operand; * BETWEEN: tag value is greater than or equal to min operand value but less than or equal to max operand value (operand must always be an array). #### String tags Valid operators: EQ, IN, NOTEQ, NOTIN\ Valid operands: * EQ, NOTEQ: operand must be a string; * IN, NOTIN: operand must be an array of strings like `["value 1", "value 2", "value N"]`; #### Integer tags Valid operators: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE\ Valid operands: * EQ, NOTEQ, GTE, LTE: operand must be an integer; * IN, NOTIN: operand must be an array of integers like `[value 1, value 2, value N]`; * BETWEEN: operand must be an array of integers like `[min_value, max_value]`. #### Date tags Valid operators: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE\ Valid operands: * `"YYYY-MM-DD 00:00"` (string) * unix timestamp `1234567890` (integer) * `"N days ago"` (string) for operators EQ, BETWEEN, GTE, LTE #### Boolean tags Valid operators: EQ\ Valid operands: `0, 1, true, false` #### List tags Valid operators: IN\ Valid operands: operand must be an array of strings like `["value 1", "value 2", "value N"]`. Danger Remember that “filter” and “conditions” parameters should not be used together.\ Also, both of them **will be ignored**, if the “devices” parameter is used in the same request. Note **Country and Language tags** Language tag value is a lowercase two-letter code according to [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)\ Country tag value is an UPPERCASE two-letter code according to [ISO_3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)\ For example, to send push a notification to Portuguese-speaking subscribers in Brazil, you will need to specify the following condition: `"conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]` ## registerEmail Registers email address for the app. `POST` `https://api.pushwoosh.com/json/1.3/registerEmail` #### Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | #### Request body | Name | Type | Description | | ------------- | ------- | --------------------------------------------------------------------------------------------------- | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | email* | string | Email address. | | language | string | Language locale of the device. Must be a lowercase two-letter code according to ISO-639-1 standard. | | userId | string | [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) to associate with the email address. | | tz_offset | integer | Timezone offset in seconds. | | tags | object | Tag values to assign to the device registered. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` * 210 ```json { "status_code": 210, "status_message": "this hwid (email) is blacklisted", "response": null } ``` * 400 ```json { "status_code": 400, "status_message": "Missing required argument: email", "response": null } ``` * 403 ```json { "status_code": 403, "status_message": "Token restrictions forbid this operation", "response": null } ``` * 500 ```json { "status_code": 500, "status_message": "Internal server error", "response": null } ``` Example ```json { "request": { "application": "APPLICATION_CODE", // required. Pushwoosh application code. "email":"email@domain.com", // required. Email address to be registered. "language": "en", // optional. Language locale. "userId": "userId", // optional. User ID to associate with the email address. "tz_offset": 3600, // optional. Timezone offset in seconds. "tags": { // optional. Tag values to set for the device registered. "StringTag": "string value", "IntegerTag": 42, "ListTag": ["string1","string2"], // sets the list of values for Tags of List type "DateTag": "2024-10-02 22:11", // note the time should be in UTC "BooleanTag": true // valid values are: true, false } } } ``` #### Response codes The public API returns the outcome in `status_code`. Use the table below to decide whether a failed call should be retried. | `status_code` | Meaning | Retry? | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `200` | Success — the email address is registered. | No — done. | | `210` | Argument/validation error — the request was understood but rejected (blacklisted address, invalid or disposable email, wrong platform for the account’s plan). See [210 error messages](https://docs.pushwoosh.com/developer/api-reference/email-api/#210-error-messages) below. | **No** — the same request returns the same `210`. Log the address and skip it. | | `400` | Malformed request — invalid JSON or a missing required field. | No — fix the request, don’t repeat it. | | `403` | Forbidden — invalid or restricted Device API token. | No — fix authorization. | | `500` | Internal server error — temporary infrastructure issue or timeout. | **Yes**, with exponential backoff — the only transient case. | Tip Retry only `500` responses, using exponential backoff — it’s the only transient case. A `210`, `400`, or `403` is final: the server understood your request and rejected it, so repeating it unchanged returns the same result. Log the address (for `210`) or fix the request/token (for `400`/`403`) instead. #### 210 error messages A `210` response carries the specific reason in `status_message`. | `status_message` | Meaning | | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `this hwid (email) is blacklisted` | The address is on the suppression list after a permanent (hard) bounce and won’t be re-registered. | | `hwid (email) is invalid` / `has invalid semantic` | The address fails validation. | | `hwid (email) is empty` | No address was provided. | | `hwid (email) has invalid count of parts` | Missing or extra `@`. | | `hwid (email) has invalid local part` | The part before `@` is invalid. | | `hwid (email) has invalid domain part` | The domain part is invalid. | | `hwid (email) has disposable domain` | The address uses a disposable/temporary email domain (e.g. 10minutemail). | | `hwid is not valid` | The `hwid` itself is malformed. | | `only email platform allowed for Email Only subscription` | The account is on an Email Only plan and can’t register non-email devices. | Note Only **permanent (hard) bounces** add an address to the blacklist. Soft bounces and spam complaints do **not** block `registerEmail` — only `this hwid (email) is blacklisted` reflects suppression. ## deleteEmail Removes email address from your user base. `POST` `https://api.pushwoosh.com/json/1.3/deleteEmail` #### Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | #### Request body | Name | Type | Description | | ----------- | ------ | ---------------------------------------------------------------------------------------------------- | | application | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | email | string | Email address used in [`/registerEmail`](https://docs.pushwoosh.com/developer/api-reference/email-api/#registeremail) request. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` Example ```json { "request": { "application": "APPLICATION_CODE", // required. Pushwoosh application code "email": "email@domain.com" // required. Email to delete from app subscribers. } } ``` ## setEmailTags Sets tag values for the email address. `POST` `https://api.pushwoosh.com/json/1.3/setEmailTags` #### Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | #### Request body | Name | Type | Description | | ----------- | ------ | ----------------------------------------------------------------------------------------------- | | application | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | email | string | Email address. | | tags | object | JSON object of tags to set, send ‘null’ to remove the value. | | userId | string | [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) associated with the email address. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "skipped": [] } } ``` Example ```json { "request": { "email": "email@domain.com", // required. Email address to set tags for. "application": "APPLICATION_CODE", // required. Pushwoosh application code. "tags": { "StringTag": "string value", "IntegerTag": 42, "ListTag": ["string1", "string2"], "DateTag": "2024-10-02 22:11", // time in UTC "BooleanTag": true // valid values are: true, false }, "userId": "userId" // optional. User ID associated with the email address. } } ``` Note For other device types will be returned 200 OK, though tags won’t be saved. Caution Please avoid setting more than 50 tag values in a single `/setEmailTags` request. ## registerEmailUser Associates an external [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) with a specified email address. `POST` `https://api.pushwoosh.com/json/1.3/registerEmailUser` Note Please note that this method **does not register an email address** in your user base; it should be used only for assigning user IDs to email addresses that have been registered already by `/registerEmail` request. Can be used in `/createEmailMessage` API call (the ‘users’ parameter). #### Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | #### Request body | Name | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------------- | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | email* | string | Email address. | | userId* | string | [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) to associate with the email address. | | tz_offset | integer | Timezone offset in seconds. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` * 400 ```json { "status_code": 400, "status_message": "Request format is not valid." } ``` * 403 ```json { "status_code": 403, "status_message": "Forbidden." } ``` Example ```json { "request": { "application": "APPLICATION_CODE", // required. Pushwoosh application code. "email": "email@domain.com", // required. User email address. "userId": "userId", // required. User ID to associate with the email address. "tz_offset": 3600 // optional. Timezone offset in seconds. } } ``` Note To retrieve data on soft bounces, hard bounces, and email complaints, including the date, email address, and reason for each bounce, use the [BouncedEmails](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#bouncedemails) method. --- # Email Templates API **URL:** https://docs.pushwoosh.com/developer/api-reference/email-templates-api/ Create, retrieve, list, update, delete, and clone Pushwoosh email templates through a REST API. --- The Email Templates API manages the reusable email templates behind an application’s email presets — the same templates you build in the Control Panel’s email editor. Each template stores per-locale subjects, sender info, and editor content, and is identified by the code of the email preset it’s connected to. Use that code to send the template through [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) (email payload [`email_template`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/email-payload-reference/#emailpayload)) or a Customer Journey [Send email point](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/#messaging-points). ## Base URL ```plaintext https://rpc-api.svc-nue.pushwoosh.com ``` All endpoints are served over HTTPS. Requests and responses use `application/json` unless noted otherwise. ## Authentication Every request must include an `Authorization` header with your [Server API token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#server-api-token): ```plaintext Authorization: Api YOUR_API_TOKEN ``` ## Conventions * **Field naming:** request bodies and query/path parameters accept `lowerCamelCase` (for example, `previewSettings`, `searchByLabel`, `includeHtml`) — the server unmarshals either casing. Responses are always marshaled using the proto field names, in `snake_case` (`per_page`, `email_template`, `sender_info`, `preview_settings`, and so on). The response examples and the [object reference](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#object-reference) below use that casing. * **`code`:** every template response carries the code of its connected email preset, not an internal template ID. Pass this same code to `Get`, `Update`, `Delete`, and to the messaging/journey APIs above. * **Unpopulated fields:** responses include all fields, even when empty or zero-valued. ### Error responses | HTTP status | Meaning | | :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | | `400 Bad Request` | Invalid argument — a required field is missing or malformed, or a precondition failed (for example, deleting a template still used by a journey). | | `401 Unauthorized` | Missing or invalid `Authorization` header. | | `403 Forbidden` | The application or preset does not belong to the caller’s account. | | `404 Not Found` | The template, preset, or application was not found. | | `500 Internal Server Error` | Unexpected server-side failure. | ## Endpoints | Method | Path | Description | | :------- | :---------------------------- | :------------------------------------------ | | `POST` | `/api/email_templates` | Create a new email template | | `GET` | `/api/email_templates` | List an application’s email templates | | `GET` | `/api/email_templates/{code}` | Get a single email template | | `PUT` | `/api/email_templates/{code}` | Update an email template | | `DELETE` | `/api/email_templates/{code}` | Delete an email template | | `POST` | `/api/email_templates:clone` | Clone an email template into an application | ## Create Creates a new email template — its editor content plus a connected email preset — in an application, and returns the generated template code. `POST` `/api/email_templates` ### Request body | Parameter | Type | Required | Description | | :---------------- | :--------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `application` | string | Yes | The [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) to create the template in. | | `name` | string | Yes | Template name, 1–255 characters. | | `content` | object | Yes | The [email content object](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#email-content-object). | | `label` | string | No | Free-text label, up to 255 characters. | | `categories` | array of strings | No | Category names to tag the template with. | | `previewSettings` | object | No | Arbitrary editor preview settings, stored and returned as-is. | | `system` | boolean | No | Marks the template as a system template — an internal feature, e.g. a synced-block fragment. System templates are hidden from `List` (see note below), but stay reachable by code. Defaults to `false`. | ##### Request example ```json { "application": "XXXXX-XXXXX", "name": "Welcome email", "label": "onboarding", "categories": ["lifecycle"], "content": { "senderInfo": { "from": { "email": "hello@acme.com", "name": "Acme" }, "replyTo": { "email": "support@acme.com", "name": "Acme Support" } }, "subject": { "en": "Welcome to Acme!", "default": "Welcome to Acme!" }, "mjml": { "mjml": "Welcome, {name|string|there}!", "html": "...", "localizationData": { "default": { "name": "there" } }, "settings": {} } } } ``` ### Response Returns `{ "email_template": { ... } }` — the created [email template object](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#email-template-object), but **without** `content` (this endpoint doesn’t echo it back). Call [Get](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#get) with the returned `code` if you need to read the content back. ## List Lists an application’s email templates — metadata only, no content — with paging, ordering, and filtering by name, label, or category. `GET` `/api/email_templates` ### Query parameters | Parameter | Type | Required | Description | | :-------------------- | :--------------- | :------- | :---------------------------------------------------------------------------------------------------------------------- | | `application` | string | Yes | The application code to list templates for. | | `orderBy` | string | No | `NAME` (default), `CREATED`, or `UPDATED`. | | `orderDirection` | string | No | `ASC` (default) or `DESC`. | | `page` | integer | No | Zero-based page index. | | `perPage` | integer | No | Page size. Defaults to `100` when omitted or `0`. This endpoint doesn’t enforce an explicit maximum. | | `searchByName` | string | No | Substring match (`like %value%`) against the template’s name **or** its code — either matching is enough. | | `searchByLabel` | string | No | Substring match on label (`like %label%`), or exact match when `strictSearchByLabel` is `true`. | | `strictSearchByLabel` | boolean | No | Use exact-match instead of substring for `searchByLabel`. | | `searchByCategory` | array of strings | No | Repeat the parameter to filter by any of several categories, e.g. `?searchByCategory=lifecycle&searchByCategory=promo`. | Note System templates (created with `system: true`) are never returned by `List`, regardless of filters. ### Response | Field | Type | Description | | :---------------- | :--------------- | :------------------------------------------------------------------------------------------------------- | | `email_templates` | array of objects | The current page of [email template objects](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#email-template-object). `content` is `null` on every item. | | `page` | integer | The returned page index. | | `per_page` | integer | The page size used for this response. | | `total` | integer | Total number of templates matching the filters, across all pages. | ##### Response example ```json { "email_templates": [ { "code": "AAAAA-BBBBB", "name": "Welcome email", "label": "onboarding", "categories": ["lifecycle"] } ], "page": 0, "per_page": 100, "total": 1 } ``` ## Get Returns a single email template by its code, including sender info, per-locale subjects, and the full editor content. `GET` `/api/email_templates/{code}` ### Path parameters | Parameter | Type | Description | | :-------- | :----- | :----------------------------------------------------- | | `code` | string | The template’s code (its connected email preset code). | ### Query parameters | Parameter | Type | Required | Description | | :------------ | :------ | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `includeHtml` | boolean | No | Whether to return the rendered `html` alongside the editor content. Defaults to `true`. Set to `false` to skip it — it’s typically over half the payload, and the editor content already describes the template. | ### Response Returns `{ "email_template": { ... } }`, the full [email template object](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#email-template-object). ## Update Updates an existing email template by code, overwriting the supplied fields. `PUT` `/api/email_templates/{code}` ### Path parameters | Parameter | Type | Description | | :-------- | :----- | :----------------------------- | | `code` | string | The template’s code to update. | ### Request body | Parameter | Type | Required | Description | | :---------------- | :--------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------- | | `name` | string | No | New name, 1–255 characters. Omit to keep the current name. | | `content` | object | No | New [email content object](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#email-content-object), replacing the stored content in full. Omit to leave the content unchanged. | | `label` | string | No | New label. Always overwritten — omit or send `""` to clear it. | | `categories` | array of strings | No | New full set of category names. Omit to leave categories unchanged; send `[]` to clear them. | | `previewSettings` | object | No | New preview settings. Omit to leave unchanged. | ##### Request example ```json { "name": "Welcome email v2", "label": "onboarding", "content": { "senderInfo": { "from": { "email": "hello@acme.com", "name": "Acme" } }, "subject": { "default": "Welcome to Acme — updated!" }, "mjml": { "mjml": "...", "html": "...", "localizationData": {}, "settings": {} } } } ``` ### Response Returns `{ "email_template": { ... } }` — the updated [email template object](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#email-template-object), also **without** `content`. Call [Get](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#get) if you need to read the content back. ## Delete Deletes an email template and its connected preset by code, removing the stored content. `DELETE` `/api/email_templates/{code}` Caution Fails with `400 Bad Request` if the template is used by a `send_email` point in a running or paused journey — remove or repoint that point first via [Update](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/create-update/#update). This cannot be undone. ### Path parameters | Parameter | Type | Description | | :-------- | :----- | :----------------------------- | | `code` | string | The template’s code to delete. | ### Response An empty object on success: `{}`. ## Clone Clones an email template — its content and preset — into a destination application, optionally under a new name. `POST` `/api/email_templates:clone` Note Only the `default` (or `en`, used as a fallback) locale subject is preserved on the clone; other localized subjects are dropped. ### Request body | Parameter | Type | Required | Description | | :---------------- | :----- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `emailPresetCode` | string | Yes | The template’s `code` (as returned by `Create`, `Get`, `List`, or `Update`) to clone. Named `emailPresetCode` here because it’s the code of the connected email preset — see [Conventions](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#conventions). | | `application` | string | Yes | Destination application code. Can be the same application, or a different one owned by the same account. | | `name` | string | No | Name for the clone, 1–255 characters. Defaults to the source template’s name. | ##### Request example ```json { "emailPresetCode": "AAAAA-BBBBB", "application": "YYYYY-YYYYY", "name": "Welcome email (copy)" } ``` ### Response | Field | Type | Description | | :------------------ | :----- | :----------------------------------------------------------------------------------- | | `email_preset_code` | string | The new template’s `code` — the same identifier `Get`/`Update`/`Delete` call `code`. | ## Object reference Field names below match what `Get`, `List`, `Update`, and `Create` actually return — `snake_case` proto field names (see [Conventions](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#conventions)). When you send these same structures back in a request body (`Create`, `Update`), the `lowerCamelCase` form used in the request examples above works too; the server accepts either casing on input. ### Email template object | Field | Type | Description | | :----------------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------ | | `code` | string | Code of the connected email preset. Identifies this template everywhere else in the API. | | `name` | string | Template name. | | `label` | string | Free-text label. | | `categories` | array of strings | Category names. | | `content` | object | The [email content object](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#email-content-object). Populated only by `Get`; `null` in `Create`, `List`, and `Update` responses. | | `preview_settings` | object | Arbitrary editor preview settings. | | `created` | string (RFC 3339) | Creation timestamp. | | `updated` | string (RFC 3339) | Last update timestamp. | ### Email content object | Field | Type | Description | | :------------------------------------------------------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sender_info` | object | [Sender info object](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#sender-info-object) — `from` and `reply_to` addresses. | | `subject` | object (map) | Per-locale subject, e.g. `{ "en": "Subject", "default": "Subject" }`. | | `unlayer` / `pushwoosh` / `mjml` / `smartcards` / `vibeblocks` | object | The editor content. **Exactly one** of these must be set — it selects which editor produced (and will render) the template. See [editor kinds](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#editor-kinds) below. | Caution The proto also defines a `raw` editor kind (per-locale HTML with no editor state). The API currently rejects it on `Create`/`Update` with `400 Bad Request: raw content not supported` — don’t use it. #### Editor kinds | Kind | Field | Required sub-fields | Description | | :----------- | :---------------------------------------------- | :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | | `unlayer` | `html`, `localization_data`, `editor_config` | `editor_config`, `localization_data` | Drag-and-drop block editor (Unlayer). `editor_config` is the Unlayer design JSON. | | `pushwoosh` | `html`, `localization_data` | `localization_data` | Pushwoosh’s own HTML-based editor. | | `mjml` | `mjml`, `html`, `localization_data`, `settings` | `mjml`, `localization_data`, `settings` | [MJML](https://mjml.io/) source, plus the last-rendered `html`. Recommended for programmatic/API-authored templates. | | `smartcards` | `html`, `localization_data`, `content` | `content`, `localization_data` | Smart Cards block editor; `content` is its editor-specific JSON. | | `vibeblocks` | `html`, `localization_data`, `content` | `content`, `localization_data` | Vibeblocks block editor; `content` is its editor-specific JSON. | In every kind, `html` is the rendered output. `localization_data` is that editor’s own per-locale content: an object keyed by locale code (`en`, `es`, `default`, …), where each value is that locale’s copy of the editor’s fields. Its inner shape is editor-specific and opaque to this API — the API stores and returns it as-is. It’s required on `Create`/`Update` for every kind (send `{}` if there’s nothing to localize). Note Whenever the API returns `content` (currently only [Get](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#get), since [Create](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#create) and [Update](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#update) don’t echo it back), it guarantees one locale is exposed as `default`: if you didn’t send a `default` key yourself, it promotes `en` (or, failing that, whichever locale key comes first) to `default`, renaming it — every other locale you sent is kept as-is. `subject` gets the same treatment. This is different from [Clone](https://docs.pushwoosh.com/developer/api-reference/email-templates-api/#clone), which keeps only that one default-locale value and drops the rest. This rename is only applied when building the response — but it’s not undone on write. If you take a `Get` response as-is and send it straight to `Update`, the promoted key (e.g. `en`) is now literally `default`, and `Update` stores exactly what you send: the original `en` key is gone from then on, permanently. If you need to keep the original locale key, rename `default` back to it yourself before calling `Update`. Text inside `html`, `mjml`, or a `localization_data` value can include [Dynamic Content](https://docs.pushwoosh.com/developer/guides/personalization/dynamic-content/) tags, e.g. `{name|string|there}` — those resolve against the recipient’s device Tags when the email is actually sent. This API doesn’t resolve them; it just stores and returns whatever text you put there. ### Sender info object | Field | Type | Description | | :--------- | :----- | :-------------------------------------------------------- | | `from` | object | `{ "email": string, "name": string }` — sender address. | | `reply_to` | object | `{ "email": string, "name": string }` — reply-to address. | Both `email` sub-fields, when non-empty, must be valid email addresses. ## Related [Notify ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) [Email payload reference ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/email-payload-reference/) [Customer Journey point reference ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/#messaging-points/) --- # Events API **URL:** https://docs.pushwoosh.com/developer/api-reference/events/ Create and manage events using API methods to track user interactions and trigger automated workflows. --- Note To track events triggered by users, call the [/postEvent](https://docs.pushwoosh.com/developer/api-reference/user-centric-api#postevent) method from User Centric API. ## createEvent `POST` `https://api.pushwoosh.com/json/1.3/createEvent` Creates an Event for the app. #### Request Body | Name | Type | Description | | --------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | name | string | Event name, 32 characters max. | | description | string | Event description, 64 characters max. | | eventAttributes | array | Event attributes array. | | trackRevenue | boolean | See Track Event Revenue section. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "event": 351 // Created Event Id } } ``` ```json { "request": { "auth":"yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX", // required. Pushwoosh application code "name": "BasketOpen", // required. 32 characters max. Event name. "description": "Open basket page", // optional. 64 characters max. Event description. "eventAttributes": [{ // optional. Event attributes array "type": 3, // Attribute type. Values: // 1 - integer; // 2 - string; // 3 - list; // 4 - date; // 5 - boolean; // 6 - price; "name": "products" // 64 characters max. Attribute name }, { "type": 5, "name": "delivery" }], "trackRevenue": false } } ``` **Response:** | | | | | --- | --- | -------------------------------------------------------------- | | 200 | 200 | Event successfully created | | 200 | 210 | Argument error. See status_message for more info | | 200 | 403 | Permissions error (for example, when Events limit is exceeded) | | 200 | 404 | Resource not found | | 400 | N/A | Malformed request string | | 500 | 500 | Internal error | --- # Geozones API **URL:** https://docs.pushwoosh.com/developer/api-reference/geozones/ API methods to manage Geozones, including adding, updating, deleting, and retrieving geozone data. --- ## getNearestZone Called internally from the SDK. Retrieves the parameters of the nearest geozone and the distance to it. Also records the device location for geo push notifications. ```http POST https://api.pushwoosh.com/json/1.3/getNearestZone ``` ### Request body parameters | Parameter | Type | Required | Description | | --------------- | -------- | :------: | ------------------------------------------------------------------------------------------------------------------ | | **application** | `string` | Yes | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | **hwid** | `string` | Yes | [Hardware device ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) used in the `/registerDevice` request. | | **lat** | `string` | Yes | Latitude of the device. | | **lng** | `string` | Yes | Longitude of the device. | ### Request example ```json { "request": { "application": "APPLICATION_CODE", "hwid": "HWID", "lat": 10.12345, "lng": 28.12345 } } ``` ### PHP example ```php // See http://gomoob.github.io/php-pushwoosh/get-nearest-zone.html use Gomoob\Pushwoosh\Model\Request\GetNearestZoneRequest; // Creates the request instance $request = GetNearestZoneRequest::create() ->setHwid('HWID') ->setLat(10.12345) ->setLng(28.12345); // Call the '/getNearestZone' Web Service $response = $pushwoosh->getNearestZone($request); if ($response->isOk()) { print 'Zone name : ' . $response->getResponse()->getName(); print 'Latitude : ' . $response->getResponse()->getLat(); print 'Longitude : ' . $response->getResponse()->getLng(); print 'Range : ' . $response->getResponse()->getRange(); print 'Distance : ' . $response->getResponse()->getDistance(); } else { print 'Oops, the operation failed :-('; print 'Status code : ' . $response->getStatusCode(); print 'Status message : ' . $response->getStatusMessage(); } ``` ## addGeoZone Adds a Geozone to a specific app. ```http POST https://api.pushwoosh.com/json/1.3/addGeoZone ``` ### Request body parameters | Parameter | Type | Required | Description | | ----------------------- | ------------------ | :--------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **auth** | `string` | Yes | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | **application** | `string` | Yes | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | **geozones** | `array` | Yes | Geozone parameters as a JSON array. | | **geozones.name** | `string` | Yes | Geozone name. | | **geozones.lat** | `string` | Yes | Geozone latitude. | | **geozones.lng** | `string` | Yes | Geozone longitude. | | **geozones.cooldown** | `integer` | Yes | Silent period after sending a notification (in seconds). | | **geozones.range** | `integer` | Yes | Geozone range in meters. Minimum 50. | | **geozones.content** | `string or object` | Required if `presetCode` is empty. | Geozone message content. | | **geozones.presetCode** | `string` | Required if `content` is empty. | [Push preset](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#preset-code) to use instead of `content`. | | **geozones.cluster** | `string` | No | Specify `null` to unbind a cluster from the Geozone. | | **geozones.campaign** | `string` | No | Specify `null` to unbind a campaign from the Geozone. If omitted, the campaign value remains unchanged. Note: Has higher priority than the campaign in the preset. | | **geozones.timetable** | `object` | No | Sets timetable intervals. | ### Request example ```json { "request": { "auth": "yxoPUlwqm............pIyEX4H", // API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX", // Pushwoosh application code "geozones": [{ "name": "Statue of George", // required. Geozone name. "lat": "40.70087797", // required. Geozone latitude. "lng": "-73.931851387", // required. Geozone longitude. "cooldown": 60, // in seconds, required. Silent period after sending a notification "range": 50, // in meters, minimum 50, required. Range of the geozone. "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", // or object "presetCode": "AAAAA-BBBBB", // optional. Push preset could be used instead of content "cluster": "GEOZONE CLUSTER CODE", // optional. Cluster's cooldown period will be applied "campaign": "CAMPAIGN_CODE", // optional. Specify null to unbind Campaign from Geozone "timetable": { // optional "timezone": 1234, // in seconds "Mon": [ // available days: Mon, Tue, Wed, Thu, Fri, Sat, Sun. Push sending { "start": "04:11", "stop": "12:00" } ], "Sun": [ { // one or two intervals "start": "01:11", "stop": "17:00" }, { "start": "18:01", "stop": "23:59" } ] } }] } } ``` ## updateGeoZone Updates Geozone properties. ```http POST https://api.pushwoosh.com/json/1.3/updateGeoZone ``` ### Request body parameters | Parameter | Type | Required | Description | | ------------- | --------- | :------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **auth** | `string` | Yes | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | **geoZoneId** | `string` | Yes | [Geozone ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#geozone-id) from `/addGeoZone` request. | | **name** | `string` | No | New Geozone name. | | **cooldown** | `integer` | No | Cooldown to update, in seconds. | | **status** | `integer` | No | 0 - deactivated, 1 - activated. | | **content** | `string` | No | Content for Geozone push notification. Cannot be used with `presetCode`. | | **cluster** | `string` | No | New cluster name. Specify `null` to unbind cluster from Geozone. | | **campaign** | `string` | No | New campaign ID. Specify `null` to unbind Campaign from Geozone. If omitted, Campaign value won’t be changed. Has higher priority than a Campaign from a preset. | | **lat** | `number` | No | Geozone latitude. | | **lng** | `number` | No | Geozone longitude. | | **range** | `integer` | No | New range in meters. | | **timetable** | `object` | No | Geozone timetable. See more info below. | *** ### Request example ```json { "request": { "auth": "yxoPUlwqm............pIyEX4H", // required, API access token from Pushwoosh Control "geoZoneId": 100016750, // required, from /addGeoZone method "name": "new geozone name", // optional "cooldown": 222, // in seconds, optional "status": 0, // optional, 0 - deactivated, 1 - activated "presetCode": "BBBBB-AAAAA", // optional, cannot be used along with "content" "content": "new geozone content", // optional, cannot be used along with "presetCode" "cluster": "GEOZONE CLUSTER CODE", // optional. Specify null to unbind cluster from Geozone "campaign": "CAMPAIGN_CODE", // optional. Specify null to unbind Campaign from Geozone "lat": 10.56, // optional, geozone latitude "lng": 12.523, // optional, geozone longitude "range": 500, // optional, geozone range "timetable": { // optional "timezone": 1234, // in seconds "Mon": [ // available days: Mon, Tue, Wed, Thu, Fri, Sat, Sun. Push sending { "start": "04:11", "stop": "12:00" } ], "Sun": [ { // one or two intervals "start": "01:11", "stop": "17:00" }, { "start": "18:01", "stop": "23:59" } ] } } } ``` ## deleteGeoZone Removes Geozones from the app. ```http POST https://api.pushwoosh.com/json/1.3/deleteGeoZone ``` ### Request body parameters | Parameter | Type | Required | Description | | --------------- | -------- | :------: | ------------------------------------------------------------------------------------------------------------ | | **auth** | `string` | Yes | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | **application** | `string` | Yes | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | **geozones** | `string` | Yes | Array of IDs or a [single ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#geozone-id) of a Geozone to remove. | ### Request example ```json { "request": { "auth": "yxoPUlwqm............pIyEX4H", // required, API access token from Pushwoosh Control "application": "XXXXX-XXXXX", // required, Pushwoosh application code "geozones": [550, 526] // required, geozones IDs } } ``` ## addGeoZoneCluster Adds Geozone Cluster to the app. ```http POST https://api.pushwoosh.com/json/1.3/addGeoZoneCluster ``` ### Request body parameters | Parameter | Type | Required | Description | | --------------- | --------- | :------: | ------------------------------------------------------------------------------------------------------------ | | **auth** | `string` | Yes | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | **application** | `string` | Yes | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | **name** | `string` | Yes | Cluster name. | | **cooldown** | `integer` | Yes | A delay before a single user can receive the same message from the Geozone Cluster, in seconds. | ### Request example ```json { "request": { "auth": "yxoPUlwqm............pIyEX4H", // required, API access token from Pushwoosh Control "application": "XXXXX-XXXXX", // required, Pushwoosh application code "name": "Raccoon city", // required, cluster name "cooldown": 3210 // required, in seconds } } ``` ## deleteGeoZoneCluster Removes a Geozone Cluster from the app. ```http POST https://api.pushwoosh.com/json/1.3/deleteGeoZoneCluster ``` ### Request body parameters | Parameter | Type | Required | Description | | ------------------ | -------- | :------: | ------------------------------------------------------------------------------------------------------------ | | **auth** | `string` | Yes | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | **application** | `string` | Yes | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | **geoZoneCluster** | `string` | Yes | ID of the Geozone cluster to remove. | ### Request example ```json { "request": { "auth": "yxoPUlwqm............pIyEX4H", // required, API access token from Pushwoosh Control "application": "XXXXX-XXXXX", // required, Pushwoosh application code "geoZoneCluster": "EA1CE-69405" // required, cluster ID obtained from the /addGeoZoneCluster request } } ``` ## listGeoZones Retrieves a list of Geozones for the app. ```http POST https://api.pushwoosh.com/json/1.3/listGeoZones ``` ### Request body parameters | Parameter | Type | Required | Description | | --------------- | -------- | :------: | ------------------------------------------------------------------------------------------------------------ | | **auth** | `string` | Yes | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | **application** | `string` | Yes | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | ### Request example ```json { "request": { "auth": "yxoPUlwqm............pIyEX4H", // required, API access token from Pushwoosh Control "application": "XXXXX-XXXXX" // required, Pushwoosh application code } } ``` ## listGeoZoneClusters Retrieves a list of Geozone clusters for the app. ```http POST https://api.pushwoosh.com/json/1.3/listGeoZoneClusters ``` ### Request body parameters | Parameter | Type | Required | Description | | --------------- | -------- | :------: | ------------------------------------------------------------------------------------------------------------ | | **auth** | `string` | Yes | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | **application** | `string` | Yes | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | ### Request example ```json { "request": { "auth": "yxoPUlwqm............pIyEX4H", // required, API access token from Pushwoosh Control "application": "XXXXX-XXXXX" // required, Pushwoosh application code } } ``` --- # Get started with Pushwoosh API **URL:** https://docs.pushwoosh.com/developer/api-reference/getting-started-with-pushwoosh-api/ Learn how to get started with Pushwoosh API, including authentication, making your first request, and understanding API responses. --- In this post we’ll walk you through the initial steps to set up and use the Pushwoosh API effectively. If you’re new to Pushwoosh or haven’t explored the API before, this guide will help you get started on the right track. ## Step 1: Sign up for access To get started with the new Pushwoosh API, you need a Pushwoosh account. Sign up for one if you do not have it yet. ## Step 2. Retrieve your API Access Token The API Access Token is a unique identifier assigned to your Pushwoosh account, allowing you to manage your projects through the API. This token is essential for various actions such as account modifications, sending messages, and editing projects. By default, your Pushwoosh account has an API Access Token for the Pushwoosh Demo App which you can use for experimentation. [Learn how to get your API Access token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/) ## Step 3. Make your first API request Once you have your Pushwoosh account and your API Access Token, you’re ready to explore the capabilities of the Pushwoosh API. To get started, select the relevant API method that aligns with the specific task you intend to accomplish and send your first API request. You can find the full list of API methods available [here](https://docs.pushwoosh.com/developer/api-reference/api-methods-reference-index). It’s crucial to include the `auth` parameter in your request by pasting your API Access Token. This authentication process guarantees that your requests are securely authorized and processed by Pushwoosh’s servers. --- # Google Wallet API **URL:** https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/ Create, update, and manage Google Wallet passes programmatically through the Pushwoosh Google Wallet API. --- The Google Wallet API lets you create, update, list, and manage [Google Wallet passes](https://docs.pushwoosh.com/product/messaging-channels/google-wallet-passes/) programmatically. It supports the same operations the [pass builder](https://docs.pushwoosh.com/product/messaging-channels/google-wallet-passes/pass-builder/) in the Control Panel performs. Use it to issue loyalty cards, offers, gift cards, event tickets, flight boarding passes, transit tickets, and generic passes, and to push live updates to passes already saved on your users’ devices. Prerequisite: Google Wallet configuration Before you can create passes for an application, a Google Wallet **Issuer ID** and **service account key** must be configured for that application in the Pushwoosh Control Panel. Without them, `create` and `update` requests fail. See [Google Wallet pass configuration for Android](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/). ## Base URL ```plaintext https://apple-passkit.svc-nue.pushwoosh.com ``` All endpoints are served over HTTPS. Requests and responses use `application/json` unless noted otherwise. ## Authentication Every request must include an `Authorization` header with your [Pushwoosh API access token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/): ```plaintext Authorization: Token ``` The account that owns the token must own the application referenced by `applicationCode`. A request for an application that belongs to another account returns `403 Forbidden`. ## Conventions * **Field naming:** JSON fields use `lowerCamelCase` (for example, `serialNumber`, `hexBackgroundColor`, `logoUrl`). * **Unpopulated fields:** responses include all fields, even when empty or zero-valued. * **Identity:** the `serialNumber` is always assigned by the server when a pass is created. Any value you send on create is ignored. The full Google Wallet object id is `{issuerId}.{serialNumber}`. * **Images:** `logoUrl` and `heroImageUrl` are public HTTPS URLs to images Google fetches—not uploaded files. * **Pass style:** exactly one style object (`generic`, `offer`, `loyalty`, `eventTicket`, `giftCard`, `flight`, or `transit`) must be set on a pass. The style cannot change after creation. ### Error responses | HTTP status | Meaning | | :------------------------ | :--------------------------------------------------------- | | `400 Bad Request` | Invalid argument—a required field is missing or malformed. | | `401 Unauthorized` | Missing or invalid `Authorization` header. | | `403 Forbidden` | The application does not belong to the caller’s account. | | `404 Not Found` | The pass, template, or application was not found. | | `503 Service Unavailable` | The service is at capacity or temporarily unavailable. | ## Endpoints | Method | Path | Description | | :------- | :------------------------------------------------------------ | :-------------------------------------------------- | | `POST` | `/api/google/pass/validate` | Validate a pass configuration | | `POST` | `/api/google/pass/create` | Create a new pass object and get a save link | | `POST` | `/api/google/pass/update/{serialNumber}` | Update an existing pass; Google delivers the change | | `GET` | `/api/google/pass/{applicationCode}/{serialNumber}/save-link` | Get an “Add to Google Wallet” save link | | `GET` | `/api/google/pass/{applicationCode}/{serialNumber}` | Get a single pass | | `GET` | `/api/google/passes` | List all passes for an application | | `POST` | `/api/google/pass/{applicationCode}/{serialNumber}/state` | Activate or invalidate a pass | | `DELETE` | `/api/google/pass/{applicationCode}/{serialNumber}` | Delete a pass | | `GET` | `/api/google/config` | Get the application’s Google Wallet configuration | | `GET` | `/api/google/templates` | List available pass templates | | `GET` | `/api/google/templates/{filename}` | Get a single template | ## Create a pass Creates the pass class and object in Google Wallet, then returns the server-assigned serial number, the full object id, and an “Add to Google Wallet” save link. `POST` `/api/google/pass/create` ### Request body | Parameter | Type | Required | Description | | :---------------- | :----- | :------- | :------------------------------------------------------------------------------------------------ | | `pass` | object | Yes | The [pass object](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#pass-object) describing the pass. Exactly one style must be set. | | `userId` | string | Yes | The [Pushwoosh User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) the pass is issued to. | | `applicationCode` | string | Yes | The [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). | ##### Request example ```json { "applicationCode": "XXXXX-XXXXX", "userId": "user-123", "pass": { "hexBackgroundColor": "#3c414c", "logoUrl": "https://cdn.acme.com/logo.png", "loyalty": { "programName": "Acme Rewards", "accountName": "Jane Doe", "accountId": "1234567890", "pointsLabel": "Points", "pointsBalance": "1200", "rewardsTier": "Gold" }, "barcode": { "format": "QR_CODE", "value": "1234567890" } } } ``` ### Response | Field | Type | Description | | :------------- | :----- | :--------------------------------------------------------------------- | | `serialNumber` | string | Server-assigned unique identity of the created pass. | | `objectId` | string | Full Google Wallet object id: `{issuerId}.{serialNumber}`. | | `saveLink` | string | ”Add to Google Wallet” link: `https://pay.google.com/gp/v/save/{jwt}`. | | `message` | string | Result message. | ##### Response example ```json { "serialNumber": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "objectId": "XXXXXXXXXXXXXXX.XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "saveLink": "https://pay.google.com/gp/v/save/{jwt}", "message": "Pass created successfully" } ``` ## Validate a pass Checks a pass configuration against Google’s requirements without creating it. Useful before calling create. `POST` `/api/google/pass/validate` ### Request body | Parameter | Type | Required | Description | | :-------- | :----- | :------- | :------------------------------------------- | | `pass` | object | Yes | The [pass object](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#pass-object) to validate. | ### Response | Field | Type | Description | | :--------- | :--------------- | :------------------------------------ | | `valid` | boolean | Whether the pass passes validation. | | `errors` | array of strings | Blocking problems that must be fixed. | | `warnings` | array of strings | Non-blocking advisories. | ## Update a pass Patches the pass object with new content. Google then delivers the updated version to every device that saved the pass. Optionally sends an Android notification with the update. `POST` `/api/google/pass/update/{serialNumber}` ### Path parameters | Parameter | Type | Description | | :------------- | :----- | :---------------------------------------------------- | | `serialNumber` | string | The serial number returned when the pass was created. | ### Request body | Parameter | Type | Required | Description | | :---------------- | :------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `updates` | object | Yes | The [pass object](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#pass-object) with the new content. The style cannot change. | | `applicationCode` | string | Yes | The [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). | | `notifyMessage` | string | No | When non-empty, push an Android notification with this text to everyone who saved the pass. Empty means a silent update. | | `notifyOnUpdate` | boolean | No | Request a field-update notification. Only `loyalty`, `eventTicket`, and `flight` passes actually notify; other styles accept the flag but never send one. Notifications fire only within 3 hours of a relevant start time, and Google limits them to 3 notifications per pass per 24 hours. | Two ways to notify on update `notifyMessage` sends a custom Android notification to everyone who saved the pass and works for any pass style. `notifyOnUpdate` asks Google to send its own field-update notification, which only fires for `loyalty`, `eventTicket`, and `flight` passes. ### Response | Field | Type | Description | | :-------- | :------ | :---------------------------- | | `success` | boolean | Whether the update succeeded. | | `message` | string | Result message. | ## Get a save link Returns an “Add to Google Wallet” save link for an already created pass. The pass object must already exist (created via [Create a pass](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#create-a-pass)). `GET` `/api/google/pass/{applicationCode}/{serialNumber}/save-link` ### Response | Field | Type | Description | | :--------- | :----- | :---------------------------------------- | | `saveLink` | string | `https://pay.google.com/gp/v/save/{jwt}`. | Share the link or render it as a QR code Put the `saveLink` behind an “Add to Google Wallet” button, or render it as a QR code with any QR library. When a user opens it, Google prompts them to save the pass and registers their device for updates. ## Get a pass Returns a single stored pass, including its full pass object. `GET` `/api/google/pass/{applicationCode}/{serialNumber}` ### Response Returns `{ "pass": { ... } }`, a single [pass record](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#pass-record-object). ## List passes Returns a paginated, sorted list of the passes stored for an application. `GET` `/api/google/passes?applicationCode=XXXXX-XXXXX&page=0&perPage=20` ### Query parameters | Parameter | Type | Required | Description | | :---------------- | :------ | :------- | :-------------------------------------------------------------------------------------------- | | `applicationCode` | string | Yes | The [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). | | `orderBy` | string | No | Sort field: `UPDATED` (default) or `CREATED`. | | `orderDirection` | string | No | Sort direction: `DESC` (default, newest first) or `ASC`. | | `page` | integer | No | Zero-based page index. Defaults to `0`. | | `perPage` | integer | No | Page size. `0` or omitted uses the server default. | ### Response | Field | Type | Description | | :-------- | :--------------- | :----------------------------------------------------------- | | `passes` | array of objects | The current page of [pass records](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#pass-record-object). | | `page` | integer | The returned page index. | | `perPage` | integer | The page size used for this response. | | `total` | integer | Total number of passes for the application across all pages. | ## Set pass state Activates or invalidates a pass. An invalidated (inactive) pass moves to the user’s **Expired passes** section in Google Wallet; the record is kept so it can be re-activated. `POST` `/api/google/pass/{applicationCode}/{serialNumber}/state` ### Request body | Parameter | Type | Required | Description | | :-------- | :------ | :------- | :--------------------------------------------------------------------- | | `active` | boolean | Yes | `true` sets the pass to `ACTIVE`; `false` invalidates it (`INACTIVE`). | ### Response Returns an empty object `{}` on success. ## Delete a pass Invalidates the pass in Google and removes its stored record in Pushwoosh. `DELETE` `/api/google/pass/{applicationCode}/{serialNumber}` A saved pass cannot be force-removed Google does not allow removing a pass already saved on a user’s device. Delete invalidates the pass (it moves to **Expired passes**) and drops the Pushwoosh record. ### Response Returns an empty object `{}` on success. ## Get configuration Returns the Google Wallet configuration state for an application. `GET` `/api/google/config?applicationCode=XXXXX-XXXXX` ### Response | Field | Type | Description | | :-------------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `hasServiceAccount` | boolean | Whether a service account key is configured. | | `issuerId` | string | The configured [Google Pay & Wallet Console Issuer ID](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/#create-the-issuer-account). | | `serviceAccountEmail` | string | The `client_email` of the configured [service account](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/#create-the-service-account-key). | ## Templates List the available example pass templates, or fetch one as a [pass object](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#pass-object) you can use as a starting point. `GET` `/api/google/templates` — returns `{ "templates": [ { "filename", "name", "description", "style" } ] }`. `GET` `/api/google/templates/{filename}` — returns `{ "template": { ...pass object... } }`. ## Object reference ### Pass object | Field | Type | Description | | :---------------------------------------------------------------------------------- | :----- | :----------------------------------------------------------------------------------------------------- | | `serialNumber` | string | Assigned by the server on create; identifies the pass. | | `generic` / `offer` / `loyalty` / `eventTicket` / `giftCard` / `flight` / `transit` | object | The pass style. **Exactly one** must be set. See the style objects below. | | `hexBackgroundColor` | string | Card background color, `#rrggbb`. | | `logoUrl` | string | Public HTTPS URL of the logo image. Required for loyalty and transit. | | `heroImageUrl` | string | Public HTTPS URL of a wide banner image. | | `barcode` | object | [Barcode](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#barcode-object) shown on the pass. | | `textModules` | array | [Text modules](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#text-module-object) shown in the details view. | | `links` | array | [Link modules](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#link-module-object) shown in the details view. | | `expirationTime` | string | ISO 8601 time when Google auto-expires the pass. Empty means no expiry. | | `appLink` | object | [App link](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#app-link-object): a CTA button on the front of the pass. | | `locations` | array | [Locations](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#location-object) that trigger a geofenced notification (max 10). | | `holdersPolicy` | string | Who may save the pass: `ONE_USER_ALL_DEVICES` (default), `ONE_USER_ONE_DEVICE`, or `MULTIPLE_HOLDERS`. | ### Generic object | Field | Type | Description | | :----------- | :----- | :----------------------------------------------------------------------------------- | | `cardTitle` | string | Required. The issuer/program name at the top of the card. | | `header` | string | Required. The main title of the card. | | `subheader` | string | Secondary title. | | `cardFields` | array | Up to 6 [text modules](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#text-module-object) pinned to the front (up to 3 rows of 2). | ### Offer object | Field | Type | Description | | :------------------ | :----- | :--------------------------------------------------------------------- | | `title` | string | Required. For example, `20% off everything`. | | `provider` | string | Required. The merchant name. | | `details` | string | Offer details. | | `finePrint` | string | Terms and conditions. | | `redemptionChannel` | string | `ONLINE`, `INSTORE`, `BOTH` (default), or `TEMPORARY_PRICE_REDUCTION`. | | `issuerName` | string | Shown on Google’s “issued by” surfaces; defaults to `provider`. | ### Loyalty object | Field | Type | Description | | :----------------- | :----- | :------------------------------------------------ | | `programName` | string | Required. Requires `logoUrl` on the pass. | | `accountName` | string | Member name shown on the card. | | `accountId` | string | Member id shown on the card. | | `pointsLabel` | string | For example, `Points`. Shown only with a balance. | | `pointsBalance` | string | The points balance. | | `rewardsTier` | string | For example, `Gold`. | | `rewardsTierLabel` | string | Label next to the tier; defaults to `Tier`. | | `issuerName` | string | Defaults to `programName`. | ### Event ticket object | Field | Type | Description | | :------------------------------------------------- | :----- | :--------------------------------------------------------------- | | `eventName` | string | Required. | | `venueName` / `venueAddress` | string | Venue details. | | `startDateTime` / `endDateTime` | string | ISO 8601 with offset (for example, `2026-07-01T19:30:00+02:00`). | | `ticketHolderName` / `ticketNumber` / `ticketType` | string | Holder and ticket details. | | `section` / `row` / `seat` / `gate` | string | Seating details. | | `issuerName` | string | Defaults to `eventName`. | ### Gift card object | Field | Type | Description | | :---------------- | :----- | :--------------------------------------------------------------- | | `merchantName` | string | Required. | | `cardNumber` | string | Required. | | `pin` | string | Card PIN. | | `balance` | string | Decimal amount, for example `25.00`. Requires `balanceCurrency`. | | `balanceCurrency` | string | ISO 4217 currency code, for example `USD`. | | `issuerName` | string | Defaults to `merchantName`. | ### Flight object | Field | Type | Description | | :---------------------------------------------------------------- | :----- | :--------------------------------------------------------------------------------------------------------- | | `carrierIataCode` | string | Required. 2-letter IATA code, for example `LX`. | | `airlineName` | string | Airline display name. | | `flightNumber` | string | Required. Digits only, for example `113`. | | `originAirportCode` / `destinationAirportCode` | string | Required. 3-letter IATA codes. | | `originTerminal` / `originGate` / `destinationTerminal` | string | Terminal and gate details. | | `departureDateTime` | string | Required. Origin airport **local** time, ISO 8601 **without** offset (for example, `2026-09-01T06:30:00`). | | `boardingTime` / `arrivalDateTime` | string | Same local format. `arrivalDateTime` is destination local time. | | `passengerName` | string | Required. | | `confirmationCode` / `seatNumber` / `seatClass` / `boardingGroup` | string | Passenger details. | | `issuerName` | string | Defaults to `airlineName`, then the carrier code. | ### Transit object | Field | Type | Description | | :-------------------- | :----- | :--------------------------------------------------------------- | | `transitType` | string | Required. `BUS`, `RAIL`, `TRAM`, `FERRY`, or `OTHER`. | | `transitOperatorName` | string | Required. Requires `logoUrl` on the pass. | | `passengerName` | string | Required. | | `ticketNumber` | string | Ticket number. | | `tripType` | string | `ONE_WAY` (default) or `ROUND_TRIP`. | | `legs` | array | One or more [transit legs](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#transit-leg-object) in travel order. | | `issuerName` | string | Defaults to `transitOperatorName`. | ### Transit leg object | Field | Type | Description | | :-------------------------------------- | :----- | :--------------------------------------------------- | | `originName` / `destinationName` | string | Required. | | `departureDateTime` / `arrivalDateTime` | string | ISO 8601; offset optional (local time when omitted). | | `platform` / `coach` / `seat` | string | Boarding details. | | `fareName` | string | For example, `Anytime Single`. | ### Barcode object | Field | Type | Description | | :-------- | :----- | :------------------------------------------------------------------------------------------ | | `format` | string | `QR_CODE`, `PDF_417`, `AZTEC`, `CODE_128`, `EAN_13`, and other Google Wallet barcode types. | | `value` | string | Data encoded in the barcode. | | `altText` | string | Text shown below the barcode. | ### Text module object | Field | Type | Description | | :------- | :----- | :------------------------ | | `id` | string | Identifier of the module. | | `header` | string | Module heading. | | `body` | string | Module text. | ### Link module object | Field | Type | Description | | :------------ | :----- | :------------------------------------ | | `uri` | string | External link URL. | | `description` | string | Link label shown in the details view. | ### App link object | Field | Type | Description | | :------------------- | :----- | :---------------------------------------------------------------------------------------- | | `uri` | string | Web URL or deep-link target URI. | | `androidPackageName` | string | Optional. When set, opens the Android app. | | `description` | string | Internal description of the target URI (not a visible button label); defaults to the URI. | ### Location object | Field | Type | Description | | :---------- | :----- | :-------------------- | | `latitude` | number | `-90.0` to `+90.0`. | | `longitude` | number | `-180.0` to `+180.0`. | ### Pass record object Returned by list/get endpoints. | Field | Type | Description | | :------------------------ | :----- | :--------------------------------------------------------------------------------------------- | | `serialNumber` | string | Pass serial number. | | `objectId` | string | Full Google Wallet object id `{issuerId}.{serialNumber}`. | | `cardTitle` | string | Display title/header for the pass. | | `header` | string | Secondary display title. | | `userId` | string | [Pushwoosh User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) the pass was issued to. | | `createdAt` / `updatedAt` | string | Creation and last-update timestamps. | | `state` | string | `ACTIVE` or `INACTIVE`. | | `style` | string | `generic`, `offer`, `loyalty`, `eventTicket`, `giftCard`, `flight`, or `transit`. | | `pass` | object | The full [pass object](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/#pass-object), for editing. | --- # iOS Live Activities API **URL:** https://docs.pushwoosh.com/developer/api-reference/ios-live-activities-api/ Create, update, and manage iOS Live Activities using API methods for real-time activity notifications. --- > Apple documentation: > > * [About Live Activities](https://developer.apple.com/design/human-interface-guidelines/live-activities) > * [Updating and ending Live Activities with ActivityKit push notifications](https://developer.apple.com/documentation/activitykit/updating-and-ending-your-live-activity-with-activitykit-push-notifications) ## startLiveActivity `POST` `https://api.pushwoosh.com/json/1.3/startLiveActivity` Allows creating iOS Live Activities. ### Request body | Parameter | Type | Required/Optional | Description | | ------------- | ------ | ----------------- | ---------------------------------------------------------------------------------------------------------------- | | application | String | Required | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | auth | String | Required | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from the Pushwoosh Control Panel. | | notifications | Array | Required | JSON array of message parameters. See details in the Notifications table below. | #### Notifications Parameters used in the `notifications` array: | Parameter | Type | Required/Optional | Description | | ------------------------------ | ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | content | String | Required | Fallback content for devices running iOS versions below 16.1 that do not support Live Activity. On iOS 16.1+ (with Live Activity support), content is sourced from the `live_activity` field. | | title | String | Optional | The title of the notification message. | | live_activity | Object | Required | Live Activity data to create Live Activity in iOS. | | live_activity.content-state | Object | Required | Content for the Live Activity notification. | | live_activity.attributes-type | String | Required | The type of attributes used in the Live Activity. | | live_activity.attributes | Object | Required | Attributes for the Live Activity. | | live_activity_id | String | Required | A unique identifier for the Live Activity. Used to target this activity when calling `updateLiveActivity`. Must be unique per activity session. | | filter | String | Optional | The name of a Pushwoosh filter (segment). See [Segment / Filter name](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#segment--filter-name). The Live Activity will be started on all devices matching this filter. | | devices | Array of Strings | Optional | A list of [device tokens](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#push-token). The Live Activity will be started only on the specified devices. | | send_date | String | Optional | Schedules the push that starts the Live Activity for a specific date and time — works with either `filter` or `devices` targeting. Use format `YYYY-MM-DD HH:mm`, or `now` to start immediately (this is also the default when the parameter is omitted). Must be no more than 1 day in the past or 30 days in the future, otherwise the request is rejected with a validation error. | | timezone | String | Optional | The timezone used to interpret `send_date`. If omitted, `send_date` is interpreted in UTC. | Caution Remote start of a Live Activity via `startLiveActivity` requires **iOS 17.2+** on the device — earlier versions do not support the `pushToStartTokenUpdates` API that this endpoint relies on. See [Start Live Activity with a Remote push notification](https://docs.pushwoosh.com/developer/pushwoosh-sdk/ios-sdk/ios-live-activities/#start-live-activity-with-a-remote-push-notification). When targeting a `filter` (segment), the scheduled send time is when Pushwoosh starts dispatching the push, not a guaranteed delivery instant — for large audiences, delivery to individual devices can lag behind `send_date` by a few minutes, since the send rate for Live Activity pushes can’t be customized with `send_rate`. ### Request example * With filter ```json { "request": { "application": "XXXXX-XXXXX", "auth": "SECRET_API_TOKEN", "notifications": [ { "content": "Your order is being prepared", "title": "Food Delivery", "live_activity": { "event": "start", "title": "Order status", "content-state": { "status": "Third", "estimatedTime": "37 min", "emoji": "👨‍🍳" }, "attributes-type": "FoodDeliveryAttributes", "attributes": {} }, "live_activity_id": "FIRST_LIVE_ACTIVITY", "filter": "FILTER_NAME_1" } ] } } ``` * With devices ```json { "request": { "application": "XXXXX-XXXXX", "auth": "SECRET_API_TOKEN", "notifications": [ { "content": "Your order is being prepared", "title": "Food Delivery", "live_activity": { "event": "start", "title": "Order status", "content-state": { "status": "Third", "estimatedTime": "37 min", "emoji": "👨‍🍳" }, "attributes-type": "FoodDeliveryAttributes", "attributes": {} }, "live_activity_id": "SECOND_LIVE_ACTIVITY", "devices": ["first_third", "second_device"] } ] } } ``` * Scheduled start ```json { "request": { "application": "XXXXX-XXXXX", "auth": "SECRET_API_TOKEN", "notifications": [ { "content": "Your order is being prepared", "title": "Food Delivery", "live_activity": { "event": "start", "title": "Order status", "content-state": { "status": "Third", "estimatedTime": "37 min", "emoji": "👨‍🍳" }, "attributes-type": "FoodDeliveryAttributes", "attributes": {} }, "live_activity_id": "THIRD_LIVE_ACTIVITY", "filter": "FILTER_NAME_1", "send_date": "2026-06-16 16:00" } ] } } ``` ### Response example ```json { "status_code": 200, "status_message": "OK", "response": { "Messages": [ "XXXXX-XXXXXXXX-XXXXXXXX" ] } } ``` > **Note:** > > Read [this article](https://docs.pushwoosh.com/developer/pushwoosh-sdk/ios-sdk/ios-live-activities) to learn more about working with Live Activities using the Pushwoosh iOS SDK. ## updateLiveActivity `POST` `https://api.pushwoosh.com/json/1.3/updateLiveActivity` Allows updating and ending iOS Live Activities ### Request body | Parameter | Type | Required/Optional | Description | | ------------- | ------ | ----------------- | ---------------------------------------------------------------------------------------------------------------- | | auth | String | Required | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from the Pushwoosh Control Panel. | | application | String | Required | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | notifications | Array | Required | JSON array of message parameters. See details in the Notifications table below. | #### Notifications Parameters used in the `notifications` array: | Parameter | Type | Required/Optional | Description | | ------------------------------ | ------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | live_activity | Object | Required | Live Activity data to update Live Activity in iOS. | | live_activity.event | String | Required | Specifies the event type. Use `"update"` to update the Live Activity or `"end"` to close it. | | live_activity.content-state | Object | Required | Object with key-value pairs used to pass data to Live Activity for updating its content. | | live_activity.dismissal-date | Integer | Optional | The time (in seconds) when the Live Activity should end. | | live_activity_id | String | Required | The unique identifier of the Live Activity to update. Must match the `live_activity_id` used in **startLiveActivity**. The update will be delivered to all devices on which this activity was started. | | live_activity.relevance-score | Integer | Optional | Tells the iOS system which Live Activity has higher priority than others. Accepts values from 1 to infinity (values up to 100 are recommended). | | live_activity.stale-date | Integer | Optional | The time (in seconds) that represents the date at which a Live Activity becomes stale, or out of date. | ### Request example ```json { "request": { "application": "XXXXX-XXXXX", "auth": "SECRET_API_TOKEN", "notifications": [ { "live_activity": { "event": "update", "title": "Live Activity Update", "content-state": { "status": "second 66", "estimatedTime": "66 min", "emoji": "👨‍" }, "relevance-score": 60 }, "live_activity_id": "FIRST_LIVE_ACTIVITY" } ] } } ``` ### Response example ```json { "status_code": 200, "status_message": "OK", "response": { "Messages": [ "XXXXX-XXXXXXXX-XXXXXXXX" ] } } ``` > [Read this article](https://docs.pushwoosh.com/developer/pushwoosh-sdk/ios-sdk/ios-live-activities/) to learn more about working with Live Activities using the Pushwoosh iOS SDK. ## Multiple activities per device You can start multiple Live Activities on the same device by calling `startLiveActivity` several times with different `live_activity_id` values. For example, if you start two activities: `FIRST_LIVE_ACTIVITY` with `filter: FILTER_NAME_1` and `SECOND_LIVE_ACTIVITY` with `filter: FILTER_NAME_2`, a device that matches both filters will have both activities running simultaneously. To update one of them, pass its `live_activity_id` to `updateLiveActivity`. The update is delivered to all devices where that activity was created. The other activity is not affected. The `relevance-score` parameter controls display priority when multiple Live Activities are active on the same device. If screen space is limited or activities are grouped, the activity with a higher value is shown with higher priority. --- # Kakao API **URL:** https://docs.pushwoosh.com/developer/api-reference/kakao/ Send personalized Kakao messages to your users using pre-approved templates via Pushwoosh API. --- /createKakaoMessage is deprecated New integrations should use [Messaging API v2](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/) — pass `platforms: ["KAKAO"]` to `Notify` and use the `kakao` block inside `payload.content.localized_content`. See the [migration guide](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/migration-from-v1/#from-createkakaomessage). ## createKakaoMessage Deprecated Use this endpoint to send Kakao messages to users. `POST` `https://api.pushwoosh.com/json/1.3/createKakaoMessage` Note This endpoint is dedicated to Kakao messaging only. For multi-channel messaging, use [`/createMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api/). ### Prerequisites Before using this endpoint, ensure: 1. **Kakao platform is configured**: Your Pushwoosh application must have Kakao credentials configured. [Learn more](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/kakao-configuration/) 2. **Templates are approved**: Kakao templates must be created and approved before they can be used. [Learn more](https://docs.pushwoosh.com/product/content/kakao-presets/) 3. **Devices are registered**: Devices must be registered with the `kakao:` prefix to be recognized as Kakao endpoints. ### Request body | Name | Required | Type | Description | | :-------------- | :------- | :----- | :----------------------------------------------------------------------------------------------------------- | | auth* | Yes | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | Yes | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | notifications* | Yes | array | Array of notification objects. See details below. | ### Notification parameters | Name | Required | Type | Description | | :------------------------ | :------------------------------------ | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | send_date* | Yes | string | Date and time to send the message. Use format `YYYY-MM-DD HH:MM:SS` (UTC) or `"now"` to send immediately. All times are interpreted as UTC. | | devices* | Required if `users` is not provided | array[string] | List of device tokens. Each token **must** be prefixed with `kakao:` (e.g., `"kakao:user_token"`). | | users* | Required if `devices` is not provided | array[string] | List of user IDs to target. | | template* | Yes | string | Kakao template name. Must be a pre-approved template. [Learn more](https://docs.pushwoosh.com/product/content/kakao-presets/) | | kakao_content_variables | No | object | Key-value pairs for template variable substitution. Keys must match variables defined in your Kakao template. Optional but allows dynamic personalization of your Kakao messages. | Important You must provide either `devices` or `users`. Do not leave both empty. #### Forbidden parameters The following parameters are not allowed for this endpoint and will result in a validation error: * `platforms`: The platform is automatically set to Kakao * `filter`: Device filtering not supported * `filter_code`: Filter codes not supported * `conditions`: Conditional targeting not supported ### Request example ```json { "request": { "auth": "your-api-access-token", // required. API access token from Pushwoosh Control Panel. "application": "XXXXX-XXXXX", // required. Pushwoosh application code. "notifications": [ { "send_date": "now", // required. YYYY-MM-DD HH:MM:SS (UTC) OR "now". "devices": ["kakao:user123@kakao.com", "kakao:device_abc"], // required if users is not provided. Device tokens with kakao: prefix. "users": ["user_001", "user_002"], // required if devices is not provided. User IDs to target. "template": "welcome_message", // required. Kakao template name (must be pre-approved). "kakao_content_variables": { // optional. Template variable substitution. "user_name": "John Doe", "order_number": "12345" } } ] } } ``` ### Response example * 200 ```json { "status_code": 200, "response": { "Messages": ["MESSAGE_ID_1"], "Warnings": [], "UnknownDevices": {}, "UnknownUsers": {}, "FailedDevices": {}, "UnknownPhoneNumbers": {} } } ``` | Field | Type | Description | | --------------------- | -------------- | ----------------------------------------- | | `Messages` | array[string] | Array of message IDs created for tracking | | `Warnings` | array | Any warnings generated during processing | | `UnknownDevices` | object | Devices that could not be found | | `UnknownUsers` | object | User IDs that could not be resolved | | `FailedDevices` | object | Devices that failed during processing | | `UnknownPhoneNumbers` | object | Phone numbers that could not be found | * 210 ```json { "status_code": 210, "status_message": "Error description" } ``` ##### Common error messages | Error Message | Cause | | :--------------------------------------------- | :-------------------------------------------------------- | | `Missing required parameter: send_date` | The `send_date` field is not provided in the notification | | `Missing required parameter: devices or users` | Neither `devices` nor `users` array is provided | | `Invalid Kakao devices list` | One or more device tokens are missing the `kakao:` prefix | | `Invalid parameter: platforms` | Attempted to set platforms manually (not allowed) | | `Kakao template is required` | Template name was not provided | | `Invalid Kakao template` | Specified template does not exist | | `Kakao template not approved` | Template exists but is not approved by Kakao | | `Please configure Kakao platform` | Application does not have Kakao credentials configured | * 500 ```json { "status_code": 500, "status_message": "Internal server error" } ``` ### Code examples * cURL ```bash curl -X POST "https://api.pushwoosh.com/json/1.3/createKakaoMessage" \ -H "Content-Type: application/json" \ -d '{ "request": { "auth": "your-api-access-token", "application": "XXXXX-XXXXX", "notifications": [ { "send_date": "now", "devices": ["kakao:user123@kakao.com", "kakao:device_abc"], "template": "welcome_message", "kakao_content_variables": { "user_name": "John Doe", "order_number": "12345" } } ] } }' ``` * PHP ```php [ 'auth' => 'your-api-access-token', 'application' => 'XXXXX-XXXXX', 'notifications' => [ [ 'send_date' => 'now', 'devices' => ['kakao:user123@kakao.com', 'kakao:device_abc'], 'template' => 'welcome_message', 'kakao_content_variables' => [ 'user_name' => 'John Doe', 'order_number' => '12345' ] ] ] ] ]; $options = [ 'http' => [ 'header' => "Content-Type: application/json\r\n", 'method' => 'POST', 'content' => json_encode($data) ] ]; $context = stream_context_create($options); $result = file_get_contents($url, false, $context); echo $result; ``` * Python ```python import requests url = "https://api.pushwoosh.com/json/1.3/createKakaoMessage" payload = { "request": { "auth": "your-api-access-token", "application": "XXXXX-XXXXX", "notifications": [ { "send_date": "now", "devices": ["kakao:user123@kakao.com", "kakao:device_abc"], "template": "welcome_message", "kakao_content_variables": { "user_name": "John Doe", "order_number": "12345" } } ] } } response = requests.post(url, json=payload) print(response.json()) ``` ### Example: Sending to users instead of devices ```json { "request": { "auth": "your-api-access-token", "application": "XXXXX-XXXXX", "notifications": [ { "send_date": "now", "users": ["user_001", "user_002", "user_003"], "template": "promotion_alert", "kakao_content_variables": { "discount_percent": "20", "promo_code": "SAVE20" } } ] } } ``` ### Example: Scheduled message ```json { "request": { "auth": "your-api-access-token", "application": "XXXXX-XXXXX", "notifications": [ { "send_date": "2024-12-25 09:00:00", "devices": ["kakao:user123"], "template": "holiday_greeting" } ] } } ``` --- # LINE API **URL:** https://docs.pushwoosh.com/developer/api-reference/line-api/ Send personalized LINE messages via Pushwoosh API. Support for text, images, carousels, and Flex templates. --- /createLineMessage is deprecated New integrations should use [Messaging API v2](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/) — pass `platforms: ["LINE"]` to `Notify` and use the `line` block inside `payload.content.localized_content`. See the [migration guide](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/migration-from-v1/#from-createlinemessage). For rich image / carousel / flex messages, pre-configure them as LINE templates in your Pushwoosh Control Panel and reference the template code through `line.template`. Note Before sending LINE messages, ensure that the Line platform is properly configured. [Learn more](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/line-configuration/) ## createLineMessage Deprecated Used to send LINE messages to users `POST` `https://api.pushwoosh.com/json/1.3/createLineMessage` ### Send a textual message Simple LINE messages that consist only of plain text, without images or buttons. [Learn more](https://developers.line.biz/en/reference/messaging-api/#text-message) > **Tip:** For advanced formatting and rich media, use message templates like [Flex](https://docs.pushwoosh.com/developer/api-reference/line-api/#send-a-flex-message), [image](https://docs.pushwoosh.com/developer/api-reference/line-api/#send-an-image-message), or [carousel](https://docs.pushwoosh.com/developer/api-reference/line-api/#send-an-image-carousel-message). ##### Request body | Parameter | Type | Required | Description | | :-------------- | :--------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `application` | string | Yes | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | `auth` | string | Yes | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) for authenticating the request. | | `notifications` | array of objects | Yes | List of LINE message objects to be sent. | | `content` | string | Yes | Text of the LINE message to be sent. Max character limit: 5000. **Note:** If both `preset` and `content` are included, the value from the request overrides the `preset`. | | `preset` | string | No | Code of the [LINE preset](https://docs.pushwoosh.com/product/content/line-presets/) you created in the Pushwoosh Control Panel. **Note:** If both `preset` and `content` are included, the value from the request overrides the `preset`. | | `send_date` | string | Yes | Date and time to send the message. Use format `YYYY-MM-DD HH:mm` or `now` to send immediately. | | `devices` | array of strings | Yes | List of device codes (user IDs) to send the LINE message to. | ```plaintext { "request": { "application": "XXXXXX-XXXXXX", "auth": "**************************************", "notifications": [ { "content": "test", "preset": "preset_code", "send_date":"now", "devices": ["XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"] } ] } } ``` ### Send an image message You can send an [image message](https://developers.line.biz/en/reference/messaging-api/#image-message) to LINE users by specifying an image object within the template field of your request. Each image message requires two image URLs: one for the **full-size image (image_url)** and another for the **preview (preview_image_url)**. When users tap the preview, the full-size image opens. Make sure both URLs use HTTPS (TLS 1.2 or later) and link to publicly accessible image files. For details, see the [Image Message section](https://developers.line.biz/en/reference/messaging-api/#image-message) in the LINE Messaging API documentation. ##### Request body | Parameter | Type | Required | Description | | :-------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `application` | string | Yes | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | `auth` | string | Yes | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) used to authenticate the request. | | `notifications` | array of objects | Yes | List of messages to send. | | `content` | string | Yes | Used as fallback or preview text for the message. Code of the LINE preset you created in the Pushwoosh Control Panel. **Note:** If both `preset` and `template` are included, the `template` from the request is used. If both `preset` and `content` are included, the `content` from the request overrides the preset. | | `send_date` | string | Yes | Date and time to send the message. Use format `YYYY-MM-DD HH:mm` or `now` to send immediately. | | `devices` | array of strings | Yes | List of device codes (user IDs) to send the LINE message to. | | `preset` | string | No | Code of the [LINE preset](https://docs.pushwoosh.com/product/content/line-presets/) you created in the Pushwoosh Control Panel. **Note:** If both `preset` and `template` parameters are included in the request, the values from the `template` will override those defined in the preset. If both `preset` and `content` are included in the same request, the `content` provided directly in the request will override the content from the `preset`. | | `template` | object | Yes | Message layout template. Supports multiple message types. See details below. | ##### Template parameters **Type:** image | Parameter | Type | Required | Description | | :------------------ | :----- | :------- | :----------------------------------------------------------------------------------------------------------------------------------- | | `image_url` | string | Yes | URL to the full-size image (must use HTTPS). **Max length:** 2000 characters. **Format:** JPEG, PNG. **Max size:** 10 MB. | | `preview_image_url` | string | Yes | URL to the preview image shown in chat (must use HTTPS). **Max length:** 2000 characters. **Format:** JPEG, PNG. **Max size:** 1 MB. | ##### Example request ```json { "request": { "application": "XXXXXX-XXXXXX", "auth": "**************************************", "notifications": [ { "content": "test", "send_date": "now", "devices": [ "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" ], "preset": "preset_code", "template": { "en": { "image": { "alt_text": "some text", "image_url": "https://images.com/1.jpg", "preview_image_url": "https://images.com/1.png" } } } } ] } } ``` ### Send an image carousel message Image carousel messages let you display multiple images in a horizontally scrollable format. Each image appears as a separate, non-clickable column that users can swipe through in the LINE chat interface. This format is ideal for showcasing items, promotions, or visual selections in an engaging way. For details, refer to the [Image Carousel Template](https://developers.line.biz/en/reference/messaging-api/#carousel) section in the LINE Messaging API documentation. ##### Request body | Parameter | Type | Required | Description | | :-------------- | :--------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `application` | string | Yes | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | `auth` | string | Yes | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) used to authenticate the request. | | `notifications` | array of objects | Yes | List of messages to send. | | `content` | string | Yes | Used as fallback or preview text for the message. **Note:** If both `content` and `template` are set, the `template` is used. If both a `preset` and `content` are included in the same request, the `content` provided directly in the request will override the content from the `preset`. | | `send_date` | string | Yes | Date and time to send the message. Use the format `YYYY-MM-DD HH:mm` or `"now"`. | | `devices` | array of strings | Yes | List of device codes (user IDs) to send the LINE message to. | | `preset` | string | No | Code of the [LINE preset](https://docs.pushwoosh.com/product/content/line-presets/) you created in the Pushwoosh Control Panel. **Note:** If both `preset` and `template` parameters are included in the request, the values from the `template` will override those defined in the `preset`. If both a `preset` and `content` are included in the same request, the `content` provided directly in the request will override the content from the `preset`. | | `template` | object | Yes | Message layout template. Supports multiple message types. See details below. | ##### Template parameters **Type:** image_carousel | Parameter | Type | Required | Description | | :---------- | :--------------- | :------- | :----------------------------------------------------------------------------------------------------------------- | | `alt_text` | string | Yes | Fallback text displayed in push previews and on unsupported devices. Max 400 characters. | | `columns` | array of objects | Yes | Array of image columns (1–10 supported). Each column includes an image. | | `image_url` | string | Yes | URL to the image shown in each carousel column pointing to a publicly accessible JPEG or PNG file. Must use HTTPS. | ##### Example request ```json { "request": { "application": "XXXXXX-XXXXXX", "auth": "**************************************", "notifications": [ { "content": "test", "send_date": "now", "devices": [ "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" ], "preset": "preset_code", "template": { "en": { "image_carousel": { "alt_text": "some text", "columns": [ { "image_url": "https://images.com/1.jpg" }, { "image_url": "https://images.com/2.jpg" }, { "image_url": "https://images.com/3.jpg" } ] } } } } ] } } ``` ### Send a Flex message Flex Messages are powerful, customizable message types that allow you to create structured layouts using text, images, buttons, and other components. They are ideal for use cases such as receipts, product cards, menus, or any content that benefits from visual structuring. To send a Flex Message, include a `template` object with a `raw` payload inside your request. The message layout must follow the [LINE Flex Message specification](https://developers.line.biz/en/docs/messaging-api/using-flex-messages/). **Tip:** You can design and preview Flex Messages using the [LINE Flex Message Simulator](https://developers.line.biz/flex-simulator/). ##### Request body | Parameter | Type | Required | Description | | :-------------- | :--------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `application` | string | Yes | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | `auth` | string | Yes | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) used to authenticate the request. | | `notifications` | array of objects | Yes | List of messages to send. | | `content` | string | Yes | Used as fallback or preview text for the message. **Note:** If both `content` and `template` are set, the template is used. If both `preset` and `content` are included, the content from the request overrides the preset. | | `send_date` | string | Yes | When to send the message. Use `"now"` or `YYYY-MM-DD HH:mm` format. | | `devices` | array of strings | Yes | List of LINE device tokens (user IDs) to receive the message. | | `preset` | string | No | Code of the [LINE preset](https://docs.pushwoosh.com/product/content/line-presets/) you created in the Pushwoosh Control Panel. **Note:** If both `preset` and `template` are included, the template overrides the preset. If both `preset` and `content` are included, the content from the request overrides the preset. | | `template` | object | Yes | Message layout template. Supports multiple message types. See details below. | ##### Template parameters For a Flex Message, use the raw structure.\ Type: raw (Flex) | Parameter | Type | Required | Description | | :--------- | :----- | :------- | :-------------------------------------------------------------------------------------------------------------------- | | `alt_text` | string | Yes | Fallback text shown in notifications, chat previews, and quotes. Max 400 characters. | | `content` | object | Yes | Flex Message layout, structured using `bubble`, `box`, `text`, and other components as per LINE’s Flex specification. | ##### Example request ```json { "request": { "application": "XXXXXX-XXXXXX", "auth": "**************************************", "notifications": [ { "content": "test", "send_date": "now", "devices": ["XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"], "preset": "preset_code", "template": { "en": { "raw": { "alt_text": "My raw template", "content": { "type": "bubble", "body": { "type": "box", "layout": "vertical", "contents": [ { "type": "text", "text": "RECEIPT", "weight": "bold", "color": "#1DB446", "size": "sm" } // Additional components... ] } } } } } } ] } } ``` --- # Message inbox API **URL:** https://docs.pushwoosh.com/developer/api-reference/message-inbox/ Retrieve and manage inbox messages using API methods to access message history and inbox status for users. --- ## getInboxMessages Returns the list of Inbox messages for a specified HWID. `POST` `https://api.pushwoosh.com/json/1.3/getInboxMessages` #### Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | #### Request Body | Name | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------------------------------- | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | userId* | string | If no custom [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) is set, use HWID. | | hwid | string | [Hardware ID of a device](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) to get the Inbox messages for. | | last_code | string | Code of the last message retrieved in the previous response. If empty, the first messages are returned. | | count | integer | The number of messages to be showed in a single response; used for pagination. 0 for loading all messages in Inbox. | * 200 ```json { "response": { "messages": [{ // array of messages currently stored in user's Inbox "inbox_id": "avde1c792cd", "rt": "146078676", // date to remove the message from Inbox "send_date": "1459758676", // date when the message was saved to Inbox "order": "59138176", // position in Inbox presentation order "title": "New Rich Media in inbox!", "text": "Hi! New feature is available right now!", "action_type": "RichMedia", "action_params": { // payload describing the actions on push opening "rm": "{\"url\":\"https:\/\/richmedia.pushwoosh.com\/C82F7-51FC1.zip\",\"ts\":\"1459758676\",\"tags\":{\"tagName\":\"tagValue\"}}" }, "status": 1, // 1 - delivered, 2 - read, 3 - opened, // 4 - deleted(by a user), 5 - deleted from Control Panel "hash":"1C" // hash code of push notification }, { ... }], "next":"afarew511", // the next Inbox code to be returned by // the following /getInboxMessages request "deleted": ["bbaf85ab", "a41957b"], // the list of messages deleted from Control Panel "new_inbox": 6 // the number of delivered Inbox messages for that user (can be used for badge) } } ``` Example Request ```json { "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh app code "userId": "user_name_1", // required. User ID registered in Pushwoosh "device_type": 1 // optional. For device types refer to /registerDevice } } ``` Note For iOS, please make sure that you have added the Notification Service Extension to your project for tracking push delivery.[ Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/ios-sdk/ios-message-delivery-tracking/) ## inboxStatus Updates the status of a particular Inbox message. `POST` `https://api.pushwoosh.com/json/1.3/inboxStatus` #### Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | #### Request Body | Name | Type | Description | | ------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | inbox_code* | string | could be obtained from Message details in Control Panel or from the “order” parameter of the `/geInboxMessages` request | | hash | string | Hash code of Inbox message. | | hwid | string | [Hardware ID of the device](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) to update Inbox status for. | | time | string | Send date timestamp. | | userID* | string | If no custom [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) is set, use HWID. | | status* | integer | 1 - delivered, 2 - read, 3 - opened, 4 - deleted by a user. | | device_type | integer | [See possible values](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#device-type). | * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` Example ```json { "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "inbox_code": "874393934032909", // required. "order" parameter of /getInboxMessages request "hash": "1C", // optional. "userId": "some_user", // required. "status": 2, // required. status to set: 1-delivered, 2-read, 3-opened, 4-deleted (by a user) "device_type": 3 // optional. } } ``` --- # Messages API **URL:** https://docs.pushwoosh.com/developer/api-reference/messages-api/ Create, delete, cancel, and manage push notifications using Messages API methods for targeted messaging. --- /createMessage and /createTargetedMessage are deprecated New integrations should use the unified [**Messaging API v2**](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/) — one endpoint replaces the entire `/create*Message` family. See the [migration guide](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/migration-from-v1/) for a field-by-field mapping. The legacy methods below remain fully operational. `/deleteMessage`, `/cancelMessage`, and `/getMessageDetails` are not deprecated — use them as usual against v1- or v2-created messages. Note To get started, please check out the descriptions of the [/createMessage request parameters](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites). ## createMessage Deprecated `POST` `https://api.pushwoosh.com/json/1.3/createMessage` Creates a new push notification. #### Request Body | Name | Type | Description | | --------------- | ------ | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | notifications* | array | JSON array of message parameters. See details in a request example below. | Tip Pass an `X-Request-ID` header to correlate the created message with your request for end-to-end tracing — see [Request ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#request-id). * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "Messages": [ "C3F8-C3863ED4-334AD4F1" ] } } ``` Note /createMessage method supports content templates. To learn more, please refer to the [Liquid Templates guide](https://docs.pushwoosh.com/developer/guides/personalization/liquid-templates/). ### Request example Example ```json { "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code. "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel. "notifications": [{ "send_date": "now", // optional. YYYY-MM-DD HH:mm OR 'now' "content": { // optional. object OR string. "en": "English", // Use "wns_content" instead for Windows. "fr": "French" }, "title": { // optional. object OR string. "en": "Title", // Ignored if platform-specific titles are specified "fr": "Titre" // 'ios_title', 'android_header', etc. }, // see the platform-specific parameters examples below. "subtitle":{ // optional. object OR string. "en": "Subtitle", // Ignored if platform-specific titles are specified "fr": "Sous-titre" // 'ios_subtitle', etc. }, // see the platform-specific parameters examples below. "ignore_user_timezone": true, // optional. "timezone": "America/New_York", // optional. If ignored UTC-0 is default for "send_date". // See https://php.net/manual/timezones.php for // supported timezones. "campaign": "CAMPAIGN_CODE", // optional. Campaign code to which you want to // assign this push message. "geozone": { // optional. Send to Geozone "lat": 22.22, "lng": 33.33, "range": 110 }, "rich_media": "XXXXX-XXXXX", // optional. Copy the Rich Media code from the URL bar of // the Rich Media editor page in Pushwoosh Control Panel. "link": "https://google.com", // optional. For deeplinks add "minimize_link": 0 "minimize_link": 0, // optional. 0 — do not minimize, 2 — bitly. Default = 2. // Please note that shorteners have restrictions // on a number of calls. "data": { // optional. JSON string or JSON object, will be passed as "key": "value" // "u" parameter in the payload (converted to JSON string). }, "transactionId": "unique UUID", // optional. Unique message identifier to prevent duplicating // in case of network problems. Stored on the side of // Pushwoosh for 5 minutes. "platforms": [ // optional. 1 — iOS; 3 — Android; 7 — Mac OS X; 8 — Windows; 1, 3, 7, 8, 9, 10, // 9 — Amazon; 10 — Safari; 11 — Chrome; 11, 12, 17 // 12 — Firefox; 17 — Huawei ], "preset": "XXXXX-XXXXX", // optional. Push Preset Code from your Control Panel. // If specific params are sent in the request, // they override preset's params. "send_rate": 100, // optional. Throttling. Valid values are from 100 to 1000 pushes/second. "send_rate_avoid": true, // optional. If set to true, throttling limit will not be applied to // this specific push notification. // Templating related, please refer to the Template Engine guide to learn more "template_bindings": { // optional. "TemplatePlaceholder": "Value" }, "dynamic_content_placeholders": { // optional. Placeholders for dynamic content instead of device tags. "firstname": "John", "lastname": "Doe" }, "message_type": "marketing", // optional. "marketing" or "transactional". // If omitted, users with PW_ControlGroup: true will not receive the message. // Frequency capping params. Ensure that Global frequency capping is configured in the Control Panel. // Frequency capping does not apply to transactional messages. // In all other cases, including omitted "message_type", frequency capping applies. "capping_days": 30, // optional. Amount of days for frequency capping (max 30 days) "capping_count": 10, // optional. The max number of pushes that can be sent from a // specific app to a particular device within a 'capping_days' // period. In case the message created exceeds the // 'capping_count' limit for a device, it won't // be sent to that device. "capping_exclude": true, // optional. If set to true, this push notification will not // be counted towards the capping for future pushes. "capping_avoid": true, // optional. If set to true, capping will not be applied to // this specific push notification. // To save the message to the Inbox via API, use "inbox_date" or "inbox_image". // The message is saved when at least one of these parameters is used. "inbox_date": "2017-02-02", // optional. Specify when to remove a message from the Inbox. // Message will be removed from Inbox at 00:00:01 UTC // of the date specified, so the previous date is the // last day a user can see the message in their Inbox. // If not specified, the default removal date is the // next day after the send date. "inbox_image": "Inbox image URL", // optional. The image to be shown near the message. "inbox_days": 5, // optional. Specify when to remove a message from the // Inbox(lifetime of an inbox message in days). // Can be used instead of the "inbox_date" parameter. // Up to 30 days. "devices": [ // optional. Specify tokens or hwids to send targeted push "hwid_XXXX" // notifications. Not more than 1000 tokens/hwids in ], // an array. If set, the message will only be sent to // the devices on the list. Application Group for devices // list is not allowed. iOS push tokens can only be lower case. "to": [ // optional. For email, SMS, and similar channels. List of recipients "email_1", "email_2" // (e.g. email addresses, phone numbers). Max 1000 items. ], // For push, use "devices" instead. // User-centric push notifications "users": [ // optional. If set, message will only be delivered to the "user_XXXX" // specified user ID's (set via /registerUser call). ], // If specified together with devices or to, // the latter will be ignored. Not more than 1000 user // ID's in an array. Application Group for users list // is not allowed. // Filters and conditions "filter": "FILTER_NAME", // optional. "conditions": [ // optional. See the remark below. ["Country", "EQ", "fr"], ["Language", "EQ", "en"] ], "conditions_operator": "AND" // optional. Logical operator for conditions arrays. // Possible values: AND | OR. AND is default. }] } } ``` ### VoIP notification request example Pushwoosh supports VoIP-style call notifications for iOS and Android.\ Below you can find example API `createMessage` requests for each platform. #### iOS Example ```json { "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code. "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel. "notifications": [ { "voip_push": true, // required. Parameter is required to send out a VoIP push notification. "ios_root_params": { "aps": { "mutable-content": 1 // required for iOS10+ Media attachments. }, "callerName": "CallerName", // optional. Caller name. If not specified, "unknown caller" is shown. "video": true, // optional. Indicates whether video calls are supported. "supportsHolding": true, // optional. Indicates whether call holding functionality is supported. "supportsDTMF": false, // optional. Controls Dual-Tone Multi-Frequency signal support. "callId": "42", // optional. The unique identifier of the call to cancel. "cancelCall": true // optional. Set to "true" to cancel the call with the specified "callId". } } ] } } ``` #### Android Example ```json { "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code. "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel. "notifications": [ { "voip_push": true, // required. Parameter is required to send out a VoIP push notification. "android_root_params": { "callerName": "callerName", // optional. Caller name. If not specified, "unknown caller" is shown. "video": true, // optional. Indicates whether video calls are supported. "callId": 42, // optional. The unique identifier of the call to cancel. "cancelCall": true // optional. Set to "true" to cancel the call with the specified "callId". } } ] } } ``` ### Platform-specific parameters #### iOS parameters Example ```json { "request": { "application": "12345-67891", // required. Pushwoosh application code "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "notifications": [{ "ios_title": { // optional. Object OR string. Adds iOS specific title for push notification. "en": "title" }, "ios_subtitle": { // optional. Object OR string. Adds iOS specific subtitle for push notification. "en": "subtitle" }, "ios_content": { // optional. Object OR string. Adds iOS specific content for push notification. "en": "content" }, "ios_badges": 5, // optional. iOS application badge number. // Use "+n" or "-n" to increment/decrement the badge value by n. "ios_sound": "sound file.wav", // optional. Sound file name in the main bundle of application. // If left empty, the device will produce a default system sound. "ios_sound_off": true, // optional. Enable/disable sound set by "ios_sound" field. "ios_ttl": 3600, // optional. Time to live parameter - maximum message lifespan in seconds. "ios_silent": 1, // optional. Enables silent notifications (ignore "sound" and "content"). "ios_category_id": "1", // optional. iOS8 category ID from Pushwoosh. "ios_root_params": { // optional. Root level parameters to the aps dictionary. "aps": { "content-available": "0", // optional. Set "1" to send a silent push and "0" for regular push. "mutable-content": 1 // required for iOS10+ Media attachments. }, "callerName": "CallerName", // optional VoIP parameter. Caller name. If not specified, "unknown caller" is shown. "video": true, // optional VoIP parameter. Indicates whether video calls are supported. "supportsHolding": true, // optional VoIP parameter. Indicates whether call holding functionality is supported. "supportsDTMF": false, // optional VoIP parameter. Controls Dual-Tone Multi-Frequency signal support. "data": {} // optional User supplied data, max of 4KB }, "ios_attachment": "URL", // optional. Insert media content in notification. "ios_thread_id": "some thread id", // optional. Identifier to group related notifications. // Messages with the same thread ID will be grouped // on the lock screen and in the Notification Center. "ios_critical": true, // optional. Marks iOS notification as a critical alert // playing sound even if a device is muted or // Do Not Disturb mode is on. "ios_category_custom": "category", // optional. Custom APNS category. "ios_interruption_level": "active", // optional. One of "passive", "active", "time-sensitive", // "critical". Indicates the importance and // delivery timing of a notification. Refer to the // One-time push guide for details. "apns_collapse_id": "promo", // optional. APNs collapse identifier. Notifications with the same // apns_collapse_id replace each other on the device. "apns_trim_content": 1 // optional. (0|1) Trims the exceeding content strings with ellipsis. }] } } ``` #### Android parameters Example ```json { "request": { "application": "12345-67891", // required. Pushwoosh application code "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "notifications": [{ "android_header": { // optional. Android notification header. "en": "header" }, "android_content": { // optional. Android notification content. "en": "content" }, "android_root_params": { // optional. Custom key-value object. "key": "value", // Root level parameters for the android payload recipients. "CancelID": 12345678, // optional. Cancels the push notification with the "voip": true, // required VoIP parameter. Parameter is required to send out VoIP push notifications. "callerName": "callerName", // optional VoIP parameter. Caller name. If not specified, "unknown caller" is shown. "video": true, // optional VoIP parameter. Indicates whether video calls are supported. }, // specified Message ID (get the ID from the Message History) "android_sound": "soundfile", // optional. No file extension. If left empty, // the device will produce a default system sound. "android_sound_off": true, // optional. Enable/disable sound set by "android_sound" field "android_icon": "icon.png", // optional. "android_custom_icon": "URL.png", // optional. Full URL to the image file. "android_banner": "URL.png", // optional. Full URL to the image file. "android_badges": 5, // optional. Android application icon badge number. // Use "+n" or "-n" to increment/decrement the badge value by n. "android_gcm_ttl": 3600, // optional. Time to live parameter — maximum message lifespan in seconds. "android_vibration": 0, // optional. Android force-vibration for high-priority pushes. "android_led": "#rrggbb", // optional. LED hex color, device will do its best approximation. "android_priority": -1, // optional. Sets the "importance" parameter for devices with // Android 8.0 and higher, as well as the "priority" parameter // for devices with Android 7.1 and lower. Establishes the // interruption level of a notification channel or a particular // notification. Valid values are -2, -1, 0, 1, 2. "android_delivery_priority": "normal", // optional. "normal" or "high". // Enables notification’s delivery when the // device is in the power saving mode. "android_ibc": "#RRGGBB", // optional. icon background color on Lollipop, #RRGGBB, // #AARRGGBB, "red", "black", "yellow", etc. "android_silent": 1, // optional. 0 or 1. Enable silent notification. // Ignore sound and content "android_group_id": "123", // optional. Identifier to group related notifications. Messages with // the same thread ID will be grouped in // the Notification Center. "android_collapse_key": "promo" // optional. FCM collapse key. Notifications with the same // collapse key replace each other while the device is offline. }] } } ``` **Huawei parameters** Huawei ```json { "request": { "application": "12345-67891", // required. Pushwoosh application code "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "notifications": [{ "huawei_android_header": { // optional. Object OR string. Notification title "en": "header" }, "huawei_android_content": { // optional. Object OR string. Notification content "en": "content" }, "huawei_android_badges": true, // optional. "huawei_android_silent": 0, // optional. 0 or 1. Enable silent notification. // Ignore sound and content "huawei_android_icon": "URL.png", // optional. "huawei_android_led": "#FF0011", // optional. LED hex color, device will do its best approximation "huawei_android_vibration": 1, // optional. Huawei force-vibration for high-priority pushes "huawei_android_sound": "sound.wav", // optional. If left empty, the device will produce // a default system sound "huawei_android_sound_off": true, // optional. Enable/disable sound set by // "huawei_android_sound" field "huawei_android_custom_icon": "URL.png", // optional "huawei_android_gcm_ttl": 2400, // optional. Time to live parameter - maximum // message lifespan in seconds "huawei_android_banner": "URL.png", // optional. Full path URL to the image file "huawei_android_root_params": { // optional. Custom key-value object. "key": "value" // Root-level parameters for Huawei payload recipients. }, "huawei_android_priority": 0, // optional. Valid values: -2, -1, 0, 1, 2 "huawei_android_ibc": "#0011AA", // optional. Icon background color on Lollipop "huawei_android_lockscreen": 1, // optional "huawei_android_delivery_priority": "normal", // optional. "normal" or "high". Enables notification // delivery in power saving mode "huawei_android_group_id": "group_id" // optional. Identifier to group related notifications }] } } ``` #### Safari parameters Safari ```json { "request": { "application": "12345-67891", // required. Pushwoosh application code "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "notifications": [{ "safari_url_args": [ // required, but the value may be empty "firstArgument", "secondArgument" ], "safari_title": { // optional. Object OR string. Title of the notification. "en": "content" }, "safari_content": { // optional. Object OR string. Content of the notification. "en": "content" }, "safari_action": "Click here", // optional. "safari_ttl": 3600 // optional. Time to live parameter — the maximum // lifespan of a message in seconds. }] } } ``` #### Chrome parameters Chrome ```json { "request": { "application": "12345-67891", // required. Pushwoosh application code "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "notifications": [{ "chrome_title": { // optional. Object OR string. You can specify the header "en": "title" // of the message in this parameter. }, "chrome_content": { // optional. Object OR string. You can specify the content "en": "content" // of the message in this parameter. }, "chrome_icon": "URL.png", // optional. Full URL to the icon or extension resources file path "chrome_gcm_ttl": 3600, // optional. Time to live parameter – maximum message lifespan in seconds. "chrome_duration": 20, // optional. max 50 seconds. Changes chrome push display time. // Set to 0 to display push until user interacts with it. "chrome_image": "image_URL", // optional. URL to large image. "chrome_root_params": { // optional. Set parameters specific to messages sent to Chrome. "key": "value" }, "chrome_button_text1": "text1", // optional "chrome_button_url1": "button1_URL", // optional. Ignored if chrome_button_text1 is not set. "chrome_button_text2": "text2", // optional "chrome_button_url2": "button2_url" // optional. Ignored if chrome_button_text2 is not set. }] } } ``` #### Firefox parameters Firefox ```json { "request": { "application": "12345-67891", // required. Pushwoosh application code "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "notifications": [{ "firefox_title": { // optional. Object OR string. You can specify message header here. "en": "title" }, "firefox_content": { // optional. Object OR string. You can specify message content here. "en": "content" }, "firefox_icon": "URL.png", // optional. Full path URL to the icon or path to the // file in extension resources. "firefox_root_params": { // optional. Set parameters specific to messages sent to Firefox. "key": "value" } }] } } ``` #### Amazon parameters Amazon ```json { "request": { "application": "12345-67891", // required. Pushwoosh application code "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "notifications": [{ "adm_header": { // optional. Object OR string. You can specify message header here. "en": "header" }, "adm_content": { // optional. Object OR string. You can specify message content here. "en": "content" }, "adm_root_params": { // optional. Custom key-value object "key": "value" }, "adm_sound": "push.mp3", // optional. "adm_sound_off": true, // optional. Enable/disable sound set by "adm_sound" field "adm_icon": "icon.png", // optional. Full URL to the icon. "adm_custom_icon": "URL.png", // optional. "adm_banner": "URL.png", // optional. "adm_ttl": 3600, // optional. Time to live parameter — the maximum message // lifespan in seconds. "adm_priority": -1 // optional. Priority of the push in Amazon push drawer, // valid values are -2, -1, 0, 1 and 2. }] } } ``` #### Mac OS X parameters Mac OS X ```json { "request": { "application": "12345-67891", // required. Pushwoosh application code "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "notifications": [{ "mac_title": { // optional. Object OR string. Adds Title for push notification. "en": "title" }, "mac_subtitle": { // optional. Adds subtitle for push notification. "en": "subtitle" }, "mac_content": { // optional. Adds content for push notification. "en": "content" }, "mac_badges": 3, // optional. "mac_sound": "sound.caf", // optional. "mac_sound_off": true, // optional. Enable/disable sound set by "mac_sound" field "mac_root_params": { // optional. "content-available": 1 }, "mac_ttl": 3600 // optional. Time to live parameter — maximum message lifespan in seconds. }] } } ``` #### Windows parameters Windows ```json { "request": { "application": "12345-67891", // required. Pushwoosh application code "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "notifications": [{ "wns_content": { // required. Content (XML or raw) of notification encoded in MIME's base64 // in form of Object OR String "en": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48YmFkZ2UgdmFsdWU9ImF2YWlsYWJsZSIvPg==", "de": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48YmFkZ2UgdmFsdWU9Im5ld01lc3NhZ2UiLz4=" }, "wns_type": "Badge", // optional. 'Tile' | 'Toast' | 'Badge' | 'Raw' "wns_tag": "myTag", // optional. Used in Tile replacement policy. // An alphanumeric string of no more than 16 characters. "wns_cache": 1, // optional. (1|0) Translates into X-WNS-Cache-Policy value. "wns_ttl": 600 // optional. Expiration time for notification in seconds. }] } } ``` Note Quick start! Check out these cool third-party libraries! Python library **by Pushwoosh**: Laravel library: Node JS client Meteor JS client Rails library Golang library Caution #### /createMessage Throttling Keep in mind that non-enterprise accounts cannot send more than 600 `/createMessage` and/or [`/createTargetedMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api/#createtargetedmessage) requests per minute. However, if you send pushes via the **devices** parameter to **10 devices or less**, there are no restrictions for any account type as long as API messaging tracing is disabled. Note that **we always save scheduled pushes** to the Message History, even if you are sending them to less than 10 devices via devices parameter. Therefore, such pushes are also throttled. **Response**: | HTTP Status code | status_code | Description | | ---------------- | ------------ | ------------------------------------------------- | | 200 | 200 | Message successfully created | | 200 | 210 | Argument error. See status_message for more info | | 400 | N/A | Malformed request string | | 500 | 500 | Internal error | Note An error in an array of notifications If the `createMessage` request has several messages in the `notifications` array, they will be processed and sent one by one. If one of the messages cannot be parsed, our API will return `"status_code":210` with the codes of successfully sent messages, i.e. those preceding the faulty message in the request. ### API messaging tracing For load balancing purposes, *we do not store messages sent through API with the “devices” parameter that contains less than 10 devices in an array*. Due to this, such messages will not be displayed in your Message History. To see push reports during the testing phase, use **API messaging tracing**. Turning this option **ON** allows you to *override this limit for 1 hour and save such pushes in the Message History*. API messaging tracing turns OFF automatically after 1 hour. API messaging tracing can be activated on the [Message History](https://docs.pushwoosh.com/product/statistics-and-analytics/message-history/) page by clicking **Start API messaging tracing** in the upper right corner. ### Tag conditions Each tag condition is an array like `[tagName, operator, operand]` where * tagName: name of a tag * operator: “EQ” | “IN” | “NOTEQ” | “NOTIN” | “LTE” | “GTE” | “BETWEEN” | “NOTSET” | “ANY” * operand: string | integer | array | date #### Operator description * EQ: tag value is equal to operand; * IN: tag value intersects with operand (operand must always be an array); * NOTEQ: tag value is not equal to an operand; * NOTIN: tag value does not intersect with operand (operand must always be an array); * GTE: tag value is greater than or equal to operand; * LTE: tag value is less than or equal to operand; * BETWEEN: tag value is greater than or equal to min operand value but less than or equal to max operand value (operand must always be an array); * NOTSET: tag not set. Operand is not considered; * ANY: tag has any value. Operand is not considered. #### String tags Valid operators: EQ, IN, NOTEQ, NOTIN, NOTSET, ANY\ Valid operands: * EQ, NOTEQ: operand must be a string; * IN, NOTIN: operand must be an array of strings like `["value 1", "value 2", "value N"]`; * NOTSET: tag not set. Operand is not considered; * ANY: tag has any value. Operand is not considered. #### Integer tags Valid operators: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE, NOTSET, ANY\ Valid operands: * EQ, NOTEQ, GTE, LTE: operand must be an integer; * IN, NOTIN: operand must be an array of integers like `[value 1, value 2, value N]`; * BETWEEN: operand must be an array of integers like `[min_value, max_value]`; * NOTSET: tag not set. Operand is not considered; * ANY: tag has any value. Operand is not considered. #### Date tags Valid operators: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE, NOTSET, ANY\ Valid operands: * `"YYYY-MM-DD 00:00"` (string) * unix timestamp `1234567890` (integer) * `"N days ago"` (string) for operators EQ, BETWEEN, GTE, LTE #### Boolean tags Valid operators: EQ, NOTSET, ANY\ Valid operands: `0, 1, true, false` #### List tags Valid operators: IN, NOTIN, NOTSET, ANY\ Valid operands: operand must be an array of strings like `["value 1", "value 2", "value N"]`. Danger Remember that “filter” and “conditions” parameters should not be used together.\ Also, both of them **will be ignored**, if the “devices” parameter is used in the same request. Note #### Country and Language tags Language tag value is a lowercase two-letter code according to [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)\ Country tag value is an UPPERCASE two-letter code according to [ISO_3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)\ For example, to send push a notification to Portuguese-speaking subscribers in Brazil, you will need to specify the following condition: `"conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]` ### /createMessage snippets Important Please be careful when using the snippets. Limit the number of recipients by specifying “users”, “devices”, “filter”, or “conditions” parameter. If none of these parameters is specified, the message will be sent **to every device** subscribed to push notifications from the application. Sample `/createMessage` requests: * Bash ```bash #!/bin/bash #Usage if [ ! -n "$1" ] || [ ! -n "$2" ] then echo "`basename $0` usage: api_token appid message"; exit 1; fi; MESSAGE="$3"; if [ -z "$3" ] then MESSAGE='One push to rule them all!' fi; echo -e "Response:" curl --data-binary " {\"request\": {\"application\":\"$2\", \"auth\":\"$1\", \"notifications\": [{ \"send_date\": \"now\", \"content\": \"$MESSAGE\" }] } }" \ -H "Content-type: application/json" \ "https://api.pushwoosh.com/json/1.3/createMessage" echo ""; exit 0; ``` * PHP ```php $data]); $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_ENCODING, 'gzip, deflate'); curl_setopt($ch, CURLOPT_HEADER, true); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $request); $response = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); if (defined('PW_DEBUG') && PW_DEBUG) { print "[PW] request: $request "; print "[PW] response: $response "; print '[PW] info: ' . print_r($info, true); } } pwCall('createMessage', array( 'application' => PW_APPLICATION, 'auth' => PW_AUTH, 'notifications' => array( array( 'send_date' => 'now', 'content' => 'test', 'data' => array('custom' => 'json data'), 'link' => 'https://pushwoosh.com/' ) ) ) ); ``` * Erlang ```erlang -module(pushwoosh). -export([run/0, stop/0, sendMessage/1]). %% sendMessage argument: message text %% %% Authentication & App_id %% -define(PW_AUTH, "YOUR_AUTH_TOKEN"). -define(PW_APPLICATION, "YOUR_PUSHWOOSH_APP_CODE"). %% KickStart %% run() -> application:start(unicode), application:start(crypto), application:start(public_key), application:start(ssl), application:start(inets), %% HTTP Client verbosity options flase, verbose, debug httpc:set_options([{verbose, false}]). stop() -> application:stop(ssl), application:stop(public_key), application:stop(crypto), application:stop(inets). %% JSON Wars ! encode(S) -> encode(S, [$"]). encode([], Acc) -> lists:reverse([$" | Acc]); encode([C | Cs], Acc) -> Hex = lists:flatten(io_lib:format("~4.16.0b", [C])), encode(Cs, lists:reverse(Hex) ++ "u\" ++ Acc). sendMessage(Message_text) -> %% URL to JSON API 1.3 Url = "https://api.pushwoosh.com/json/1.3/createMessage", EncodedMessage = encode(Message_text), {ok, Response} = httpc:request( %%Method post, %%Request {Url, [{"User-Agent", "Erlang exemple"}], "application/json; charset=UTF-8", "{\"request\":{ \"application\": \""?PW_APPLICATION"\", \"auth\": \""?PW_AUTH"\", \"notifications\": [{ \"send_date\": \"now\", \"content\": "++EncodedMessage++" }]}}"}, %%HTTP options [{ssl,[{verify, verify_none}]}, {version, "HTTP/1.0"}], %%Options []), io:format("And received ~p", [Response]). ``` * Ruby ```ruby class PushNotification #- PushWoosh API Documentation https://www.pushwoosh.com/programming-push-notification/pushwoosh-push-notification-remote-api/ #- Two methods here: # - PushNotification.new.notify_all(message) Notifies all with the same option # - PushNotification.new.notify_devices(notification_options = {}) Notifies specific devices with custom options include HTTParty #Make sure to have the HTTParty gem declared in your gemfile https://github.com/jnunemaker/httparty default_params :output => 'json' format :json def initialize #- Change to your settings @auth = {:application => "00000-00000",:auth => "auth_token"} end # PushNotification.new.notify_all("This is a test notification to all devices") def notify_all(message) notify_devices({:content => message}) end # PushNotification.new.notify_device({ # :content => "TEST", # :data => {:custom_data => value}, # :devices => array_of_tokens #}) def notify_devices(notification_options = {}) #- Default options, uncomment :data or :devices if needed default_notification_options = { # YYYY-MM-DD HH:mm OR 'now' :send_date => "now", # Object( language1: 'content1', language2: 'content2' ) OR string :content => { :fr => "Test", :en => "Test" }, # JSON string or JSON object "custom": "json data" #:data => { # :custom_data => value #}, # omit this field (push notification will be delivered to all the devices for the application), or provide the list of devices IDs #:devices => {} } #- Merging with specific options final_notification_options = default_notification_options.merge(notification_options) #- Constructing the final call options = @auth.merge({:notifications => [final_notification_options]}) options = {:request => options} #- Executing the POST API Call with HTTPARTY - :body => options.to_json allows us to send the json as an object instead of a string response = self.class.post("https://api.pushwoosh.com/json/1.3/createMessage", :body => options.to_json,:headers => { 'Content-Type' => 'application/json' }) end end ``` * Java ```java // Uses JSON classes from https://json.org/java/ package com.arellomobile; import org.json.*; import java.io.*; import java.net.*; public class SendPushNotificationSample { public static final String PUSHWOOSH_SERVICE_BASE_URL = "https://api.pushwoosh.com/json/1.3/"; private static final String AUTH_TOKEN = "YOUR_AUTH_TOKEN"; private static final String APPLICATION_CODE = "PW_APPLICATION_CODE"; public static void main(String[] args) throws JSONException, MalformedURLException { String method = "createMessage"; URL url = new URL(PUSHWOOSH_SERVICE_BASE_URL + method); JSONArray notificationsArray = new JSONArray() .put(new JSONObject().put("send_date", "now") .put("content", "test") .put("link", "https://pushwoosh.com/")); JSONObject requestObject = new JSONObject() .put("application", APPLICATION_CODE) .put("auth", AUTH_TOKEN) .put("notifications", notificationsArray); JSONObject mainRequest = new JSONObject().put("request", requestObject); JSONObject response = SendServerRequest.sendJSONRequest(url, mainRequest.toString()); System.out.println("Response is: " + response); } } class SendServerRequest { static JSONObject sendJSONRequest(URL url, String request) { HttpURLConnection connection = null; try { connection = (HttpURLConnection) url.openConnection(); connection.setRequestMethod("POST"); connection.setRequestProperty("Content-Type", "application/json"); connection.setDoInput(true); connection.setDoOutput(true); DataOutputStream writer = new DataOutputStream(connection.getOutputStream()); writer.write(request.getBytes("UTF-8")); writer.flush(); writer.close(); return parseResponse(connection); } catch (Exception e) { System.out.println("An error occurred: " + e.getMessage()); return null; } finally { if (connection != null) { connection.disconnect(); } } } static JSONObject parseResponse(HttpURLConnection connection) throws IOException, JSONException { String line; BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream())); StringBuilder response = new StringBuilder(); while ((line = reader.readLine()) != null) { response.append(line).append(' '); } reader.close(); return new JSONObject(response.toString()); } } ``` * Python ```python import json PW_AUTH = 'API TOKEN' PW_APPLICATION_CODE = 'APPLICATION CODE' try: # For Python 3.0 and later from urllib.request import urlopen from urllib.request import Request except ImportError: # Fall back to Python 2's urllib2 from urllib2 import urlopen from urllib2 import Request def pw_call(method, data): url = 'https://api.pushwoosh.com/json/1.3/' + method data = json.dumps({'request': data}) req = Request(url, data.encode('UTF-8'), {'Content-Type': 'application/json'}) try: f = urlopen(req) response = f.read() f.close() print('Pushwoosh response: ' + str(response)) except Exception as e: print ('Request error: ' + str(e)) if __name__ == '__main__': pw_call('createMessage', { 'auth': PW_AUTH, 'application': PW_APPLICATION_CODE, 'notifications': [ { 'send_date': 'now', 'content': 'test', 'data': {"custom": "json data"}, 'link': 'https://pushwoosh.com' } ] } ) ``` * .NET ```plaintext using System; using System.IO; using System.Net; using Newtonsoft.Json.Linq; namespace WebApplication1 { public partial class Default : System.Web.UI.Page { protected void Page_Load(object sender, EventArgs e) { string pwAuth = "YOUR_AUTH_TOKEN"; string pwApplication = "PW_APPLICATION_CODE"; JObject json = new JObject( new JProperty("application", pwApplication), new JProperty("auth", pwAuth), new JProperty("notifications", new JArray( new JObject( new JProperty("send_date", "now"), new JProperty("content", "test"), new JProperty("wp_type", "Toast"), new JProperty("wp_count", 3), new JProperty("data", new JObject( new JProperty("custom", "json data"))), new JProperty("link", "https://pushwoosh.com/"), new JProperty("conditions", new JArray( (object)new JArray("Color", "EQ", "black"))))))); PWCall("createMessage", json); } private void PWCall(string action, JObject data) { Uri url = new Uri("https://api.pushwoosh.com/json/1.3/" + action); JObject json = new JObject(new JProperty("request", data)); DoPostRequest(url, json); } private void DoPostRequest(Uri url, JObject data) { HttpWebRequest req = (HttpWebRequest)HttpWebRequest.Create(url); req.ContentType = "text/json"; req.Method = "POST"; using (var streamWriter = new StreamWriter(req.GetRequestStream())) { streamWriter.Write(data.ToString()); } HttpWebResponse httpResponse; try { httpResponse = (HttpWebResponse)req.GetResponse(); } catch (Exception exc) { throw new Exception(string.Format("Problem with {0}, {1}", url, exc.Message)); } using (var streamReader = new StreamReader(httpResponse.GetResponseStream())) { var responseText = streamReader.ReadToEnd(); Page.Response.Write(responseText); } } } } ``` * Go ```go package main import ( "fmt" "encoding/json" "net/http" "bytes" "io/ioutil" ) const ( PW_APPLICATION = "APPLICATION CODE" PW_AUTH = "API TOKEN" PW_ENDPOINT = "https://api.pushwoosh.com/json/1.3/" ) func pwCall(method string, data []byte) (bool) { url := PW_ENDPOINT + method request, err := http.NewRequest("POST", url, bytes.NewBuffer(data)) request.Header.Set("Content-Type", "application/json") client := http.Client{} response, err := client.Do(request) if err != nil { fmt.Println("Error occur: " + err.Error()) return false } defer response.Body.Close() fmt.Println("Response Status: ", response.Status) if (response.StatusCode == 200) { body, _ := ioutil.ReadAll(response.Body) fmt.Println("Response Body: ", string(body)) return true } return false } func main() { requestData := map[string]interface{}{ "request": map[string]interface{} { "auth": PW_AUTH, "application": PW_APPLICATION, "notifications": []interface{}{ map[string]interface{} { "send_date": "now", "content": "test", "link": "https://pushwoosh.com", }, }, }, } jsonRequest, _ := json.Marshal(requestData) requestString := string(jsonRequest) fmt.Println("Request body: " + requestString) pwCall("createMessage", jsonRequest) } ``` * JavaScript ```javascript $.ajax({ type: "POST", url: "https://api.pushwoosh.com/json/1.3/createMessage", data: JSON.stringify({ "request": { "application": "APPLICATION CODE", "auth": "API TOKEN", "notifications": [{ "send_date": "now", "ignore_user_timezone": true, "content": "Hello world!" }] } }), dataType: "json" }).done(function(data) { console.log(data); }); ``` ## deleteMessage `POST` `https://api.pushwoosh.com/json/1.3/deleteMessage` Deletes a message, whether it’s still scheduled or has already been sent. For a scheduled message, this also removes it from Message History right away — for an already-sent message, see the caution below. Caution Deleting an already-sent message still succeeds, but Message History may keep showing it under its last status (`done`, `canceled`, `fail`) instead of marking it deleted. Follow-up sends created from the message with [Resend to non-openers](https://docs.pushwoosh.com/product/statistics-and-analytics/message-history/) are not affected — delete or cancel each of them separately. Use `/cancelMessage` instead if you want to stop the sending but keep the message in Message History with the `canceled` status. #### Request Body | Name | Type | Description | | --------- | ------ | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | message* | string | [Message code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#message-code) obtained in `/createMessage` request. | * 200 ```json { "status_code": 200, "status_message": "OK" } ``` Example ```json { "request":{ "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "message": "xxxx-xxxxxxx-xxxxxx" // required. Message code obtained in /createMessage } } ``` Note The method works for messages in the `pending`, `waiting`, `processing`, `done`, `canceled`, or `fail` status. It’s not allowed while a message is in the `creating` status — that returns a `210` error. **Status codes:** | HTTP Status code | status_code | Description | | ---------------- | ------------ | ----------------------------------------------------------------------------------------------------- | | 200 | 200 | Message successfully deleted | | 200 | 210 | Argument error, e.g. the message is still in the `creating` status. See status_message for more info | | 400 | N/A | Malformed request string | | 500 | 500 | Internal error | ```php setMessage('MESSAGE_CODE'); // call '/deleteMessage' Web Service $response = $pushwoosh->deleteMessage($request); if($response->isOk()) { print 'Great, my message has been deleted !'; } else { print 'Oups, the deletion failed :-('; print 'Status code : ' . $response->getStatusCode(); print 'Status message : ' . $response->getStatusMessage(); } ``` ## getMessageDetails `POST` `https://api.pushwoosh.com/json/1.3/getMessageDetails` Retrieves the message details. #### Request Body | Name | Type | Description | | --------- | ------ | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | message* | string | [Message code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#message-code) or message ID. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "message": { "id": 2068991743, "created": "2016-09-14 17:19:42", "send_date": "2016-09-14 17:19:41", "status": "done", "content": { "en": "Hello {Name|CapitalizeFirst|friend}! 🚀" }, "platforms": "[1]", "ignore_user_timezone": "1", "code": "XXXX-92B4C3C5-A7F5EF70", "data": { "key": "value" } } } } ``` Example ```json { "request":{ "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "message": "xxxx-xxxxxxx-xxxxxx" // required. message code or message ID } } ``` ## createTargetedMessage Deprecated `POST` `https://api.pushwoosh.com/json/1.3/createTargetedMessage` Creates a new targeted push notification. #### Request Body | Name | Type | Description | | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | devices_filter* | string | See remark below. | | send_date* | string | YYYY-MM-DD HH:mm or ‘now’. | | ignore_user_timezone | boolean | If ignored, UTC-0 is default for “send_date”. | | timezone | string | If ignored, UTC-0 is default for “send_date”. | | campaign | string | [Code of a campaign](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#campaign-code) to which you want to assign this push message. | | content* | string | Notification content. See the request example for details. | | transactionId | string | Unique message identifier to prevent duplicating messages in case of network problems. Stored on the side of Pushwoosh for 5 minutes. | | link | string | Link to be opened once a user opens a push message. | | minimize_link | integer | 0 - do not minimize, 2 - bit.ly. Default = 2. | | data | object | JSON string or JSON object. Will be passed as “u” parameter in the payload (converted to JSON string). | | preset | string | [Preset code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#preset-code). | | send_rate | integer | Throttling. Valid values are from 100 to 1000 pushes per second. | | inbox_date | string | Specify when to remove a message from the Inbox. | | inbox_image | string | URL of the image to be shown near the message in the Inbox. | Tip Pass an `X-Request-ID` header to correlate the created message with your request for end-to-end tracing — see [Request ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#request-id). * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "messageCode": "97B0-C7473871-2FBDFDC6" } } ``` * 400 JSON syntax errors ```plaintext The request cannot be fulfilled due to bad syntax. ``` More response examples: * 210 - syntax ```json { "status_code": 210, "status_message": "Errors occurred while compiling filter", "response": { "errors": [{ "message": "Invalid tag set specification. \")\" expected.", "type": "syntax" }] } } ``` * 210 - semantic ```json { "status_code": 210, "status_message": "Errors occurred while compiling filter", "response": { "errors": [{ "message": "Application \"11111-11111\" not found", "type": "semantic", "near": "\"11111-11111\"" }] } } ``` * 210 - lexical ```json { "status_code": 210, "status_message": "Errors occurred while compiling filter", "response": { "errors": [{ "message": "Invalid character \"/\" at 1:19", "type": "lexical" }] } } ``` Hard mode Should you be using [`/createMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api/#createmessage) instead? * Example Example ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "devices_filter": "A(\"XXXXX-XXXXX\") * T(\"City\", EQ, \"Name\")", // required. Syntax explained below "send_date": "now", // optional. YYYY-MM-DD HH:mm OR 'now' "ignore_user_timezone": true, // optional. "timezone": "America/New_York", // optional. If ignored UTC-0 is default for "send_date". // More info https://php.net/manual/timezones.php. "campaign": "CAMPAIGN_CODE", // optional. Campaign code to which you want to assign this push message. "content": { // optional. Object OR string. Use "wns_content" instead for Windows. "en": "English", "de": "Deutsch" }, "transactionId": "unique UUID", // optional. Unique message identifier to prevent duplicating messages // in case of network problems. Stored on the side of // Pushwoosh for 5 minutes. "rich_media": "XXXXX-XXXXX", // optional. Copy the Rich Media code from the URL bar of the // Rich Media editor page in Pushwoosh Control Panel. "link": "https://google.com", // optional. For deeplinks add "minimize_link": 0 "minimize_link": 0, // optional. 0 — do not minimize, 2 — bitly. Default = 2. // Google URL shortener is disabled since March 30, 2019. // Please note that shorteners have restrictions // on a number of calls. "data": { // optional. JSON string or JSON object. "key": "value" // Will be passed as "u" parameter in the payload }, // (converted to JSON string). "preset": "XXXXX-XXXXX", // optional. Push Preset Code from your Control Panel. "send_rate": 100, // optional. Throttling. Valid values are from 100 to 1000 pushes/second. "dynamic_content_placeholders": { // optional. Placeholders for dynamic content instead of device tags. "firstname": "John", "lastname": "Doe" }, // To save the message to the Inbox via API, use "inbox_date" or "inbox_image". // The message is saved when at least one of these parameters is used. "inbox_image": "Inbox image URL", // optional. The image to be shown near the message. "inbox_date": "2017-02-02" // optional. Specify when to remove a message from the Inbox. // Message will be removed from Inbox at 00:00:01 UTC of // the date specified, so the previous date is the last // day a user can see the message in their Inbox. // If not specified, the default removal date is the next // day after the send date. } } ``` * Platform-specific parameters Platform-specific parameters ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "devices_filter": "FILTER CONDITION", "send_date": "now", // optional. YYYY-MM-DD HH:mm OR 'now' "content": { // optional. Object OR string. "en": "English", // Use "wns_content" instead for Windows. "de": "Deutsch" }, "ignore_user_timezone": true, // optional. "timezone": "America/New_York", // optional. If ignored UTC-0 is default for "send_date". // More info https://php.net/manual/timezones.php. "campaign": "CAMPAIGN_CODE", // optional. Campaign code to which you want to assign this push message. // iOS related parameters "ios_badges": 5, // optional. iOS application badge number. // Use "+n" or "-n" to increment/decrement the badge value by n. "ios_sound": "sound file.wav", // optional. Sound file name in the main bundle of application. // If left empty, the device will produce no sound // upon receiving a push. "ios_sound_off": true, // optional. Enable/disable sound set by "ios_sound" field. "ios_ttl": 3600, // optional. Time to live parameter — maximum message lifespan in seconds. "ios_silent": 1, // optional. Enables silent notifications (ignore "sound" and "content"). "ios_category_id": "1", // optional. iOS8 category ID from Pushwoosh. "ios_category_custom": "category", // optional. Custom APNS category. "ios_root_params": { // optional. Root level parameters to the aps dictionary. "aps": { "content-available": "0", // optional. Set "1" to send a silent push and "0" for regular push. "mutable-content": 1 // required for iOS10+ Media attachments. }, "attachment": "YOUR_ATTACHMENT_URL", // iOS10+ media attachment URL. "data": {} // optional. User supplied data, max of 4KB }, "apns_trim_content": 1, // optional. (0|1) Trims the exceeding content strings with ellipsis. "ios_title": { // optional. Adds title for iOS push notification. "en": "title" }, "ios_subtitle": { // optional. Adds subtitle for iOS push notification. "en": "subTitle" }, "ios_content": { // optional. Adds content for iOS push notification. "en": "content" }, // Android related parameters "android_root_params": { // optional. Custom key-value object. "key": "value" // Root level parameters for the android payload recipients. }, "android_sound": "soundfile", // optional. No file extension. If left empty, the device // will produce no sound upon receiving a push. "android_sound_off": true, // optional. Enable/disable sound set by "android_sound" field "android_header": { // optional. Object OR string. Android notification header. "en": "header" }, "android_content": { // optional. Object OR string. Android notification content. "en": "content" }, "android_icon": "icon.png", "android_custom_icon": "URL.png", // optional. Full path URL to the image file. "android_banner": "URL.png", // optional. Full path URL to the image file. "android_badges": 5, // optional. integer. Android application icon badge number. // Use "+n" or "-n" to increment/decrement the badge value by n. "android_gcm_ttl": 3600, // optional. Time to live parameter — maximum message lifespan in seconds. "android_vibration": 0, // optional. Android force-vibration for high-priority pushes. "android_led": "#rrggbb", // optional. LED hex color, device will do its best approximation. "android_priority": -1, // optional. Sets the "importance" parameter for devices with Android 8.0 // and higher, as well as the "priority" parameter for devices // with Android 7.1 and lower. Establishes the interruption // level of a notification channel or a particular notification. // Valid values are -2, -1, 0, 1, 2. "android_delivery_priority": "normal", // optional. "normal" or "high". Enables notification’s delivery // when the device is in the power saving mode. "android_ibc": "#RRGGBB", // optional. icon background color on Lollipop, #RRGGBB, // #AARRGGBB, "red", "black", "yellow", etc. "android_silent": 1, // optional. 0 or 1. Enable silent notificaiton. // Ignore sound and content // Amazon related parameters "adm_root_params": { // optional. Custom key-value object "key": "value" }, "adm_sound": "push.mp3", "adm_sound_off": true, // optional. Enable/disable sound set by "adm_sound" field "adm_header": { "en": "Header" }, "adm_content": { "en": "content" }, "adm_icon": "icon.png", "adm_custom_icon": "URL.png", "adm_banner": "URL.png", "adm_ttl": 3600, // optional. Time to live parameter — the maximum message // lifespan in seconds. "adm_priority": -1, // optional. Priority of the push in Amazon push drawer, // valid values are -2, -1, 0, 1 and 2. // Mac OS X related parameters "mac_badges": 3, "mac_sound": "sound.caf", "mac_sound_off": true, "mac_root_params": { "content-available": 1 }, "mac_ttl": 3600, // optional. Time to live parameter — maximum message lifespan in seconds. "mac_title": { // optional. Adds Title for push notification. "en": "title" }, "mac_subtitle": { // optional. Adds subtitle for MacOS push notification. "en": "subtitle" }, "mac_content": { // optional. Adds content for MacOS push notification. "en": "content" }, // Windows related parameters "wns_content": { // required. Content (XML or raw) of notification encoded // in MIME's base64 in form of Object OR String "en": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48YmFkZ2UgdmFsdWU9ImF2YWlsYWJsZSIvPg==", "de": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48YmFkZ2UgdmFsdWU9Im5ld01lc3NhZ2UiLz4=" }, "wns_type": "Badge", // 'Tile' | 'Toast' | 'Badge' | 'Raw' "wns_tag": "myTag", // optional. Used in Tile replacement policy. // An alphanumeric string of no more than 16 characters. "wns_cache": 1, // optional. (1|0) Translates into X-WNS-Cache-Policy value. "wns_ttl": 600, // optional. Expiration time for notification in seconds. // Safari related parameters "safari_title": { // optional. Object OR string. Title of the notification. "en": "title" }, "safari_content": { // optional. Object OR string. Content of the notification. "en": "content" }, "safari_action": "Click here", // optional. "safari_url_args": [ // required. but the value may be empty "firstArgument", "secondArgument" ], "safari_ttl": 3600, // optional. Time to live parameter — the maximum // lifespan of a message in seconds. // Chrome related parameters "chrome_title": { // optional. You can specify the header of the message in this parameter. "en": "title" }, "chrome_content": { // optional. You can specify the content of the message in this parameter. "en": "content" }, "chrome_icon": "icon_URL", // optional. Full path URL to the icon or extension resources file path "chrome_gcm_ttl": 3600, // optional. Time to live parameter – maximum message lifespan in seconds. "chrome_duration": 20, // optional. Changes chrome push display time. Set to 0 to display push // until user interacts with it. "chrome_image": "image_URL", // optional. URL to large image "chrome_root_params": { // optional. Set parameters specific to messages sent to Chrome. "key": "value" }, "chrome_button_text1": "text1", // optional. "chrome_button_url1": "button1_URL", // optional. Ignored if chrome_button_text1 is not set. "chrome_button_text2": "text2", // optional. "chrome_button_url2": "button2_url", // optional. Ignored if chrome_button_text2 is not set. // Firefox related parameters "firefox_title": { // optional. Object OR string. You can specify message header here. "en": "title" }, "firefox_content": { // optional. Object OR string. You can specify message content here. "en": "content" }, "firefox_icon": "icon_URL", // optional. Full path URL to the icon or path // to the file in extension resources. "firefox_root_params": { // optional. Set parameters specific to messages sent to Firefox. "key": "value" } } } ``` The basics are very simple – all filters are performed on the **sets** of entities. ### Sets Sets are defined as: **1.** Devices subscribed to the particular app (A);\ **2.** Devices that match the specified tag values (T) or app-specific tag value (AT);\ ### Syntax Let’s try with some samples according to the list above. #### Targeting app subscribers The “A” filter defines a set of devices subscribed to a particular app: `A("XXXXX-XXXXX", ["iOS", "Android", "OsX", "Windows", "Amazon", "Safari", "Chrome", "Firefox"])` where * “XXXXX-XXXXX” – Pushwoosh Application Code * [“iOS”, “Android”, …] – array of targeted platforms. If omitted, the message will be sent to all platforms available for this app. #### Filtering by tag values The “T” filter defines a set of devices that have specified tag values assigned. `T(\"Age\", IN, [17,20])` Defines the set of the devices that have the “age” tag set to one of the values: 17, 18, 19, 20. Caution For **app-specific tags**, the “AT” filter is applied. Make sure to specify a corresponding Application Code as the first value in an AT set: `AT(“XXXXX-XXXXX”, “TagName”, EQ, “VALUE”)` ### Tags types and operators The very important thing to understand is that tags are shared between the apps, and it presents a very powerful instrument for segmenting and filtering your target users without binding yourself to a particular app. The tag could be one of the three different types: **String, Integer, List**. The tag type defines what operators you can use for a particular tag. #### String tags **Applicable operators:** * **EQ** – targets devices with a specified tag value * **IN** – targets devices with any of the specified tag values * **NOTIN** – targets devices with no specified tag values * **NOTEQ** – targets devices with a tag value not equal to a specified one * **NOTSET** – targets devices with no value for a specified tag * **ANY** – targets devices with any value set for a specified tag Examples: `T (\"Age\", EQ, 30)` – filters users in the age of 30 `T (\"favorite_color\", IN, [\"red\",\"green\",\"blue\"])` – filters users who have chosen red, green, or blue as their favorite color. `T (\"Name", NOTSET, \"\")` – target devices with no value for the Name tag. You can use numeric values with the string tags, but such values will be converted to a string. #### Integer tags **Applicable operators:** * **GTE** – greater than or equal to a specified value * **LTE**– less than or equal to a specified value * **EQ** – equal to a specified value * **BETWEEN** – between the min and max specified values * **IN** – any of specified values * **NOTIN** – no specified values assigned to a device * **NOTEQ** – devices with a tag value not equal to a specified one * **NOTSET** – devices with no value for a specified tag * **ANY** – devices with any value set for a specified tag Examples: `T (\"Level\", EQ, 14)` – filters users on the 14 level only. `T (\"Level\", BETWEEN, [1,5)` – filters users on 1, 2, 3, 4, and 5 levels. `T (\"Level", GTE, 29)` – targets users who have reached at least 29 level. #### List tags **Applicable operators:** * **IN** – devices with any of the specified tag values Example: `T("Category", IN, ["breaking_news","business","politics"])` #### Date tags **Applicable operators:** * **GTE** – greater than or equal to a specified value * **LTE**– less than or equal to a specified value * **EQ** – equal to a specified value * **BETWEEN** – between the min and max specified values * **NOTEQ** – devices with a tag value not equal to a specified one * **NOTSET** – devices with no value for a specified tag * **ANY** – devices with any value set for a specified tag Examples: `AT("7777D-322A7","Last Application Open", BETWEEN, ["2022-02-28", "2022-03-02"])` `AT("7777D-322A7","Last Application Open", GTE, "90 days ago")` ### Operations * “+” – joins two sets (equals OR) * “*” – intersects two sets (equals AND) * “\” – subtracts one set from another (equals NOT) All the operations are left-associative. ”+” and ”*” have the same priority. "" has greater priority. You can use brackets to define the priorities of the calculations. Note that “\” operation is not commutative. `A("12345-12345") \ A("67890-67890")` is not the same as `A("67890-67890") \ A("12345-12345")`. Note You cannot use any of the following targeting-related parameters in the /createTargetedMessage request: * “application” * “platforms” * “devices” * “filter” * “conditions” All the other parameters listed in [`/createMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api/#createmessage) are supported. Important There is a known issue with the `/createTargetedMessage` method: if you don’t specify any applications in “devices_filter” section, Pushwoosh doesn’t display any applications in push details. ## getPushHistory Deprecated Note Use [**/messages:list**](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#messageslist) to retrieve message history and more detailed data instead. `POST` `https://api.pushwoosh.com/json/1.3/getPushHistory` Gets message history with push details. #### Request Body | Name | Type | Description | | ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------- | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | limitMessages | integer | Limits the number of messages in a response. Possible values from 10 to 1000. | | source | string | Push history source. Can be null or: “CP”, “API”, “GeoZone”, “RSS”, “AutoPush”, “A/B Test”. | | searchBy | string | Possible values to search by. Can be null or: “notificationID”, “notificationCode”, “applicationCode”, “campaignCode”. | | value | string | Search value set according to the “searchBy” field. | | lastNotificationID | string | Used for pagination. Last messageId from the previous /getPushHistory call. See details below. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "rows": [{ "id": 10191611434, "code": "8071-07AD1171-77238AD1", "createDate": "2020-09-14 12:26:21", "sendDate": "2020-09-14 12:26:21", "content": { "en": "Hello!" }, "url": null, "ios_title": null, "ios_subtitle": null, "ios_root_params": null, "android_header": null, "android_root_params": null, "conditions": null, "conditions_operator": "AND", "filter_code": "E3A64-A5F3C", "filter_conditions": "#In-app Purchase(≠0)", "filter_name": "Purchased something", "geozone": null, "campaignId": "", "campaignName": "", "subscription_segments": null, "open": { "C90C0-0E786": { "IOS": 0 } }, "sent": { "C90C0-0E786": { "IOS": 1 } }, "ctr": { "C90C0-0E786": 0 } }, { "id": 10191609202, "code": "41CA-83F8E0D7-7A63822B", "createDate": "2020-09-14 12:25:55", "sendDate": "2020-09-14 12:25:55", "content": { "en": "Hi!" }, "url": null, "ios_title": null, "ios_subtitle": null, "ios_root_params": null, "android_header": null, "android_root_params": null, "conditions": null, "conditions_operator": "AND", "filter_code": null, "filter_conditions": null, "filter_name": null, "geozone": null, "campaignId": "", "campaignName": "", "subscription_segments": { "2D732-BB981": "News" }, "open": { "C90C0-0E786": { "CHROME": 0, "IOS": 0 } }, "sent": { "C90C0-0E786": { "CHROME": 1, "IOS": 2 } }, "ctr": { "C90C0-0E786": 0 } }] } } ``` Example ```json { "request":{ "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "source": null, // optional. Possible values are null, "CP", "API", "GeoZone", // "RSS", "AutoPush", "A/B Test" "searchBy": "applicationCode", // optional. Possible values are "", "notificationID", // "notificationCode", "applicationCode", "campaignCode" "value": "C8717-703F2", // optional. Search value set according to the "searchBy" field. "lastNotificationID": 0, // optional. Used for pagination. Last messageId from the // previous /getPushHistory call. See details below. "limitMessages": 1000 // optional. Possible value from 10 to 1000. } } ``` This method will return 1000 messages from the account sorted by message Id. To get the second page, specify the last message Id of previous response in the **lastNotificationId** parameter. ### Response data types ```plaintext id -- int | 0 code -- string createDate -- string (date: %Y-%m-%d %H:%M:%S) sendDate -- string (date: %Y-%m-%d %H:%M:%S) content -- array ( dict {lang: value} | list []) title -- array ( dict {lang: value} | list []) subtitle -- array ( dict {lang: value} | list []) url -- string ios_title -- string | array ( dict {lang: value} ) | null ios_subtitle -- string | array ( dict {lang: value} ) | null ios_root_params -- dict (JSON) | null android_header -- string | array ( dict {lang: value} ) | null android_root_params -- dict (JSON) | null conditions -- list (JSON) | null conditions_operator -- string | null filter_code -- string | null filter_name -- string | null filter_conditions -- string | null geozone -- string | null campaignId -- string | "" campaignName -- string | "" subscription_segments (obsolete) -- list (JSON) | null data -- dict (JSON) | null open -- dict [dict [string: int]] | "" Example: 'open': {'AAAAA-BBBBB': {'IOS': 1, 'ANDROID': 1}} sent -- dict [dict [string: int]] | "" Example: 'sent': {'AAAAA-BBBBB': {'IOS': 10, 'ANDROID': 10}} ctr -- dict [string: int] | "" Example: {'AAAAA-BBBBB': 1} errors -- dict [string: int] | "" Example: {'ANDROID': 1, 'IOS': 1} ``` ## cancelMessage `POST` `https://api.pushwoosh.com/json/1.3/cancelMessage` Cancels the sending of a scheduled message. The message remains in Message History with the `canceled` status. Follow-up sends created from it with [Resend to non-openers](https://docs.pushwoosh.com/product/statistics-and-analytics/message-history/) are canceled as well. Use `/deleteMessage` instead if you want the message removed from Message History (see the caution there about already-sent messages). #### Request Body | Name | Type | Description | | --------- | ------ | ----------------------------------------------------------------------------------------------------------------- | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | message* | string | The [Message code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#message-code) obtained in `/createMessage` response. | * 200 ```json { "status_code":200, "status_message":"OK" } ``` Note The method is only allowed for messages that are in the status of pending, waiting or processing. Example ```json { "request":{ "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "message": "xxxx-xxxxxxx-xxxxxx" // required. The message code obtained in /createMessage response } } ``` **Status codes:** | HTTP Status code | status_code | Description | | ---------------- | ------------ | -------------------------------------------------- | | 200 | 200 | Message successfully canceled | | 200 | 210 | Argument error. See status_message for more info. | | 400 | N/A | Malformed request string | | 500 | 500 | Internal error | --- # /createMessage parameters **URL:** https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/ List of parameters of the /createMessage API method --- Deprecated `/createMessage` is deprecated. New integrations should use [Messaging API v2](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/) — see the [migration guide](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/migration-from-v1/) for a field-by-field mapping of the parameters below. Here you’ll find the descriptions of the [`/createMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api/#createmessage) API parameters. * [Required parameters](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#required-parameters) must be included to successfully send a `/createMessage` API request and broadcast a push notification at the specified time. * [Optional parameters](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#optional-parameters) allow you to customize push notification properties. Note If you are using */createMessage* to send SMS, please refer to [Parameters for sending SMS](https://docs.pushwoosh.com/developer/api-reference/sms/#createsmsmessage). Other parameters will not be passed. ## Required parameters Required parameters are obligatory to use in [`/createMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api/#createmessage) requests. Otherwise, the request won’t be submitted. ### application Unique code of an app created in your Pushwoosh account. App code can be found at the top left corner of the Control Panel or in response to a [`/createApplication`](https://docs.pushwoosh.com/developer/api-reference/applications/#createapplication) request. The app code is a hyphen-separated set of 10 characters (both letters and digits). ![Pushwoosh application code displayed in the Control Panel at the top left corner](https://docs.pushwoosh.com/messages-api-prerequisites-1.webp) When creating an app via the API, you’ll get an app code in response to your [`/createApplication`](https://docs.pushwoosh.com/developer/api-reference/applications/#createapplication) request. To obtain a code of a previously created app via the API, call [`/getApplications`](https://docs.pushwoosh.com/developer/api-reference/applications/#getapplications). In response to the [`/getApplications`](https://docs.pushwoosh.com/developer/api-reference/applications/#getapplications) request, you’ll receive the list of all apps created in your Pushwoosh account with their names and codes. ### auth API access token from Pushwoosh Control Panel. Go to **Settings** → **API Access** and copy a token you’d like to use or generate a new one. ![API Access settings page in Pushwoosh Control Panel showing API access tokens](https://docs.pushwoosh.com/messages-api-prerequisites-2.webp) When generating an access token, specify its permissions. Check the checkboxes for those types of activities you’re going to use the API token with. You can create app-specific API tokens by checking the Applications checkboxes. ![API token generation dialog with permissions and application checkboxes](https://docs.pushwoosh.com/messages-api-prerequisites-3.webp) ### content The string or object that defines the message content. The “content” parameter submitted with a string type value will send the same message for all recipients. String ```txt "content": "Hello world!", ``` JSON objects are used for specifying content using [Dynamic Content](https://docs.pushwoosh.com/developer/guides/personalization/dynamic-content/), for example, for multi-language messages. Object ```txt "content": { "en": "Hello!", "es": "¡Hola!", "de": "Hallo!" }, ``` ### notifications The JSON array of push properties. Must include at least the required `content` and `send_date` parameters. Optional parameters to use within the “notifications” array: * [campaign](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#campaign) * [capping_days](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#capping_days) * [capping_count](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#capping_count) * [conditions](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#conditions) * [data](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#data) * [devices](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#devices) * [dynamic_content](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#dynamic_content) * [filter](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#filter) * [ignore_user_timezone](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#ignore_user_timezone) * [inbox_date](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#inbox_date) * [inbox_image](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#inbox_image) * [link](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#link) * [minimize_link](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#minimize_link) * [message_type](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#message_type) * [platforms](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#platforms) * [preset](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#preset) * [rich_media](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#rich_media) * [send_rate](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#send_rate) * [timezone](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#timezone) * [template_bindings](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#template_bindings) * [transactionId](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#transactionid) * [users](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#users) ### send_date Date and time on which the message is sent. Can be any date and time formatted as YYYY-MM-DD HH:mm or ‘now’. If set to ‘now’, the message will be sent immediately after submitting the request. ## Optional parameters ### campaign The code of a Campaign. To obtain a Campaign code, go to **Statistics** → **Aggregated statistics** and select the Campaign you’re going to use. The campaign code will be visible at the end of the page URL in the format `XXXXX-XXXXX`. **Example:** **URL:** `https://app.pushwoosh.com/applications/AAAAA-AAAAA/statistics/aggregated-message?campaignCode=XXXXX-XXXXX` **Campaign code:** `XXXXX-XXXXX` To obtain a list of Campaigns with their codes, call [`/getCampaigns`](https://docs.pushwoosh.com/developer/api-reference/campaigns/#getcampaigns). In response to the `/getCampaigns` request, you’ll receive the list of all Campaigns created for a particular app in your Pushwoosh account, with their codes, names, and descriptions. ### capping_days Period to be applied for frequency capping, in days (max 30 days). See [Frequency capping](https://docs.pushwoosh.com/product/messaging-channels/global-frequency-capping/) for details. Frequency capping is not applied to messages with `message_type: transactional`. In all other cases, frequency capping is applied, including requests where `message_type` is omitted. ### capping_count The maximum number of pushes that can be sent from a specific app to a particular device within a “capping_days” period. In case the message created exceeds the “capping_count” limit for a device, it won’t be sent to that device. See [Frequency capping](https://docs.pushwoosh.com/product/messaging-channels/global-frequency-capping/) for details. ### conditions Conditions are arrays like `[tagName, operator, operand]` used for sending targeted messages based on [Tags](https://docs.pushwoosh.com/developer/guides/audience-and-segmentation/tags/) and their values, where: * tagName — the name of a tag to apply, * [operator](https://docs.pushwoosh.com/developer/guides/audience-and-segmentation/tags#tag-operators) — a value comparison operator (“EQ” | “IN” | “NOTEQ” | “NOTIN” | “LTE” | “GTE” | “BETWEEN” | “NOTSET” | “ANY”), * [operand](https://docs.pushwoosh.com/developer/guides/audience-and-segmentation/tags#tag-values) — Tag values of any of the following types: string | integer | array | date | boolean | list #### Operator description | | | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **EQ** | tag value is equal to operand. | | **IN** | tag value intersects with operand (operand must always be an array). | | **NOTEQ** | tag value is not equal to an operand. | | **NOTIN** | tag value does not intersect with operand (operand must always be an array). | | **GTE** | tag value is greater than or equal to operand. | | **LTE** | tag value is less than or equal to operand. | | **BETWEEN** | tag value is greater than or equal to min operand value but less than or equal to max operand value (operand must always be an array). | | **NOTSET** | tag is not set. Operand is not considered. | | **ANY** | tag has any value. Operand is not considered. | #### String tags **Valid operators**: EQ, IN, NOTEQ, NOTIN, NOTSET, ANY **Valid operands:** | | | | ------------- | ---------------------------------------------------------------------------- | | **EQ, NOTEQ** | operand must be a string | | **IN, NOTIN** | operand must be an array of strings like `["value 1", "value 2", "value N"]` | | **NOTSET** | tag is not set. Operand is not considered | | **ANY** | tag has any value. Operand is not considered | #### Integer tags **Valid operators**: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE, NOTSET, ANY **Valid operands:** | | | | ----------------------- | ----------------------------------------------------------------------- | | **EQ, NOTEQ, GTE, LTE** | operand must be an integer | | **IN, NOTIN** | operand must be an array of integers like `[value 1, value 2, value N]` | | **BETWEEN** | operand must be an array of integers like `[min_value, max_value]` | | **NOTSET** | tag is not set. Operand is not considered | | **ANY** | tag has any value. Operand is not considered | #### Date tags **Valid operators**: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE, NOTSET, ANY **Valid operands:** * `"YYYY-MM-DD 00:00"` (string) * unix timestamp `1234567890` (integer) * `"N days ago"` (string) for operators EQ, BETWEEN, GTE, LTE #### Boolean tags **Valid operators**: EQ, NOTSET, ANY **Valid operands:** `0, 1, true, false` #### List tags **Valid operators**: IN, NOTIN, NOTSET, ANY **Valid operands:** operand must be an array of strings like `["value 1", "value 2", "value N"]`. Important Remember that “filter” and “conditions” parameters should not be used together.\ Also, both of them **will be ignored** if the “devices” parameter is used in the same request. Country and Language tags Language tag value is a lowercase two-letter code according to [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). Country tag value is an UPPERCASE two-letter code according to [ISO_3166-2](https://en.wikipedia.org/wiki/ISO_3166-2). For example, to send a push notification to Portuguese-speaking subscribers in Brazil, you will need to specify the following condition: `"conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]` ### conditions_operator Logical operator for conditions arrays. Possible values: AND | OR. AND is default. If the operator applied is AND (when no operator is specified, or the ‘conditions_operator’ param has the ‘AND’ value), devices simultaneously complying with all the conditions will receive the push notification. If the operator is OR, devices that comply with any of the specified conditions will receive the message. ### data JSON string or JSON object used to pass any [custom data](https://docs.pushwoosh.com/developer/guides/messaging-channels/using-custom-data) in the push payload; is passed as “u” parameter in the payload (converted to JSON string). ### devices The array of [push tokens](https://docs.pushwoosh.com/developer/pushwoosh-knowledge-hub/device-identifiers/#push-token) or [hwids](https://docs.pushwoosh.com/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) to send targeted push notifications. If set, the message will only be sent to the devices on the list. ### dynamic_content Placeholders for [Dynamic Content](https://docs.pushwoosh.com/product/personalization/dynamic-content) to be used instead of device Tag values. The example below will send the “Hello, John!” message to every user you target. If not set, the Dynamic Content values are taken from the device Tags. ```plaintext "content": "Hello, {firstname|CapitalizeFirst}!", "dynamic_content_placeholders": { "firstname": "John", "lastname": "Doe" }, ``` ### filter The name of a [Segment](https://docs.pushwoosh.com/product/audience-data-and-segmentation/segmentation/) exactly as it’s created in Pushwoosh Control Panel or via a [`/createFilter`](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api/#createfilter) API request. Go to the **Audience** → **Segments** section and check the list of Segments created. ![Segments list in the Audience section of Pushwoosh Control Panel](https://docs.pushwoosh.com/messages-api-prerequisites-7.webp) To get Segments list via the API, call the [`/listFilters`](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api/#listfilters) API method. In response to the `/listFilters` request, you’ll receive the list of all Segments created in your Pushwoosh account, with Segments’ names, conditions, and expiration dates. ### ignore_user_timezone If set to ‘true’, sends the message at the time and date specified in the “send_date” parameter according to UTC-0. If set to ‘false’, users will receive the message at the specified local time according to their device’s settings. ### inbox_date The date until which the message should be kept in users’ [Inbox](https://docs.pushwoosh.com/developer/guides/message-inbox/mobile-message-inbox). If not specified, the message will be removed from Inbox on the next day after the sending date. Note To save the message to Inbox, use at least one of the ‘inbox’ parameters: “inbox_date” or “inbox_image”. Caution Message will be removed from Inbox at 00:00:01 of the date specified, so the previous date is the last day a user can see the message in their Inbox. ### inbox_image The URL of the custom image to be shown near the message in [Inbox](https://docs.pushwoosh.com/developer/guides/message-inbox/mobile-message-inbox). Note To save the message to Inbox, use at least one of the ‘inbox’ parameters: “inbox_date” or “inbox_image”. ### inbox_days The lifetime of an inbox message in days, up to 30 days. After this period, the message will be removed from the inbox. Can be used instead of the **inbox_date** parameter. ### link The URL to be opened once a user opens a push notification. ### message_type Specifies the push message type. Available values are `marketing` and `transactional`. See [Marketing vs transactional messages](https://docs.pushwoosh.com/product/messaging-channels/marketing-vs-transactional/) for details. This parameter is optional. If omitted, users with `PW_ControlGroup: true` will not receive the message. ### minimize_link Shortener to minimize the URL submitted in the “link” parameter. Please note that push notification payload size is limited, so consider creating short URLs not to exceed the limit. Available values: 0 — do not minimize, 2 — bitly. Default = 2. Google URL shortener is disabled since March 30, 2019. ### platforms The array of platform codes to send the message to specific platforms only. Available platform codes include: `1` — iOS, `3` — Android, `7` — Mac OS X, `8` — Windows, `9` — Amazon, `10` — Safari, `11` — Chrome, `12` — Firefox, `14` — Email, `17` — Huawei, `18` — SMS, and `21` — WhatsApp. ### preset The code of a [Preset](https://docs.pushwoosh.com/product/content/push-presets/) created in Pushwoosh Control Panel or via API. To obtain a preset code, go **Content** → **Presets**, expand the preset you are going to use, and copy the **Preset Code** from preset’s details. ![Presets list in Content section showing Preset Code](https://docs.pushwoosh.com/messages-api-prerequisites-8.webp) ### rich_media The code of a [Rich Media](https://docs.pushwoosh.com/product/content/in-apps/) page you’re going to attach to your message. To obtain a code, go to **Content** → **Rich Media**, open a Rich Media page you are going to use, and copy the code from the URL bar of your browser. The code is a hyphen-separated set of 10 characters (both letters and digits). ![Rich Media page in Content section with Rich Media code in the browser URL bar](https://docs.pushwoosh.com/messages-api-prerequisites-9.webp) ### send_rate Throttling to restrain the push sending speed. Valid values are from 100 to 1000 pushes/second. ### timezone Timezone to be taken into account when the message is sent on a particular date and time. If set, the device’s timezone is ignored. If ignored, the message is sent in UTC. See for supported timezones. ### template_bindings Template placeholders to use in your content template. See the [Liquid Templates guide](https://docs.pushwoosh.com/developer/guides/personalization/liquid-templates/) for details. ### transactionId Unique message identifier to prevent duplicating messages in case of network problems. You can assign any ID to a message created via the [`/createMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api/#createmessage) or [`/createTargetedMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api/#createtargetedmessage) request. Stored on the side of Pushwoosh for 5 minutes. ### users The array of [userIds](https://docs.pushwoosh.com/developer/pushwoosh-knowledge-hub/users-userids/). User ID is a unique user identifier set by a [`/registerUser`](https://docs.pushwoosh.com/developer/api-reference/user-centric-api/), [`/registerDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api/#registerdevice), or [`/registerEmail`](https://docs.pushwoosh.com/developer/api-reference/email-api/) API request. --- # Messaging API v2 overview **URL:** https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/ Unified API for sending push, email, SMS, and messenger notifications through a single endpoint. --- Messaging API v2 is a single REST/JSON endpoint for creating outbound messages across every channel Pushwoosh supports: * Push: iOS, Android, Huawei, Baidu, macOS, Amazon, Windows, Safari, Chrome, Firefox, IE * Email * SMS * Telegram, Kakao, LINE, WhatsApp, Viber **Channel** is selected by the payload type (`payload` for push / SMS / messengers, `email_payload` for email). **Targeting** is selected by the request kind (`segment` for audience segments, `transactional` for explicit device or user lists). ## Base URL ```plaintext https://api.pushwoosh.com ``` If you use a dedicated region or private deployment, confirm the exact base URL with your Pushwoosh Customer Success Manager. ## Authentication Every request must include an `Authorization` header with a server-side Pushwoosh [API access token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#server-api-token): ```plaintext Authorization: Token YOUR_API_TOKEN ``` Use the same token you already issue for server-to-server API calls. Do not expose this token in client applications. ## Methods * [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/): `POST /messaging/v2/notify`. Create and send a single message (segment or transactional). * [`Cancel`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/cancel/): `POST /messaging/v2/cancel`. Cancel a previously created message that has not been delivered yet. * [`Update`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/update/): `POST /messaging/v2/update`. Replace a still-scheduled message with a new definition. ## Request and response format * Content type: `application/json`. * Field names use `snake_case`. `oneof` groups appear as nested objects with exactly one key set. * Enum values are serialized as their string names (for example, `"IOS"`, `"MESSAGE_TYPE_MARKETING"`). * Successful responses return HTTP 200 with a JSON body; errors use the standard gRPC-Gateway error envelope — `{ "code": ..., "message": ..., "details": [...] }`. ## Quick start Send a push to a segment ```bash 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 from v2!" }, "android": { "body": "Hello from v2!" } } } } }, "schedule": { "at": "2026-05-01T12:00:00Z" }, "message_type": "MESSAGE_TYPE_MARKETING" } }' ``` ## Sending email over SMTP If a service already speaks SMTP, you can submit transactional email through the [SMTP gateway](https://docs.pushwoosh.com/developer/api-reference/smtp-gateway/) instead of calling `Notify` directly. The gateway forwards each message to this API as a transactional `Notify`, so the same authentication and email payload rules apply. ## Next steps [Notify ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) [Cancel ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/cancel/) [Update ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/update/) [Payload reference ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/) [Email payload reference ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/email-payload-reference/) [SMTP gateway ](https://docs.pushwoosh.com/developer/api-reference/smtp-gateway/) [Migration from v1 ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/migration-from-v1/) --- # Cancel **URL:** https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/cancel/ Cancel a message before delivery using its message_code while the send is still pending, waiting, or processing. --- `POST` `https://api.pushwoosh.com/messaging/v2/cancel` Cancels a previously created message, identified by its `message_code`. Cancellation is available only while the message is in one of these states: * **pending:** created but not yet picked up for sending. * **waiting:** scheduled for a future send time. * **processing:** currently being prepared for delivery. Important * If the message is in `processing`, cancel only stops deliveries that have not gone out yet. Anyone who already received the message may still have it. * If the message was already canceled or has finished sending, the API returns `400`. This call is not idempotent. Check the message status before you retry. To check whether a message is still in a cancelable state, see [Checking message status](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/cancel/#checking-message-status). ## Request Authenticate with your [Server API token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#server-api-token) in the `Authorization: Token ` header. | Field | Type | Required | Description | | -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `message_code` | string | Yes | [Message code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#message-code) of the message to cancel, as returned by [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) in `result.message_code`. | ### Example request ```bash curl -X POST https://api.pushwoosh.com/messaging/v2/cancel \ -H "Authorization: Token YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "message_code": "XXXX-XXXXXXXX-XXXXXXXX" }' ``` ## Response On success, returns HTTP 200 with an empty JSON body. ```json {} ``` ## Errors Errors use the standard gRPC-Gateway error envelope: `{ "code": ..., "message": ..., "details": [...] }`. | HTTP status | Condition | | ----------- | ------------------------------------------------------------------------------------------------------- | | `400` | `message_code` is missing. | | `400` | The message is not in a cancelable state (it is no longer `pending`, `waiting`, or `processing`). | | `403` | The message belongs to another account. | | `404` | No message exists for the given `message_code`. | | `500` | An internal error occurred while loading the message or publishing the cancellation. Retry the request. | **Example** Canceling a message that no longer exists returns HTTP `404`: ```json { "code": 5, "message": "message not found", "details": [] } ``` ## Checking message status Before canceling, you can verify whether a message is still in a cancelable state. Besides reading the **Status** column in the messages table in the Control Panel ([**Campaigns → One-time messages**](https://docs.pushwoosh.com/product/statistics-and-analytics/message-history/)), you can query the status programmatically with [`messages:list`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#messageslist): * Pass the `message_code` in the `filters.messages_codes` array (alongside the required `filters.application`). * Read the `status` field of the matching entry in `items[]`. Note `messages:list` is part of the Statistics API and uses a different auth header than this endpoint: `Authorization: Api `. ## Related [Notify ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) [Update ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/update/) [Message statistics ](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#messageslist/) [Messaging API v2 overview ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/) [Migration from v1 ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/migration-from-v1/) --- # Email payload reference **URL:** https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/email-payload-reference/ Complete field reference for the v2 EmailPayload — subject, body, attachments, custom from/reply-to, and list-unsubscribe. --- Reference for the `EmailPayload` message used by [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) when sending email. Note For push / SMS / messenger payloads, see the [Payload reference](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/). ## EmailPayload * `subject` (map): subject line keyed by locale, e.g. `{"en": "Hello!", "es": "¡Hola!"}`. * `body` (string): HTML body of the email. For per-locale HTML bodies, use `email_template` with an [Email Template](https://docs.pushwoosh.com/product/content/email-content/) configured in the Control Panel. * `attachments` (array of [`Attachment`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/email-payload-reference/#attachment)): file attachments. * `list_unsubscribe` (string): custom URL for the `List-Unsubscribe` header. * `from` ([`Address`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/email-payload-reference/#address)): override the default `From` configured in the app’s email settings. * `reply_to` ([`Address`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/email-payload-reference/#address)): override the default `Reply-To` configured in the app’s email settings. * `email_template` (string): code of an [Email Template](https://docs.pushwoosh.com/product/content/email-content/) to use instead of an inline `body`. ## Attachment ```json { "name": "invoice.pdf", "content": "" } ``` | Field | Type | Description | | --------- | ------ | ----------------------------------- | | `name` | string | File name as the recipient sees it. | | `content` | string | Base64-encoded file content. | ## Address ```json { "name": "Pushwoosh", "email": "support@example.com" } ``` Both fields are optional. If `name` is omitted, the recipient sees the raw email address. ## Example: Send an email to a segment ```bash 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": ["EMAIL"], "code": "newsletter_subscribers", "email_payload": { "subject": { "en": "Our May updates", "es": "Novedades de mayo" }, "email_template": "may-digest-2026", "from": { "name": "Pushwoosh Team", "email": "news@example.com" }, "reply_to": { "email": "replies@example.com" } }, "schedule": { "at": "2026-05-01T09:00:00Z" }, "message_type": "MESSAGE_TYPE_MARKETING" } }' ``` ## Example: Transactional email with attachment ```bash 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"], "users": { "list": ["customer-42"] }, "email_payload": { "subject": { "en": "Your invoice" }, "body": "

Please find your invoice attached.

", "attachments": [ { "name": "invoice.pdf", "content": "JVBERi0xLjQKJe..." } ] }, "schedule": { "at": "2026-05-01T12:00:00Z" }, "message_type": "MESSAGE_TYPE_TRANSACTIONAL" } }' ``` --- # Migration from v1 **URL:** https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/migration-from-v1/ Field-by-field migration guide from /createMessage, /createTargetedMessage, /createEmailMessage, /createSMSMessage, /createKakaoMessage to /messaging/v2/notify. --- This guide maps every legacy `/create*Message` field onto its Messaging API v2 equivalent. Use it as a reference while porting existing integrations. Note Legacy v1 methods are deprecated but fully operational. There is no hard sunset date, so you can migrate at your own pace. For new integrations, use Messaging API v2. ## High-level differences | Aspect | v1 | v2 | | -------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | Endpoint per channel | separate method per channel (`/createMessage`, `/createEmailMessage`, `/createSMSMessage`, `/createKakaoMessage`, …) | single endpoint — `POST /messaging/v2/notify` | | Auth | `auth` field in the request body | `Authorization: Token ` header | | Targeting | mixed: `filter` + `conditions` + `devices` + `users` on the same request | explicit split: `NotifySegment` vs `NotifyTransactional` | | Content | flat `content` + sibling platform blocks | nested `payload.content.localized_content.{locale}.{platform}` | | Response | `MessageCode[]` | `message_code` + optional `unknown_identifiers` | ## From `/createMessage` v1 `notifications[*]` entries become individual `Notify` requests (one message each). If a v1 call has multiple entries, issue one `Notify` per entry. **Targeting decision.** If the v1 entry uses `devices` or `users` (explicit lists), map it to `transactional`. Otherwise map it to `segment`. ### Request-level fields * `application` → `segment.application` or `transactional.application` (same app-code format). * `applications_group`: not supported in v2. Use multiple per-app requests. * `auth`: moved to the `Authorization` header, no longer in the body. * `transactionId` → `transaction_id`, a request-level field alongside `segment` / `transactional`. Same deduplication behavior as v1: a repeat call with the same value within 5 minutes returns the original `message_code` instead of resending, matched on the key alone, not the payload. See [`transaction_id`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/#request-structure). ### Scheduling * `send_date` (`"YYYY-MM-DD HH:mm"` or `"now"`) → `schedule.at` (RFC 3339 UTC timestamp). To reproduce v1 `"now"`, set `schedule.at` to the current time. Any timestamp in the past is sent immediately. * `ignore_user_timezone` → `schedule.follow_user_timezone`. **Inverted:** `ignore_user_timezone: true` becomes `follow_user_timezone: false`. * `timezone`: not supported. v2 always uses UTC for `at`. Convert client-side. ### Targeting * `filter` (segment name) → `segment.code`. * `conditions` (`[[tag, op, value], ...]`) → `segment.expression`. Rewrite to a [seglang](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api/segmentation-language/) expression. In seglang, `*` is logical AND and app-specific tags are referenced as `Tag("", "", , )`. Example: `[["Country","EQ","BR"],["Language","EQ","pt"]]` with `conditions_operator: AND` → `Tag("XXXXX-XXXXX", "Country", EQ, "br") * Tag("XXXXX-XXXXX", "Language", EQ, "pt")`. * `conditions_operator` (`AND` / `OR`): folded into `segment.expression`. * `devices` (hwids or push tokens) → `transactional.hwids.list` or `transactional.push_tokens.list`. v2 separates the two: hwids go into `hwids`, raw push tokens into `push_tokens`. * `users` → `transactional.users.list`. * `platforms` (numeric codes `[1, 3, …]`) → `segment.platforms` or `transactional.platforms` (string enums `["IOS", "ANDROID", …]`). See [Platform enum](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/#platform-enum). ### Content * `content` (string) → `payload.content.localized_content.default.{platform}.body`. In v2, content is always per-locale and per-platform. Put a plain v1 string under the special `"default"` key (catch-all translation, see [Locale selection](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#locale-selection-for-a-device)). * `content` (`{locale: text}`) → `payload.content.localized_content.{locale}.{platform}.body`. Duplicate the body into each targeted platform block. * `preset` → `payload.preset`. * `data` → `payload.custom_data`. * `rich_media` → `payload.open_action.rich_media.code`. * `link` → `payload.open_action.link.url`. * `minimize_link` (`0` or `2`) → `payload.open_action.link.shortener` (`NONE` or `BITLY`). * `inbox_image` → `payload.content.localized_content.{locale}.{platform}.inbox.image_url` (each platform block has its own `inbox`). * `inbox_date` → `payload.content.localized_content.{locale}.{platform}.inbox.expiration_date`. * `inbox_days`: not supported. Convert to an absolute `expiration_date` client-side. ### Delivery controls * `dynamic_content` / `dynamic_content_placeholders` → `dynamic_content_placeholders` on `segment` or `transactional`. * `campaign` → `campaign` on `segment` or `transactional`. * `capping_days` → `frequency_capping.days`. * `capping_count` → `frequency_capping.count`. * `send_rate` (int) → `send_rate.value` with `send_rate.bucket: "1s"`. * `message_type` (`"marketing"` / `"transactional"`) → `message_type` (`MESSAGE_TYPE_MARKETING` / `MESSAGE_TYPE_TRANSACTIONAL`). ### Not supported in v2 * `template_bindings`: Liquid template bindings are not available in v2. Keep using v1 if you rely on them. ### Platform-specific blocks v1 accepts platform-specific parameters at the top level of each `notifications[*]` entry (`ios`, `android`, `safari`, `chrome`, …). In v2 they move inside the locale: ```plaintext // v1 "notifications": [{ "content": "Hello", "ios": { "title": "Hi", "sound": "default.caf" }, "android": { "header": "Hi", "led": "#ff0000" } }] // v2 "payload": { "content": { "localized_content": { "en": { "ios": { "title": "Hi", "body": "Hello", "sound": "default.caf" }, "android": { "title": "Hi", "body": "Hello", "led_color": "#ff0000" } } } } } ``` Field names within platform blocks differ in places. See the [Payload reference](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/) for the exact v2 names. ### Example: Before and after **v1 `/createMessage`** (push to a segment): ```json { "request": { "application": "XXXXX-XXXXX", "auth": "YOUR_API_TOKEN", "notifications": [{ "send_date": "2026-05-01 12:00", "content": "Hello!", "platforms": [1, 3], "filter": "active_users", "campaign": "YYYYY-YYYYY", "capping_days": 7, "capping_count": 3, "message_type": "marketing" }] } } ``` **v2 `/messaging/v2/notify`**: ```json { "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" }, "frequency_capping": { "days": 7, "count": 3 }, "campaign": "YYYYY-YYYYY", "message_type": "MESSAGE_TYPE_MARKETING" } } ``` ## From `/createTargetedMessage` `/createTargetedMessage` maps to `transactional` in most cases or to `segment` if you were using it purely as a cross-app `devices_filter` with no explicit identifiers. * `devices_filter` → `segment.expression` (seglang) or `segment.filter_expression` (structured). * `content` → `payload.content.localized_content.{locale}.{platform}.body`. * All other fields, same as `/createMessage` above. ## From `/createEmailMessage` Move to `Notify` with `platforms: ["EMAIL"]` and an `email_payload` block. Full reference: [Email payload reference](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/email-payload-reference/). * `subject` → `email_payload.subject` (map keyed by locale. Wrap single-locale values in `{"en": "..."}`). * `content` (HTML) → `email_payload.body`. * `email_template` → `email_payload.email_template`. * `from` / `from_name` → `email_payload.from` (`{ "name": "...", "email": "..." }`). * `reply_to` / `reply_to_name` → `email_payload.reply_to`. * `list_unsubscribe` → `email_payload.list_unsubscribe`. * `attachments` → `email_payload.attachments` (`[{ "name": "...", "content": "" }]`). * Targeting, schedule, campaign, etc., same as `/createMessage`. ## From `/createSMSMessage` Move to `Notify` with `platforms: ["SMS"]`. The SMS body is delivered through the app’s configured SMS provider. Put the content in `payload.content.localized_content.{locale}.{platform}.body` on any filled platform block. SMS-specific provider options (sender ID, etc.) continue to come from the app’s SMS configuration rather than the request body. `/createSMSMessage` has no MMS equivalent. To send MMS (subject + image attachments), use `sms.subject` and `sms.file_urls` — see [MMS](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#mms). ## From `/createKakaoMessage` Move to `Notify` with `platforms: ["KAKAO"]`, using `payload.content.localized_content.{locale}.kakao`: * `template_id` → `kakao.template`. * `content` → `kakao.content`. * `variables` → `kakao.content_variables` (JSON-stringified). ## From `/createWhatsAppMessage` Move to `Notify` with `platforms: ["WHATS_APP"]`, using `payload.content.localized_content.{locale}.whatsapp`: * `content` (free-form text) → `whatsapp.content`. Delivered by Meta only inside the 24-hour customer service window. * `content_id` → `whatsapp.content_id`. Name of a pre-approved Meta template. * `language` → `whatsapp.language`. Meta-template locale (e.g. `"en_US"`). Independent of the outer `LocalizedContent` locale key. * `content_variables` (object in v1) → `whatsapp.content_variables` (JSON-stringified object). Example v1 `{"1": "John"}` becomes v2 `"{\"1\":\"John\"}"`. * `button_url_variables` (object) → `whatsapp.button_url_variables` (JSON-stringified). * `header_variables` (object) → `whatsapp.header_variables` (JSON-stringified). * `preset` → `payload.preset` (generic preset on the payload level). * Targeting: the WhatsApp phone number that in v1 went into `devices` (e.g. `"whatsapp:+1234567890"`) must be registered via [`/registerDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api#registerdevice) against a user. In v2, target the resulting user with `transactional.users.list` (or the hwid via `transactional.hwids.list`). * `use_auto_registration`: not supported. Register the WhatsApp number before sending. ## From `/createLineMessage` Move to `Notify` with `platforms: ["LINE"]`, using `payload.content.localized_content.{locale}.line`: * `content` (plain text) → `line.content`. * `preset` (LINE preset code) → `line.template`. The v2 field stores a code that references a LINE template configured in the Pushwoosh Control Panel. * Inline `template` (v1 image, carousel, or flex message structures): not supported directly in v2. Pre-configure the rich message as a LINE preset in the Control Panel and reference it through `line.template`. * Targeting: the v1 `devices` list (LINE user IDs registered through the SDK / `/registerDevice`) becomes `transactional.users.list` (or the hwid via `transactional.hwids.list`) in v2. ## Response differences v1 `/createMessage` returns: ```json { "status_code": 200, "status_message": "OK", "response": { "Messages": ["XXXXX-XXXXX-AAAAA"] } } ``` v2 `Notify` returns: ```json { "result": { "message_code": "XXXXX-XXXXX-AAAAA", "unknown_identifiers": [] } } ``` Non-200 responses follow the standard gRPC-Gateway error envelope (`{ "code": ..., "message": ..., "details": [...] }`) instead of the v1 `status_code` / `status_message` pair. --- # Notify **URL:** https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/ Send a single message through any channel — push, email, SMS, Telegram, Kakao, LINE, WhatsApp, or Viber — using /messaging/v2/notify. --- `POST` `https://api.pushwoosh.com/messaging/v2/notify` Creates and schedules a single message. ## Request structure The request body is a `NotifyRequest` with exactly one of two kinds: * [`segment`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/#notifysegment): target an audience segment by segment code, a [seglang](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api/segmentation-language/) expression, or a structured filter expression. * [`transactional`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/#notifytransactional): send to an explicit list of hwids, user IDs, push tokens, or test devices. Shape ```json { "segment": { ... }, // OR "transactional": { ... }, "transaction_id": "unique-uuid" } ``` | Field | Type | Description | | ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `transaction_id` | string | Optional. Idempotency key for the request — works with both `segment` and `transactional`. A repeat call with the same `transaction_id` within 5 minutes returns the original `message_code` instead of sending a duplicate message. Use a UUID or another value unique per logical send. | Tip Pass an `X-Request-ID` header to correlate the created message with your request for end-to-end tracing — see [Request ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#request-id). Only the key is checked, not the payload Deduplication matches on `transaction_id` alone. If a retry reuses the same `transaction_id` but sends a different `segment` / `transactional` body, the original `message_code` is still returned and the new body is silently discarded — it is not compared against the first request. Never reuse a `transaction_id` across logically different messages. Tip This is the same deduplication mechanism as `transactionId` on the legacy [Messages API](https://docs.pushwoosh.com/developer/api-reference/messages-api/), sharing the same 5-minute storage window, so a retried request is deduplicated across `/createMessage` and `Notify` alike. It is unrelated to the `transaction_id` attribute on [`PW_Conversion`](https://docs.pushwoosh.com/product/audience-data-and-segmentation/events/conversion-events/#attributes-for-the-postevent-call) revenue events, which Pushwoosh stores as-is and does not use for deduplication. ## NotifySegment Targets users who match an audience segment or filter expression. | Field | Type | Description | | ------------------------------ | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | `schedule` | [`Schedule`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/#schedule) | When and how to send. Required. | | `application` | string | [Application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). | | `platforms` | array of [`Platform`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/#platform-enum) | Platforms the message targets. | | `code` | string | [Segment code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#segment--filter-code). Mutually exclusive with `expression` and `filter_expression`. | | `expression` | string | [Seglang](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api/segmentation-language/) expression. | | `filter_expression` | `FilterExpression` | Structured filter expression (advanced). | | `payload` | [`Payload`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/) | Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber payload. Mutually exclusive with `email_payload`. | | `email_payload` | [`EmailPayload`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/email-payload-reference/) | Email payload. | | `campaign` | string | [Campaign code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#campaign-code) to attribute this message to. | | `frequency_capping` | [`FrequencyCapping`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/#frequencycapping) | Per-user frequency limits. | | `send_rate` | [`SendRate`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/#sendrate) | Throttling for the send. | | `message_type` | [`MessageType`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/#messagetype-enum) | `MESSAGE_TYPE_MARKETING` (default) or `MESSAGE_TYPE_TRANSACTIONAL`. Controls control-group filtering. | | `dynamic_content_placeholders` | map | Replaces placeholders in content. | | `meta_data` | object | Free-form metadata forwarded to downstream analytics. | ### Example: Send to a segment ```bash 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 Sends to an explicit list of recipients. | Field | Type | Description | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `schedule` | [`Schedule`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/#schedule) | Required. | | `application` | string | [Application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). | | `platforms` | array of [`Platform`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/#platform-enum) | Platforms the message targets. | | `test_devices` | bool | If `true`, send to the app’s test devices only. | | `hwids` | `{ "list": [string, ...] }` | Send to these [hwids](https://docs.pushwoosh.com/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) only. | | `users` | `{ "list": [string, ...] }` | Send to these [user IDs](https://docs.pushwoosh.com/developer/pushwoosh-knowledge-hub/users-userids/) only. | | `push_tokens` | `{ "list": [string, ...] }` | Send to these [push tokens](https://docs.pushwoosh.com/developer/pushwoosh-knowledge-hub/device-identifiers/#push-token) only. | | `payload` | [`Payload`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/) | Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber payload. | | `email_payload` | [`EmailPayload`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/email-payload-reference/) | Email payload. | | `return_unknown_identifiers` | bool | When `true`, the response’s `unknown_identifiers` lists identifiers that were not found. | | `use_latest_user_device` | bool | Only applies when you target `users`. When `true`, the message is delivered to each user’s most recently active device — the one with the latest Last Application Open — instead of all devices tied to that user ID. Defaults to `false` (send to every device). | | `campaign`, `frequency_capping`, `send_rate`, `message_type`, `dynamic_content_placeholders`, `meta_data` | | See `NotifySegment` above. | `test_devices`, `hwids`, `users`, and `push_tokens` are mutually exclusive. Exactly one must be set. ### Example: Transactional by user IDs ```bash 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 } }' ``` ## Response ```json { "result": { "message_code": "XXXXX-XXXXX-XXXXX", "unknown_identifiers": [] } } ``` | Field | Type | Description | | --------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `message_code` | string | Unique [message code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#message-code). Use it with [`/getMessageDetails`](https://docs.pushwoosh.com/developer/api-reference/messages-api/#getmessagedetails) and message statistics endpoints. | | `unknown_identifiers` | array of string | Identifiers not found on the account. Populated only when `return_unknown_identifiers: true` was set on the `transactional` kind. | ## Shared types ### Schedule ```json { "at": "2026-05-01T12:00:00Z", "follow_user_timezone": true, "past_timezones_behaviour": "PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY" } ``` | Field | Type | Description | | -------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `at` | timestamp | Absolute send time (RFC 3339). If in the past, the message is sent immediately. Maximum 14 days in the future. | | `after` | duration | Alternative to `at`. Send after this offset from “now” (e.g. `"3600s"`). | | `follow_user_timezone` | bool | When `true`, each device receives the message at `at` in its local timezone. | | `past_timezones_behaviour` | enum | `PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY` (default), `PAST_TIMEZONES_BEHAVIOUR_DO_NOT_SEND`, or `PAST_TIMEZONES_BEHAVIOUR_NEXT_DAY`. Only meaningful when `follow_user_timezone` is `true`. | ### FrequencyCapping Per-user frequency limits for marketing sends. To disable capping, omit `frequency_capping` entirely, or send `days: 0` together with `count: 0`. ```json { "days": 7, "count": 3, "exclude": false, "avoid": true } ``` * `days` (int, 1–30, or `0` to disable capping): look-back window. Must be sent together with `count` — if one is `0`, the other must also be `0`; sending one as `0` while the other is nonzero returns `400`. * `count` (int, 1 or higher, or `0` to disable capping): maximum messages allowed within `days`. Same pairing rule as `days` above. * `exclude` (bool): hard-exclude users who have already hit the cap. * `avoid` (bool): soft-avoid users who have already hit the cap (they still count toward analytics). Important Sending `days` and `count` with mismatched zero-ness (e.g. `{"days": 0, "count": 5}`) returns `400`. This validation is a breaking change to `Notify` — clients that previously relied on a lone `0` being silently ignored will now get an error instead. ### SendRate ```json { "value": 500, "bucket": "1s", "avoid": false } ``` Throttles the send. `value` is messages per `bucket`; typical `bucket` is `"1s"`. ### Platform enum `IOS`, `ANDROID`, `OSX`, `WINDOWS`, `AMAZON`, `SAFARI`, `CHROME`, `FIREFOX`, `IE`, `EMAIL`, `BAIDU_ANDROID`, `HUAWEI_ANDROID`, `SMS`, `WEB`, `KAKAO`, `TELEGRAM`, `LINE`, `WHATS_APP`, `VIBER`. ### MessageType enum * `MESSAGE_TYPE_UNSPECIFIED`: equivalent to `MESSAGE_TYPE_MARKETING`. * `MESSAGE_TYPE_MARKETING`: subject to control-group filtering and frequency capping. * `MESSAGE_TYPE_TRANSACTIONAL`: skips control-group filtering and frequency capping. Use for order confirmations, OTPs, and similar critical flows. ## Related [Cancel ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/cancel/) [Payload reference ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/) [Email payload reference ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/email-payload-reference/) [Migration from v1 ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/migration-from-v1/) --- # Payload reference **URL:** https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/ Complete field reference for the v2 Payload including push content, rich media, deep links, inbox, and per-platform properties. --- Reference for the `Payload` message used by [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) when sending through any non-email channel (push, SMS, Telegram, Kakao, LINE, Viber, WhatsApp). Note For email, see the [Email payload reference](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/email-payload-reference/). ## Payload * `preset` (string): [push preset](https://docs.pushwoosh.com/product/content/push-presets/) code (format `XXXXX-XXXXX`) to apply to this message. * `sms_preset` (string): code (format `XXXXX-XXXXX`) of a saved [SMS preset](https://docs.pushwoosh.com/product/content/sms-presets/). Its per-locale text is resolved into each locale’s [`sms.body`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#sms-sms). An inline `sms.body` for a given locale overrides the preset for that locale. The preset must belong to the same application as the message. * `content` ([`LocalizedContent`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#localizedcontent)): message content. Mutually exclusive with `silent`. * `silent` (bool): send a silent (data-only) push. Mutually exclusive with `content`. * `custom_data` (object): free-form JSON forwarded to the client SDK as the `u` parameter. * `open_action` ([`OpenAction`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#openaction)): action triggered when the user opens the notification. * `open_actions` (map): per-platform override of `open_action`. Key is a numeric `Platform` enum value. * `voip_push` (bool): iOS VoIP notification. ```json { "payload": { "preset": "XXXXX-XXXXX", "content": { "localized_content": { "default": { "ios": { "title": "Hello", "body": "Tap to view" } } } }, "custom_data": { "order_id": "42" }, "open_action": { "link": { "url": "https://example.com/promo" } } } } ``` ## LocalizedContent Maps locale code → per-platform content. Keys are [ISO 639-1](https://www.loc.gov/standards/iso639-2/php/code_list.php) two-letter codes (for example, `"en"`, `"es"`) plus the special key `"default"` for a catch-all translation. The exceptions to ISO 639-1 are `"zh-Hant"` and `"zh-Hans"` for Traditional and Simplified Chinese. ```json { "localized_content": { "default": { "ios": { "title": "Hello", "body": "Tap to view" }, "android": { "title": "Hello", "body": "Tap to view" } }, "es": { "ios": { "title": "Hola", "body": "Toca para ver" }, "android": { "title": "Hola", "body": "Toca para ver" } } } } ``` ### Locale selection for a device Content delivered to a device is picked in this order: 1. Exact match on the device’s language. 2. Key `"default"`. 3. Key `"en"`. 4. Any other locale present in the map. Provide at least one of `"default"` or `"en"` so every device has a deterministic fallback. If you do not expect per-locale variants, send only `"default"`. Each locale entry is a `Content` object with optional per-platform blocks. Only fill in the platforms you target. | Platform block | Channel | | ---------------- | ----------------------------------- | | `ios` | iOS push | | `android` | Android (FCM) push | | `huawei_android` | Huawei Android push | | `baidu_android` | Baidu Android push | | `mac_os` | macOS push | | `amazon` | Amazon (ADM) push | | `safari` | Safari web push | | `chrome` | Chrome web push | | `firefox` | Firefox web push | | `ie` | Internet Explorer web push | | `windows` | Windows push (tile / toast / badge) | | `telegram` | Telegram message | | `kakao` | Kakao message | | `line` | LINE message | | `viber` | Viber message | | `whatsapp` | WhatsApp message | | `sms` | SMS message | ## Common push fields These fields are shared by `ios`, `android`, `huawei_android`, `baidu_android`, `mac_os`, `amazon`, `safari`, `chrome`, and `firefox` blocks (support varies. Unused fields are ignored by the relevant platform). * `title` (string): notification title. * `body` (string): notification body. * `time_to_live` (duration, e.g. `"3600s"`): how long the push server should retain the notification for an offline device. * `sound` (string): sound file name. * `sound_enabled` (bool): enable or suppress sound. * `badges` (string): badge count (iOS) or analogue. * `root_params` (object): raw platform-specific payload overrides. * `inbox` ([`Inbox`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#inbox)): [Message Inbox](https://docs.pushwoosh.com/developer/guides/message-inbox/mobile-message-inbox/) entry. ```json { "android": { "title": "Hello", "body": "Tap to view", "time_to_live": "3600s", "sound": "default", "sound_enabled": true, "badges": "+1" } } ``` ## iOS (`ios`) * `subtitle` (string): iOS notification subtitle. * `is_critical` (bool): critical alert (requires entitlement). * `attachment` (string): URL of a media attachment. * `thread_id` (string): thread identifier for grouped notifications. * `trim_content` (bool): trim content to fit. * `category_id` (string): `UNNotificationCategory` identifier for interactive actions. * `interruption_level` (string): `passive`, `active`, `time-sensitive`, or `critical`. * `collapse_id` (string): APNs collapse identifier. Notifications with the same `collapse_id` replace each other on the device. ```json { "ios": { "title": "Hello", "body": "Tap to view", "subtitle": "New update", "attachment": "https://cdn.example.com/image.png", "interruption_level": "active", "thread_id": "promo" } } ``` ## Android (`android`, `huawei_android`, `baidu_android`) * `icon` (string): notification small icon. * `banner` (string): big-picture URL. * `delivery_priority` (`NORMAL` | `HIGH`): FCM delivery priority. * `vibration` (bool): vibration on receive. * `led_color` (string, hex): notification LED color. * `icon_background_color` (string, hex): icon background color. * `show_on_lockscreen` (bool): show on the lock screen. * `custom_icon` (string): URL of a custom icon. * `priority` ([`NotificationPriority`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#notificationpriority-enum)): in-tray priority. * `group_id` (string): notification group key. * `collapse_key` (string): FCM collapse key. Notifications with the same `collapse_key` replace each other while the device is offline. ```json { "android": { "title": "Hello", "body": "Tap to view", "icon": "ic_notification", "banner": "https://cdn.example.com/banner.png", "led_color": "#FF0000", "priority": "PRIORITY_HIGH", "delivery_priority": "HIGH" } } ``` ## macOS (`mac_os`) Uses the common push fields plus `subtitle` and `action` (URL opened when the user clicks the notification). ```json { "mac_os": { "title": "Hello", "body": "Tap to view", "subtitle": "New update", "action": "https://example.com/promo" } } ``` ## Amazon (`amazon`) Uses the common push fields plus `custom_icon` and `priority` ([`NotificationPriority`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#notificationpriority-enum)). ```json { "amazon": { "title": "Hello", "body": "Tap to view", "custom_icon": "https://cdn.example.com/icon.png", "priority": "PRIORITY_HIGH" } } ``` ## Safari (`safari`) * `action` (string): URL opened when the user clicks the notification. * `url_arguments` (array of string): Safari URL arguments substituted into the Web Push URL template. ```json { "safari": { "title": "Hello", "body": "Tap to view", "action": "https://example.com/promo", "url_arguments": ["promo", "2026"] } } ``` ## Chrome (`chrome`) * `icon`, `image` (string): small icon and large image URLs. * `duration` (duration): auto-close timer. * `button_text1` / `button_url1`, `button_text2` / `button_url2`: up to two action buttons. ```json { "chrome": { "title": "Hello", "body": "Tap to view", "icon": "https://cdn.example.com/icon.png", "image": "https://cdn.example.com/banner.png", "duration": "20s", "button_text1": "Open", "button_url1": "https://example.com/promo" } } ``` ## Firefox (`firefox`) Uses only `title`, `body`, `icon`, `root_params`, and `inbox`. ```json { "firefox": { "title": "Hello", "body": "Tap to view", "icon": "https://cdn.example.com/icon.png" } } ``` ## Windows (`windows`) Windows uses a different shape: ```json { "windows": { "type": "TOAST", "template": { "title": "Hello", "body": "Tap to view" }, "tag": "promo", "cache": true, "time_to_live": "3600s" } } ``` * `type` is `TILE`, `TOAST`, or `BADGE`. * `template` (structured) or `raw` (`{ "content": "" }`) — exactly one. ## Telegram (`telegram`) * `body` (string): message text. * `content_variables` (string): JSON-stringified variables for the bot-side template. ```json { "telegram": { "body": "Hello from Pushwoosh", "content_variables": "{\"name\":\"John\"}" } } ``` ## Kakao (`kakao`) * `content` (string): message content. * `template` (string): approved template code. * `content_variables` (string): JSON-stringified template variable bindings. ```json { "kakao": { "content": "Hello from Pushwoosh", "template": "welcome_v1", "content_variables": "{\"name\":\"John\"}" } } ``` ## LINE (`line`) * `content` (string): plain text body. * `template` (string): code of a LINE template configured in the Pushwoosh Control Panel (used to send image, carousel, or flex messages). For rich content, pre-configure the template in the Control Panel and reference it here. At least one of `content` or `template` must be set. ```json { "line": { "content": "Hello from Pushwoosh", "template": "promo_carousel" } } ``` ## Viber (`viber`) A Viber message is either a free-text body or a pre-approved transactional template (Omni Messaging / MStat) referenced by id and language. * `body` (string): plain text message. Required when `template_id` is not set. * `template_id` (string): id of a pre-approved transactional template. When set, it takes precedence over `body`. * `template_lang` (string): template locale. Required when `template_id` is set. * `template_params` (map): key/value bindings substituted into the template, e.g. `{ "name": "John", "code": "123456" }`. * `all_devices` (bool): `false` (default) delivers to the user’s primary device only; `true` delivers to all of the user’s devices. At least one of `body` or `template_id` must be set. When `template_id` is set, `template_lang` is required. Address Viber recipients as hwids in the form `viber:` (E.164), for example `viber:+1234567890`. Plain text: ```json { "viber": { "body": "Hello from Pushwoosh" } } ``` Transactional template: ```json { "viber": { "template_id": "e3dec4a0-c063-4b0f-96d5-cf9d629a7abe", "template_lang": "en", "template_params": { "name": "John", "code": "123456", "expires_in": "5 minutes" }, "all_devices": false } } ``` ## WhatsApp (`whatsapp`) WhatsApp messages go through Meta and are subject to Meta’s messaging rules. The key split is between free-form text (only delivered inside the 24-hour customer service window opened by an inbound message from the user) and approved templates (required for outbound initiation and for any message outside the 24-hour window). * `content` (string): free-form message text. Delivered by Meta only inside the 24-hour window. * `content_id` (string): name of a pre-approved Meta template (e.g. `"hello_world"`). Required for outbound initiation or any message outside the 24-hour window. * `language` (string): template locale that must exactly match the locale approved in Meta (e.g. `"en_US"`, `"en_GB"`). Only meaningful together with `content_id`. This is independent of the outer `LocalizedContent` key. The outer key selects content for a device, and `language` selects the Meta-template locale for that content. * `content_variables` (string): JSON object mapping body placeholders, e.g. `"{\"1\":\"John\"}"`. * `button_url_variables` (string): JSON object mapping button-URL placeholders keyed by button index, e.g. `"{\"0\":\"https://...\"}"`. * `header_variables` (string): JSON object mapping header placeholders keyed by type, e.g. `"{\"image\":\"https://...\"}"`. At least one of `content` or `content_id` must be set. ```json { "whatsapp": { "content_id": "hello_world", "language": "en_US", "content_variables": "{\"1\":\"John\"}" } } ``` ## SMS (`sms`) SMS has its own platform block inside each locale’s [`Content`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#localizedcontent), alongside `ios`, `android`, and the other messaging channels. * `body` (string): SMS text for the locale. Required when the `sms` block is present. There are two ways to supply the text: * **Inline** — set `sms.body` per locale in `localized_content`. * **From a preset** — set the payload-level [`sms_preset`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#payload) to the code (format `XXXXX-XXXXX`) of a saved [SMS preset](https://docs.pushwoosh.com/product/content/sms-presets/). Its per-locale content is resolved into `sms.body` for each locale the preset defines. An inline `sms.body` for a locale overrides the preset for that locale, so you can reuse a preset and still tweak individual languages. ```json { "payload": { "sms_preset": "XXXXX-XXXXX", "content": { "localized_content": { "default": { "sms": { "body": "Your order has shipped." } }, "es": { "sms": { "body": "Tu pedido ha sido enviado." } } } } } } ``` ### MMS Adding `subject` and `file_urls` to an `sms` block turns the message into an MMS. Only [AbleMobile](https://ablemobile.com/) has an MMS endpoint — other SMS providers ignore both fields and deliver the plain-text `body` only. * `subject` (string): MMS subject. Requires at least one entry in `file_urls` — a subject without attachments is rejected. Up to 40 ASCII characters, or 13 characters if the subject contains non-ASCII characters. * `file_urls` (array of string): up to 3 attachment URLs. Each must be an absolute `https` URL ending in `.jpg` or `.gif` — `.jpeg` and `.png` are rejected by validation, even for a genuine JPEG or PNG file, because the provider can’t decode them. Each file must also be 200 KB or smaller; AbleMobile rejects the whole send if any attachment is heavier. * `message_at` (int): index into `file_urls` (0-based) that the SMS body text is shown after. `subject` and `file_urls` support [Liquid personalization](https://docs.pushwoosh.com/developer/guides/personalization/liquid-templates/), same as `body`. ```json { "sms": { "body": "Your order has shipped.", "subject": "Order update", "file_urls": [ "https://cdn.example.com/shipping-label.jpg", "https://cdn.example.com/tracking-map.gif" ], "message_at": 1 } } ``` ## OpenAction Defines the action performed when the user opens the message. Exactly one of: * `rich_media` ([`RichMedia`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#richmedia)): open a [Rich Media](https://docs.pushwoosh.com/product/content/in-apps/) page. * `deep_link`: open a deep link: `{ "code": "flow-code", "params": { "key": "value" } }`. * `link` ([`Link`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#link)): open a URL. ```json { "open_action": { "deep_link": { "code": "flow-code", "params": { "promo": "summer" } } } } ``` The deeplink URL and `params` values support [Liquid personalization](https://docs.pushwoosh.com/developer/guides/personalization/liquid-templates/) syntax — expressions are resolved before the deep link is opened. ### RichMedia ```json { "code": "XXXXX-XXXXX" } // by Rich Media code { "url": "https://..." } // by remote URL ``` ### Link ```json { "url": "https://example.com/promo", "shortener": "BITLY" } ``` `shortener` is `NONE` (default) or `BITLY`. ## Inbox Configures how the message appears in Message Inbox. ```json { "image_url": "https://cdn.example.com/inbox.png", "expiration_date": "2026-05-15T00:00:00Z" } ``` * `image_url` (string): image shown in the inbox entry. * `expiration_date` (timestamp): when the entry is removed from the inbox. ## NotificationPriority enum Controls notification priority on the target device, from `PRIORITY_MIN` (lowest) to `PRIORITY_MAX` (highest). * `PRIORITY_UNSPECIFIED` * `PRIORITY_MIN` * `PRIORITY_LOW` * `PRIORITY_DEFAULT` * `PRIORITY_HIGH` * `PRIORITY_MAX` Caution Always send `priority` as one of the string values above. The API also accepts the enum’s numeric equivalents (1-5, matching the order above), but that mapping is an internal protobuf detail, not a supported contract — don’t rely on it. An unrecognized `priority` value (a misspelled string or an out-of-range number) is not rejected: the API silently drops it, and the notification is sent with no `priority` field at all instead of returning an error. ## Example: Send a push to a segment ```bash 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": { "title": "Hello", "body": "Hello, world!" }, "android": { "title": "Hello", "body": "Hello, world!" } }, "es": { "ios": { "title": "¡Hola!", "body": "¡Hola, mundo!" }, "android": { "title": "¡Hola!", "body": "¡Hola, mundo!" } } } }, "open_action": { "link": { "url": "https://example.com/promo" } } }, "schedule": { "at": "2026-05-01T12:00:00Z" }, "message_type": "MESSAGE_TYPE_MARKETING" } }' ``` ## Example: Transactional push by user IDs ```bash 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": ["customer-42"] }, "payload": { "content": { "localized_content": { "default": { "ios": { "title": "Your order", "body": "Order #42 has shipped." }, "android": { "title": "Your order", "body": "Order #42 has shipped." } } } }, "custom_data": { "order_id": "42" } }, "schedule": { "at": "2026-05-01T12:00:00Z" }, "message_type": "MESSAGE_TYPE_TRANSACTIONAL" } }' ``` --- # Update **URL:** https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/update/ Replace a scheduled message with a new definition using its message_code before the send starts. --- `POST` `https://api.pushwoosh.com/messaging/v2/update` Replaces a previously created message, identified by its `message_code`, with a new definition. The replacement is a **full replace, not a patch**: the new definition is applied exactly as sent, and the `message_code` does not change. Update is available only while the message is still **pending** — scheduled for a future send and not yet picked up for processing or delivery. Important * The `request` field is a complete [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) definition. Fields you omit are **not** carried over from the original message — they are reset. Send the full message you want, not just the changed parts. * If the message is already processing, has been delivered, was canceled, or was deleted, the API returns `400`. This call is not idempotent. Check the message status before you update. To check whether a message is still in an updatable state, see [Checking message status](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/update/#checking-message-status). ## Request Authenticate with your [Server API token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#server-api-token) in the `Authorization: Token ` header. | Field | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `message_code` | string | Yes | [Message code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#message-code) of the message to update, as returned by [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) in `result.message_code`. | | `request` | object | Yes | The full new definition of the message. Same shape as the [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) request body — a `segment` or `transactional` object. Validated exactly like `Notify`. | ### Example request Reschedule a segment message and change its content: ```bash curl -X POST https://api.pushwoosh.com/messaging/v2/update \ -H "Authorization: Token YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "message_code": "XXXX-XXXXXXXX-XXXXXXXX", "request": { "segment": { "application": "XXXXX-XXXXX", "platforms": ["IOS", "ANDROID"], "code": "active_users", "payload": { "content": { "localized_content": { "en": { "ios": { "body": "Updated message" }, "android": { "body": "Updated message" } } } } }, "schedule": { "at": "2026-05-02T12:00:00Z" }, "message_type": "MESSAGE_TYPE_MARKETING" } } }' ``` ## Response On success, returns HTTP 200 with the result of the updated message. The `message_code` is unchanged. ```json { "result": { "message_code": "XXXX-XXXXXXXX-XXXXXXXX", "unknown_identifiers": [] } } ``` * `message_code` (string): the same code that was passed in the request. * `unknown_identifiers` (array of string): identifiers in the new definition that were not found, when applicable (see [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/)). ## Errors Errors use the standard gRPC-Gateway error envelope: `{ "code": ..., "message": ..., "details": [...] }`. | HTTP status | Condition | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `400` | `message_code` is missing. | | `400` | The new `request` definition is missing or invalid (it is validated exactly like [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/)). | | `400` | The message is not in an updatable state (it is no longer `pending`). | | `403` | The message belongs to another account. | | `404` | No message exists for the given `message_code`. | | `500` | An internal error occurred while loading the message or applying the update. Retry the request. | **Example** Updating a message that no longer exists returns HTTP `404`: ```json { "code": 5, "message": "message not found", "details": [] } ``` ## Checking message status Before updating, you can verify whether a message is still in an updatable state. Besides reading the **Status** column in the messages table in the Control Panel ([**Campaigns → One-time messages**](https://docs.pushwoosh.com/product/statistics-and-analytics/message-history/)), you can query the status programmatically with [`messages:list`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#messageslist): * Pass the `message_code` in the `filters.messages_codes` array (alongside the required `filters.application`). * Read the `status` field of the matching entry in `items[]`. Note `messages:list` is part of the Statistics API and uses a different auth header than this endpoint: `Authorization: Api `. ## Related [Notify ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) [Cancel ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/cancel/) [Message statistics ](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#messageslist/) [Messaging API v2 overview ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/) [Migration from v1 ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/migration-from-v1/) --- # Presets API **URL:** https://docs.pushwoosh.com/developer/api-reference/presets-api/ Create, retrieve, list, update, delete, and clone Pushwoosh push notification presets through a REST API. --- A [push preset](https://docs.pushwoosh.com/product/content/push-presets/) is a reusable push notification template — the same object you build in the Control Panel’s push editor. This API manages push presets only; SMS, WhatsApp, Kakao, LINE, and Viber presets each have their own dedicated preset service, not covered here. Use a preset’s `code` to send it through [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) (payload `preset`) or a Customer Journey [Send push point](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/#messaging-points). ## Base URL ```plaintext https://rpc-api.svc-nue.pushwoosh.com ``` All endpoints are served over HTTPS. Requests and responses use `application/json` unless noted otherwise. ## Authentication Every request must include an `Authorization` header with your [Server API token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#server-api-token): ```plaintext Authorization: Api YOUR_API_TOKEN ``` ## Conventions * **Field naming:** request bodies and query/path parameters accept `lowerCamelCase` (for example, `sendType`, `localizedProperties`, `searchByName`) — the server unmarshals either casing. Responses are always marshaled using the proto field names, in `snake_case` (`localized_properties`, `platform_properties`, `per_page`, and so on). The response examples and the [Preset object](https://docs.pushwoosh.com/developer/api-reference/presets-api/#preset-object) reference below use that casing. * **`code`:** every preset response carries its own code, generated on `Create`. Pass this code to `Get`, `Update`, `UpdatePartial`, `Delete`, `Clone`, and to the messaging/journey APIs above. * **Platform keys:** the `platforms` and `open_actions` maps are keyed by the numeric [device type code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#device-type) (`1` for iOS, `3` for Android, and so on). `platform_properties` is keyed by the platform’s enum name instead (`IOS`, `ANDROID`, `BAIDU_ANDROID`, `HUAWEI_ANDROID`, `OSX` — the only five platforms it covers). * **Unpopulated fields:** `Get`, `Create`, and `Clone` responses include every field of the [Preset object](https://docs.pushwoosh.com/developer/api-reference/presets-api/#preset-object), even when empty or zero-valued. `List` returns a reduced field set — see [List](https://docs.pushwoosh.com/developer/api-reference/presets-api/#list) below. `Update` and `UpdatePartial` return no preset fields at all — see the [caution](https://docs.pushwoosh.com/developer/api-reference/presets-api/#update) in their sections. ### Error responses | HTTP status | Meaning | | :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------- | | `400 Bad Request` | Invalid argument — a required field is missing or malformed, or a precondition failed (for example, cloning without a `name`). | | `401 Unauthorized` | Missing or invalid `Authorization` header. | | `403 Forbidden` | The application or preset does not belong to the caller’s account. | | `404 Not Found` | The preset or application was not found. | | `500 Internal Server Error` | Unexpected server-side failure. | `Delete` on a preset still used by a running or paused journey’s Send push point also returns `400 Bad Request` (a `FailedPrecondition` on the wire) — not `409`. Remove the preset from the journey first. ## Endpoints | Method | Path | Description | | :------- | :---------------------------- | :------------------------------------ | | `POST` | `/api/presets` | Create a new push preset | | `GET` | `/api/presets` | List an application’s push presets | | `GET` | `/api/presets/{code}` | Get a single push preset | | `PUT` | `/api/presets/{code}` | Update a push preset (full overwrite) | | `PUT` | `/api/presets/{code}:partial` | Update a push preset (partial) | | `POST` | `/api/presets/{code}:clone` | Clone a push preset | | `DELETE` | `/api/presets/{code}` | Delete a push preset | ## Create Creates a new push preset in an application and returns it with its generated code. `POST` `/api/presets` ### Request body | Parameter | Type | Required | Description | | :------------ | :------ | :------- | :------------------------------------------------------------------------------------------------------------------- | | `application` | string | Yes | The [application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) to create the preset in. | | `name` | string | Yes | Preset name. | | `sendType` | string | No | Channel of the preset (for example `push`). | | `isV2` | boolean | No | Pins the preset’s origin flag. Omit to default to `true` (v2); set `false` only when reproducing a legacy v1 preset. | All other fields — localized content, platforms, deep link, inbox, categories, and so on — are shared with `Update` and documented once in the [Preset object](https://docs.pushwoosh.com/developer/api-reference/presets-api/#preset-object) reference below. ##### Request example ```json { "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"] } ``` ### Response Returns `{ "preset": { ... } }`, the created [Preset object](https://docs.pushwoosh.com/developer/api-reference/presets-api/#preset-object). ## List Lists an application’s push presets — a reduced field set, not the full object — with paging, ordering, and filtering by name or category. `GET` `/api/presets` ### Query parameters | Parameter | Type | Required | Description | | :----------------- | :--------------- | :------- | :---------------------------------------------------------------------------------------------------------------------- | | `application` | string | Yes | The application code to list presets for. | | `orderBy` | string | No | `NAME` (default), `CREATED`, or `UPDATED`. | | `orderDirection` | string | No | `ASC` (default) or `DESC`. | | `page` | integer | No | Zero-based page index. | | `perPage` | integer | No | Page size. Defaults to `100` when omitted or `0`. | | `searchByName` | string | No | Case-insensitive substring match on preset name **or** code (`ILIKE %value%`). | | `searchByCategory` | array of strings | No | Repeat the parameter to filter by any of several categories, e.g. `?searchByCategory=promo&searchByCategory=lifecycle`. | | `showHidden` | boolean | No | Include presets marked `hidden`. | Note `isDefault` is a deprecated filter kept only for the legacy send-push form in the Control Panel — don’t rely on it. ### Response Each item carries only: `name`, `code`, `platforms`, `localized_content` (plain per-locale text — **not** `localized_properties`), `localized_title`, `localized_subtitle`, `banner`, `icon`, `categories`, `journey_uuid`, `custom_data`, `is_v2`, `created`, `updated`. Every other field of the [Preset object](https://docs.pushwoosh.com/developer/api-reference/presets-api/#preset-object) — `localized_properties`, `platform_properties`, `deeplink`, `richmedia`, `url`, and so on — is omitted, even if set on the preset. | Field | Type | Description | | :--------- | :--------------- | :----------------------------------------------------------------- | | `presets` | array of objects | The current page of presets, in the reduced shape described above. | | `page` | integer | The returned page index. | | `per_page` | integer | The page size used for this response. | | `total` | integer | Total number of presets matching the filters, across all pages. | ##### Response example ```json { "presets": [ { "name": "20% discount", "code": "AAAAA-BBBBB", "platforms": { "1": true, "3": true }, "categories": ["promo"] } ], "page": 0, "per_page": 100, "total": 1 } ``` ## Get Returns a single push preset by its code, with every field of the [Preset object](https://docs.pushwoosh.com/developer/api-reference/presets-api/#preset-object) populated. `GET` `/api/presets/{code}` ### Path parameters | Parameter | Type | Description | | :-------- | :----- | :----------------- | | `code` | string | The preset’s code. | ### Response Returns `{ "preset": { ... } }`, the full [Preset object](https://docs.pushwoosh.com/developer/api-reference/presets-api/#preset-object). ## Update Overwrites an existing push preset by code with the supplied fields. `PUT` `/api/presets/{code}` ### Path parameters | Parameter | Type | Description | | :-------- | :----- | :------------------------------ | | `code` | string | The preset’s code to overwrite. | ### Request body Same fields as [Create](https://docs.pushwoosh.com/developer/api-reference/presets-api/#create) (minus `application`), plus the rest of the [Preset object](https://docs.pushwoosh.com/developer/api-reference/presets-api/#preset-object) fields. `sendType` is accepted but ignored — a preset’s channel can’t be changed after creation. Omitting a field doesn't always mean 'leave unchanged' `Update` rebuilds the preset’s content properties from scratch on every call: `localizedProperties`, `platformProperties`, `openAction`/`openActions`, `deeplink`, `deeplinkParams`, `richmedia`, `url`, `campaignCode`, `filterCode`, `geoZones`, `sendRate`, `cappingCount`/`cappingDays`, the three `notification*Url` fields, `remotePage`, `wnsContent`, `originalUrl`, the four `*Silent` flags, `inboxImage`/`inboxIcon`/`inboxDays`/`inboxDate`, `banner`, `icon`, `customData`, and `isV2` — omit any of these and it’s cleared (or, for `isV2`, reset to `true`). `name`, `platforms`, `categories`, `localizedTitle`, `localizedSubtitle`, and `localizedContent` are the exception: each is only touched when you send it, and left unchanged when omitted. Use [UpdatePartial](https://docs.pushwoosh.com/developer/api-reference/presets-api/#updatepartial) if you want the first group to be left-unchanged-when-omitted too. Response has no preset field `Update` returns `{}` — an empty object. The response message technically defines a `preset` field, but the server never populates it. Call `Get` afterward if you need the updated object back. ### Response An empty object on success: `{}`. ## UpdatePartial Updates only the supplied fields of an existing push preset by code, leaving unset fields unchanged. `PUT` `/api/presets/{code}:partial` ### Path parameters | Parameter | Type | Description | | :-------- | :----- | :-------------------------- | | `code` | string | The preset’s code to patch. | ### Request body Same fields as [Update](https://docs.pushwoosh.com/developer/api-reference/presets-api/#update), minus `application`. Unlike `Update`, every field here — including `localizedProperties`, `platformProperties`, `categories`, and the rest of the content-properties group listed in [Update’s caution](https://docs.pushwoosh.com/developer/api-reference/presets-api/#update) — is left unchanged when omitted, and only touched when you send it (a map/array field you send still fully replaces the existing value for that field, it just doesn’t affect anything you didn’t include). `sendType` is likewise accepted but ignored. Note `isV2` is the one exception even here: it’s rewritten on every `UpdatePartial` call, defaulting to `true` when omitted. Send `isV2: false` explicitly if the preset must stay a v1-style preset. ##### Request example ```json { "sendRate": 500, "cappingCount": 3, "cappingDays": 7 } ``` ### Response Also an empty object — see the [caution above](https://docs.pushwoosh.com/developer/api-reference/presets-api/#update). ## Clone Duplicates an existing push preset, under a new name, into the **same** application. `POST` `/api/presets/{code}:clone` Note Unlike the Email Templates API’s `Clone`, this endpoint has no `application` parameter — it always clones within the source preset’s own application. The clone is always created with `hidden: false`, regardless of the source. ### Request body | Parameter | Type | Required | Description | | :-------- | :----- | :------- | :-------------------------------------- | | `code` | string | Yes | Code of the source preset to duplicate. | | `name` | string | Yes | Name for the new preset. | ##### Request example ```json { "code": "AAAAA-BBBBB", "name": "20% discount (copy)" } ``` ### Response Returns `{ "preset": { ... } }`, the new [Preset object](https://docs.pushwoosh.com/developer/api-reference/presets-api/#preset-object). ## Delete Permanently deletes a push preset by code. `DELETE` `/api/presets/{code}` Caution Fails if the preset is still used by a `send_push` point in a running or paused journey — remove it from the journey first. This cannot be undone. ### Path parameters | Parameter | Type | Description | | :-------- | :----- | :--------------------------- | | `code` | string | The preset’s code to delete. | ### Response An empty object on success: `{}`. ## Object reference Field names below match what `Get`, `Create`, `Update`, and `Clone` actually return — `snake_case` proto field names (see [Conventions](https://docs.pushwoosh.com/developer/api-reference/presets-api/#conventions)). The `lowerCamelCase` form used in the request examples above works the same way on input. ### Preset object #### Identity | Field | Type | Description | | :---------- | :---------------- | :---------------------------------------------------------------------------- | | `code` | string | Generated on `Create`. Identifies this preset everywhere else in the API. | | `name` | string | Preset name. | | `send_type` | string | Channel of the preset (for example `push`). | | `is_v2` | boolean | `true` for presets created or migrated to the v2 content model. | | `system` | boolean | Marks the preset as a system/internal preset. | | `hidden` | boolean | Hides the preset from `List` results (send `showHidden: true` to include it). | | `created` | string (RFC 3339) | Creation timestamp. | | `updated` | string (RFC 3339) | Last update timestamp. | #### Targeting & content | Field | Type | Description | | :------------------------------------------------------------- | :-------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `platforms` | map | Which platforms the preset targets, keyed by [device type code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#device-type) (e.g. `"1"` for iOS). | | `localized_properties` | map | Locale → rich per-platform content. Same shape as [`LocalizedContent`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#localizedcontent) on the `Notify` payload — one entry per platform block (`ios`, `android`, and so on). This is the primary way to set platform-specific push content. | | `localized_title` / `localized_subtitle` / `localized_content` | map | Locale → plain text. A simpler alternative to `localized_properties` for title, subtitle, and body when you don’t need per-platform overrides. | | `platform_properties` | map | Legacy per-platform overrides, keyed by platform enum name (`IOS`, `ANDROID`, `BAIDU_ANDROID`, `HUAWEI_ANDROID`, `OSX`). See [PlatformProperties object](https://docs.pushwoosh.com/developer/api-reference/presets-api/#platformproperties-object) below. | | `open_action` | [`OpenAction`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#openaction) | Action triggered when the user opens the notification, applied to every platform. Mutually exclusive with `open_actions` — the response sets exactly one. | | `open_actions` | map | Per-platform override of `open_action`, keyed by [device type code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#device-type). | | `deeplink` | string | [Deep Link](https://docs.pushwoosh.com/developer/guides/messaging-channels/deep-linking/) code. | | `deeplink_params` | map | Parameters passed to the deep link. | | `richmedia` | string | [Rich Media](https://docs.pushwoosh.com/product/content/rich-media/) code opened by the notification. | | `url` | string | URL opened by the notification, if not using a deep link or Rich Media. | #### Inbox | Field | Type | Description | | :------------ | :---------------- | :--------------------------------------------------------------------------------------------------- | | `inbox_image` | string | Image URL shown in the [Message Inbox](https://docs.pushwoosh.com/developer/guides/message-inbox/mobile-message-inbox/) entry. | | `inbox_icon` | string | Icon URL shown in the Message Inbox entry. | | `inbox_days` | integer | Days the entry stays in the Message Inbox. | | `inbox_date` | string (RFC 3339) | Explicit expiration date for the Message Inbox entry, as an alternative to `inbox_days`. | #### Organization & metadata | Field | Type | Description | | :-------------- | :--------------- | :---------------------------------------------------------------------------------------------------------------------- | | `categories` | array of strings | Category names the preset is tagged with. | | `campaign_code` | string | [Campaign code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#campaign-code) this preset is attributed to. | | `filter_code` | string | [Segment / Filter code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#segment--filter-code) this preset targets by default. | | `geo_zones` | string | [Geozone](https://docs.pushwoosh.com/developer/api-reference/geozones/) targeting, if the preset is geo-triggered. | | `journey_uuid` | string | UUID of the Customer Journey that owns this preset, if it was created from a journey’s Send push point. | | `custom_data` | object | Free-form JSON forwarded to the client SDK as the `u` parameter. | | `banner` | string | Big-picture / attachment image URL. | | `icon` | string | Custom notification icon URL. | #### Delivery limits | Field | Type | Description | | :------------------------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `send_rate` | integer | Throttling for sends using this preset, in messages/second — the preset-level equivalent of `Notify`’s [`SendRate`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/#sendrate). | | `capping_count` / `capping_days` | integer | Per-user frequency limit for this preset — the preset-level equivalent of `Notify`’s [`FrequencyCapping`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/#frequencycapping) `count` / `days`. | #### Webhooks | Field | Type | Description | | :--------------------------- | :----- | :------------------------------------------------------------------------- | | `notification_sent_url` | string | Callback URL requested when a notification using this preset is sent. | | `notification_delivered_url` | string | Callback URL requested when a notification using this preset is delivered. | | `notification_click_url` | string | Callback URL requested when a notification using this preset is clicked. | #### Legacy fields These carry over from the v1 preset model. They’re populated for Control Panel compatibility rather than for new integrations. | Field | Type | Description | | :--------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------- | | `remote_page` | string | Legacy remote page reference. | | `wns_content` | string | Legacy Windows toast template JSON, as accepted by the v1 `createPreset`/`getPreset` methods. | | `original_url` | string | The pre-shortening value of `url`, when `url` was replaced by a shortened link. | | `ios_silent` / `android_silent` / `baidu_android_silent` / `huawei_android_silent` | boolean | Per-platform silent (data-only) push flags. | ### PlatformProperties object Fields available in each `platform_properties` entry (`IOS`, `ANDROID`, `BAIDU_ANDROID`, `HUAWEI_ANDROID`, `OSX`): | Field | Type | Description | | :----------------------- | :------ | :---------------------------------------------------------------- | | `badge` | string | Badge count override. | | `sound` | string | Sound file name. | | `sound_off` | boolean | Mute the notification sound. | | `priority` | string | In-tray priority (Android/Baidu/Huawei only). | | `delivery_priority` | string | `NORMAL` or `HIGH` delivery priority (Android/Baidu/Huawei only). | | `ios_interruption_level` | string | `passive`, `active`, `time-sensitive`, or `critical` (iOS only). | ## Related [Notify ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) [Payload reference ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/) [Customer Journey point reference ](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/point-reference/#messaging-points/) --- # Scheduled requests **URL:** https://docs.pushwoosh.com/developer/api-reference/scheduled-requests/ Use /getResults to obtain responses for scheduled requests and retrieve statistics data from asynchronous API operations. --- To obtain a response for **every scheduled request**, `/getResults` has to be sent after the main request. Most of statistics&analytics API methods need the `/getResults` to be sent in order to get the stats files or JSON: * [getAppStats](https://docs.pushwoosh.com/developer/api-reference/statistics-api/application-subscriber-statistics/#getappstats) * [getCampaignStats](https://docs.pushwoosh.com/developer/api-reference/statistics-api/campaign-statistics/) * [getEventStatistics](https://docs.pushwoosh.com/developer/api-reference/statistics-api/events-and-tags-statistics/#geteventstatistics) * [getTagStats](https://docs.pushwoosh.com/developer/api-reference/statistics-api/events-and-tags-statistics/#gettagstats) * [getBouncedEmails](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#bouncedemails) ## getResults `POST` `https://api.pushwoosh.com/json/1.3/getResults` Retrieves the result of a scheduled request. #### Request Body | Name | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | request_id* | string | Request ID returned by a scheduled method. | Note This `request_id` is a job token for polling this result, unrelated to the message [Request ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#request-id) used for HTTP-level tracing. Example ```json { "request":{ "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel. "request_id": "REQUEST_ID" // required. Request ID returned by the scheduled method. } } ``` * 200: Response Example Response depends on the request you’re obtaining results for, so it may look different. Below is an example response for the `/getMsgStats` request: Example Response ```json { "status_code": 200, "status_message": "OK", "response": { "formatter": "hourly", "rows": [{ "datetime": "2020-05-13 08:00:00", "action": "send", "count": 6 }, { "datetime": "2020-05-13 08:00:00", "action": "inboxopen", "count": 0 }, { "datetime": "2020-05-13 08:00:00", "action": "delivery", "count": 1 }, { "datetime": "2020-05-13 08:00:00", "action": "open", "count": 0 }], "conversion": { "send": 6, "delivery": 1, "open": 0, "events": [] } } } ``` --- # Segmentation (Filters) API **URL:** https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api/ Create, retrieve, list, and delete filters, and export segments using Segmentation (Filters) API methods. --- ## createFilter `POST` `https://api.pushwoosh.com/json/1.3/createFilter` Creates a new filter. **Request body** | Name | Required | Type | Description | | -------------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | auth* | Yes | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | name* | Yes | string | [Filter name](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#segment--filter-name). | | filter_expression* | Yes | string | Expression constructed according to the rules of the [Segmentation language](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api/segmentation-language/). **Example:** `T(“City”, eq, “Madrid”)` to segment users whose city is Madrid. | | application | No | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). This parameter is usable only with High-Speed Setup; omit otherwise. | | expiration_date | No | string | Filter expiry. The filter will be automatically deleted on a date specified, unless it’s used in a Preset or an RSS Feed. | **200** ```json { "status_code": 200, "status_message": "OK", "response": { "name": "filter name" } } ``` **Example** ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", "name": "City = Madrid", "filter_expression": "T(\"City\", eq, \"Madrid\")", "application": "B18XX-XXXXX", "expiration_date": "2025-01-01" } } // creating Filters for Timezones { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel "name": "Timezone Filter", "filter_expression": "T(\"Timezone\", BETWEEN, [\"UTC-12:00\", \"UTC+14:00\"])" } } ``` ## listFilters `POST` `https://api.pushwoosh.com/json/1.3/listFilters` Returns a list of available segments (filters) with their conditions. **Request Body** | Name | Required | Type | Description | | ------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------ | | auth* | Yes | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | Yes | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | **200** ```json { "status_code": 200, "status_message": "OK", "response": { "filters": [{ "code": "52551-F2F42", "name": "City = Madrid", "filter_expression": "T(\"City\", eq, \"madrid\")", "expiration_date": "2025-01-01", "application": "B18XX-XXXXX" }] } } ``` **Example** ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", "application": "B18XX-XXXXX" } } ``` ## deleteFilter `POST` `https://api.pushwoosh.com/json/1.3/deleteFilter` Deletes an existing filter. **Request Body** | Name | Type | Description | | ------ | ------ | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | name* | string | [Filter name](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#segment--filter-name). | * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` Example ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel "name": "filter name" } } ``` ## exportSegment `POST` `https://api.pushwoosh.com/api/v2/audience/exportSegment` A scheduled request. Exports the list of subscribers that fall under specified Filter conditions. **Request body** | Name | Required | Type | Description | | -------------------- | ------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | auth* | Yes | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | filterExpression* | Yes | string | Filter conditions | | exportData | No | array | Data to export. Possible values: `"hwids"`, `"push_tokens"`, `"users"`, `"tags"`, `"location"`. Including `"location"` adds `Latitude` and `Longitude` columns to the exported CSV. If `exportData` is omitted, `Latitude` and `Longitude` are included in the export by default. | | filterCode | No | string | Pre-made [filter code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#segment--filter-code), can be used instead of `filterExpression`. Can be obtained from `/listFilters` API or address bar of your browser when viewing the filter in Control Panel. | | applicationCode | Required if you’re using either `filterExpression` or `filterCode`. | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | generateExport | No | boolean | By default set to `true`, and a response contains a link to download the file. If false, only devices count will be sent in response. | | format | No | string | Sets the format of the exported file: “csv” or “json_each_line”. If omitted, the CSV file is generated. | | tagsList | No | array | Specifies [tags](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#tag) to export. To obtain the specific tags only, the “exportData” array should contain the “tags” value. | | includeWithoutTokens | No | boolean | Set to `true` to include users without push tokens in the exported file. Default is `false`. | * 200 Successful ```json { "task_id": "177458" } ``` Example ```json { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "filterExpression": "AT(\"12345-67890\", \"Name\", any)", // filter conditions, refer to the Segmentation Language guide for syntax "filterCode": "12345-67890", // pre-made filter code, can be used instead of filterExpression "applicationCode": "00000-AAAAA", // Required if you're using either `filterExpression` or `filterCode`. Pushwoosh app code. Can be obtained from /listFilters API request or address bar of your browser while viewing the filter in Control Panel. "generateExport": true, // if false, devices count only will be sent in response; by default, a response contains a link to download the CSV file "format": "json_each_line", // format of the file to present the data in: "csv" – the .csv file is downloaded; "json" – a JSON file with all expored devices; or "json_each_line" – JSON line for each device. If not specified, CSV is the default format. "exportData": ["hwids", "tags"], // optional. Data to export. Possible values: "hwids", "push_tokens", "users", "tags", "location", "fcm_keys", "web keys" "tagsList": ["Name", "Level"], // optional. Specifies tags to export. To obtain the specific tags only, the "tags" value should be sent within the "exportData" array or the "exportData" be empty. "includeWithoutTokens": true // optional. Set to true to include users without push tokens in the exported file. Default is false. } ``` Note Please find Segmentation Language reference for writing filter expressions [here](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api/segmentation-language/). For example, to export all subscribers of a particular app, use the following Filter conditions: ```json { "auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel "filterExpression": "A(\"AAAAA-BBBBB\")", // Filter expression referencing app segment "applicationCode": "AAAAA-BBBBB" // Required Pushwoosh app code } ``` Caution In the response, you’ll get the **`task_id`** to get the resulting file. Then, call [/exportSegment/result](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api/#exportsegment-results) with that `task_id` in the request body to retrieve the resulting file. ## exportSegment results `POST` `https://api.pushwoosh.com/api/v2/audience/exportSegment/result` **Retrieves the link to the CSV with the /exportSegment results.** **Request Body** | Name | Type | Description | | ---------- | ------ | ------------------------------------------------------------------------------------------------------------ | | auth* | String | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | task_id* | String | Identifier received in your `/exportSegment` response. | * 200: OK ```json { "devicesCount": "24735", "filename": "https://static.pushwoosh.com/segment-export/export_segment_XXXXX_XXXXX_xxxxxxxxxxxxxxxxx.csv.zip", "status": "completed" } ``` Pass the “**task_id**” received in your `/exportSegment` response in the `/exportSegment/result` request body. In the `/exportSegment/result` response, you’ll receive the “filename” parameter. Follow the link provided in that parameter value to automatically download a ZIP archive. Unpack the archive to retrieve the CSV or JSON file (depending on the “format” specified in your request) containing the devices’ data. Starting April 3, 2025 authorization is required to download the file: * If downloading via a **browser**, simply log in to the **Pushwoosh Control Panel** to gain access. * If downloading via **server software**, include the following header in your request: `Authorization: Token YOUR_API_TOKEN` If you specify the “exportData” in your `/exportSegment` request, the file downloaded will contain the data requested only. By default, the file contains the following user data: | **Field** | Description | Example of value | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | Hwid | [Hardware ID of a device](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) | 01D1BA5C-AAAA-0000-BBBB-9B81CD5823C8 | | User ID | [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) associating a device with a particular user. If no User ID assigned, the HWID is used. | user8192 | | Push Token | Unique identifier assigned to a device by cloud messaging gateways. [Learn more](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#push-token) | eeeb2fd7…0fc3547 | | Type | Platform type (integer). | 1 | | Type (humanized) | Platform type (string). | iOS | | Age | Value of the default Age tag. | 29 | | ApplicationVersion | Value of the default Application Version tag. | 1.12.0.0 | | City | Value of the default City tag. | us, boston | | TagName | Value of a tag created in your account. | TagValue | --- # Segmentation language **URL:** https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api/segmentation-language/ Create precise, behavior-based user segments with Pushwoosh Segmentation Language for personalized, targeted messaging. --- Pushwoosh offers a powerful segmentation engine for building granular Segments based on Tag values. **Segmentation Language** is a specific way of writing and combining segmentation criteria to describe a particular group of users that match those criteria and treat them as a single audience segment. This article describes the basic concepts and syntax of the Segmentation Language and provides comprehensive examples of building segmentation criteria for various cases. ## Basics Each device in your user base has specific attributes associated with it via **Tag values**. For example, let’s say a user named Jane lives in Tokyo, and her age is 28. That user will have the following Tags set for their device: * Name: Jane * City: Tokyo * Age: 28 To target Jane, you will need to describe a segment as follows: `T("Name", eq, "Jane") * T("Age", eq, 28) * T("City", eq, "Tokyo")` This combination of conditions is a **filter expression** used in Segmentation Language for describing groups of users aka audience Segments. ## Filter expressions Filter expression is a string that contains a condition or a combination of conditions describing the segment you need. ### Conditions Each condition describes a segment of devices that match the criteria specified in that condition. For example, the following condition builds a segment of users who live in Tokyo: `T("City", e, "Tokyo")` where * T is a Tag (condition type); * eq is an operator to apply; * “Tokyo” is a Tag value users have associated with their devices. #### Condition types The following condition types are available for segmentation: * **A** (Application) – describes a segment of devices with a particular app installed. Aliases: **App**, **Application**; * **T** (Tag) – describes a segment of devices with the specified Tag values; * **AT** (App-scoped tag) – looks up a tag value within a specific application; app code is required as the first argument. Alias: **Tag**; * **Event** – describes a segment of devices triggered a specific Pushwoosh event; * **Geo** – describes a segment of devices within a specific geographic radius; * **BTTS** – describes a segment of devices based on their best time to send; * **Updated** – describes a segment of devices based on their last update timestamp; * **Segment** – references another filter/segment by its code; ### Operations with conditions For building sophisticated segments, the following operations can be applied to conditions within the filter expression: #### Union (+) Joins the segments, i.e., builds a new segment of users who match at least one of the specified conditions. For example, to target users who live in Tokyo or in Osaka, you’ll need to describe the segment with the following conditions: `T("City", eq, "Tokyo") + T("City", eq, "Osaka")` Note Equivalent to logical **disjunction** (**OR**). Can also be written as **or** operator. #### Intersection (*) Constructs a segment of users belonging to both segments described by the conditions. Thus, only those users who comply with each condition you specify will be included. The following expression describes a segment of users who both live in Tokyo and have specified their names: `T("City", eq, "Tokyo") * T("Name", any)` Note Analog to logical **conjunction** (**AND**). Can also be written as **and** operator. #### Difference (\) Builds a segment of users who belong to one of the described segments and do not belong to another. Users who live in Tokyo but have not given you their names will be described as follows: `T("City", eq, "Tokyo") \ T("Name", any)` Note Equivalent to logical **negation** (**NOT**). Can also be written as **not** operator. #### Parentheses Determine the order of operations to perform with the conditions in your filter expression. For example, the following filter expression will, at first, obtain a segment of the 12345-67890 subscribers whose age is 18 and then subtract all men of that segment: `( A("12345-67890") * T("Age", eq, 18) ) \ T("Gender", eq, "Male")` ## Tag conditions operators For each Tag type, their own operators are applied. ### Integer Tags Operators * **eq** - equal to a specified value * **noteq** - not equal to a specified value * **lte** - less than or equal to a specified value * **gte** - greater than or equal to a specified value * **in** - any of specified values * **notin** - not equal to any of specified values * **between** - in a specified range * **any** - devices with any values set for the tag * **notset** - devices with no value set for the tag Integer Tags syntax example `T("int", eq, 42)` ### String Tags Operators * **eq** - equal to a specified value * **noteq** - not equal to a specified value * **startswith** - starts with a specified prefix * **endswith** - ends with a specified suffix * **contains** - contains a specified substring * **in** - equal to any of specified values * **notin** - not equal to any of specified values * **any** - devices with any values set for the tag * **notset** - devices with no value set for the tag String Tags syntax examples * `T("str", eq, "kangaroo")` - exact match * `T("str", startswith, "kang")` - starts with “kang” * `T("str", endswith, "roo")` - ends with “roo” * `T("str", contains, "nga")` - contains “nga” anywhere in the string ### List Tags Operators * **in** - devices with any of the specified tag values * **notin** - none of the specified tag values associated with the device * **any** - devices with any values set for the tag * **notset** - devices with no value set for the tag List Tags syntax example `T("list", notin, ["kangaroo", "raccoon"])` ### Date Tags Operators * **eq** - equal to the date specified * **noteq** - not equal to the date specified * **lte** - before or on the date specified * **gte** - after or on the date specified * **in** - equal to any of specified dates * **notin** - not equal to any of specified dates * **between** - in a specified range * **any** - devices with any values set for the tag * **notset** - devices with no value set for the tag * **match** - matches a specified month of the year and day of the month. match operator examples * `AT("XXXXX-XXXXX", "Date tag", match month 4 day 1)` - devices that have the “Date tag” set to the 1st of April of any year. * `AT("XXXXX-XXXXX", "Date tag", match month "now" day 13)` - devices that have the “Date tag” set to the 13th day of the current month. * `AT("XXXXX-XXXXX", "Date tag", match month "now" day "now+2")` - devices that have the “Date tag” set to the day after tomorrow. Common use case: birthday greetings. Match operator examples for anniversary and birthday segments You can [segment users based on recurring calendar dates](https://docs.pushwoosh.com/product/audience-data-and-segmentation/segmentation/create-segments/anniversary-segments), such as birthdays or anniversaries. In these cases, only the month and day are taken into account, while the year is ignored. * `AT("XXXXX-XXXXX", "birthday", match month "now" day "now")` **Targets users whose birthday is today** (same day and month as today). *Use this to send birthday greetings or special offers on the user’s actual birthday.* * `AT("XXXXX-XXXXX", "birthday", match month "now" day "now+N")` **Targets users whose birthday is in N days** (same month and day, N days from today). *Use this to prepare users in advance, for example, send countdown messages or upcoming event reminders.* * `AT("XXXXX-XXXXX", "birthday", match month "now" day "now-N")` **Targets users whose birthday was N days ago**. *Use this for belated birthday messages or follow-ups like feedback requests.* * `AT("XXXXX-XXXXX", "birthday", match month "now" day N)` **Targets users whose birthday is on the Nth day of the current month**, regardless of the year. *Use this when planning fixed monthly campaigns tied to specific dates (e.g., monthly loyalty rewards on the 10th).* - **daysago eq** - equal to a specified number of days before the present day - **daysago noteq** - not equal to a specified number of days before the present day - **daysago lte** - less than or equal to a specified number of days before the present day - **daysago gte** - greater than or equal to specified number of days before the present day - **daysago between** - between the specified numbers of days daysago operator examples * `T("Date tag", daysago, eq, 0)` - the present day from 00:00 to the current moment * `T("Date tag", daysago, eq, 1)` - from 00:00 of the previous day to 00:00 of the present day * `T("Date tag", daysago, gte, 1)` - all the time to 00:00 of the present day * `T("Date tag", daysago, lte, 7)` - from 00:00 of the day 6 days ago to the current moment * `T("Date tag", daysago, between, [2,7])` - from 7 to 2 days ago. - **minutesago lte** - less than or equal to a specified number of minutes before the present moment - **minutesago gte** - greater than or equal to a specified number of minutes before the present moment minutesago operator examples * `T("Date tag", minutesago, lte, 30)` - the last 30 minutes; * `T("Date tag", minutesago, gte, 60)` - 60 or more minutes ago; * `T("Date tag", minutesago, lte, 1)` - within the last minute. - **daysahead** - in N to M days from the present day (UTC), inclusive on both ends daysahead operator examples `daysahead` takes a `[from, to]` interval (days from today’s UTC midnight, both ends inclusive). Unlike `daysago`, it has no sub-operator — only the interval form. * `T("Date tag", daysahead, [0, 0])` - the present day from 00:00 to 23:59:59 * `T("Date tag", daysahead, [1, 1])` - the next day from 00:00 to 23:59:59 * `T("Date tag", daysahead, [2, 5])` - any moment from the start of 2 days from now to the end of 5 days from now date operator example * `T("Date tag", eq "2022-12-05 00:00:00")` ### Boolean Tags Operators * **eq** - equal to a specified value * **noteq** - not equal to a specified value * **any** - devices with any values set for the tag * **notset** - devices with no value set for the tag Boolean Tags syntax example `T("bool", eq, true)` ### Price Tags Operators * **eq** - equal to a specified value * **noteq** - not equal to a specified value * **lte** - less than or equal to a specified value * **gte** - greater than or equal to a specified value * **in** - equal to any of specified values * **notin** - not equal to any of specified values * **between** - in a specified range * **any** - devices with any values set for the tag * **notset** - devices with no value set for the tag Price Tags syntax example `T("price", between, ["4.2", "6.9"])` ### Version Tags Operators * **eq** - equal to a specified value * **noteq** - not equal to a specified value * **lte** - less than or equal to a specified value * **gte** - greater than or equal to a specified value * **in** - equal to any of specified values * **notin** - not equal to any of specified values * **between** - in a specified range * **any** - devices with any values set for the tag * **notset** - devices with no value set for the tag Version Tags syntax example `T("version", lte, "4.2")` ## Event conditions operators Note Please keep in mind the event conditions are app-specific so the app code should be specified in your filter expressions along with the event name. ### Event count * **count gte** - devices triggered the event more than or exactly n times * **count lte** - devices triggered the event less than or exactly n times * **count eq** - devices triggered the event exactly n times * **count noteq** - devices triggered the event any times but not equal to n Event count syntax example `Event("11111-11111", "Level reached", count gte 10) // 11111-11111 is an app code` ### Event date * **date gte** - devices triggered the event later than or exactly on the specified date * **date lte** - devices triggered the event earlier than or exactly on the specified date * **date eq** - devices triggered the event exactly on the specified date * **date noteq** - devices triggered the event whenever but not on the specified date * **date in** - devices triggered the event on any of the specified dates * **date notin** - devices triggered the event whenever but not on any of the specified dates * **date between** - devices triggered the event within a specified period * **date daysago eq** - event trigger date is equal to a specified number of days before the present day * **date daysago noteq** - event trigger date is not equal to a specified number of days before the present day * **date daysago lte** - event trigger date is less than or equal to a specified number of days before the present day * **date daysago gte** - event trigger date is greater than or equal to specified number of days before the present day * **date daysago between** - event trigger date is between the specified numbers of days * **date daysahead** - event trigger date is in a specified number of days from the present day (interval is inclusive on both ends, see Date Tags Operators above for full semantics) * **date minutesago lte** - event trigger date is less than or equal to specified number of minutes before the present moment * **date minutesago gte** - event trigger date is greater than or equal to specified number of minutes before the present moment Event date syntax examples * `Event("11111-11111", "Level reached", date gte "2022-01-01 01:02:03")` * `Event("11111-11111", "Level reached", date in ["2022-01-01 01:02:03", "2022-01-01 02:03:04"])` * `Event("11111-11111", "Level reached", date between "2022-01-01 01:02:03" "2022-01-01 02:03:04")` * `Event("11111-11111", "Level reached", date daysahead 0 7)` - events with a trigger date within the next 7 days * `Event("11111-11111", "Level reached", date minutesago lte 30)` - events within last 30 minutes * `Event("11111-11111", "Level reached", date minutesago gte 60)` - events 60+ minutes ago ### Event platforms Filter events by the platform where they were triggered. * **platforms** - list of platforms (e.g., [“ios”, “android”]) Event platforms syntax example `Event("11111-11111", "Level reached", platforms ["android", "ios"], count gte 5)` ### Event attributes Event conditions can filter based on event attribute values. Attributes support various data types with their corresponding operators. #### Integer Event Attributes * **attribute “name” eq** - attribute equals a specified value * **attribute “name” noteq** - attribute not equal to a specified value * **attribute “name” gte** - attribute greater than or equal to a specified value * **attribute “name” lte** - attribute less than or equal to a specified value * **attribute “name” between** - attribute in a specified range * **attribute “name” in** - attribute equals any of specified values * **attribute “name” notin** - attribute not equal to any of specified values * **attribute “name” any** - any value set for the attribute * **attribute “name” notset** - no value set for the attribute Integer attribute syntax examples * `Event("11111-11111", "Purchase", attribute "amount" eq 42)` * `Event("11111-11111", "Purchase", attribute "amount" between 10 100)` * `Event("11111-11111", "Purchase", attribute "amount" in [10, 20, 30])` #### String Event Attributes * **attribute “name” eq** - attribute equals a specified value * **attribute “name” noteq** - attribute not equal to a specified value * **attribute “name” startswith** - attribute starts with a specified prefix * **attribute “name” endswith** - attribute ends with a specified suffix * **attribute “name” contains** - attribute contains a specified substring * **attribute “name” in** - attribute equals any of specified values * **attribute “name” notin** - attribute not equal to any of specified values * **attribute “name” any** - any value set for the attribute * **attribute “name” notset** - no value set for the attribute String attribute syntax examples * `Event("11111-11111", "Page View", attribute "url" startswith "https://example.com")` * `Event("11111-11111", "Page View", attribute "url" endswith ".html")` * `Event("11111-11111", "Page View", attribute "url" contains "/products/")` * `Event("11111-11111", "Button Click", attribute "button_name" in ["submit", "cancel"])` #### Boolean Event Attributes * **attribute “name” eq** - attribute equals true or false * **attribute “name” noteq** - attribute not equal to true or false Boolean attribute syntax example `Event("11111-11111", "Feature Toggle", attribute "enabled" eq true)` #### Date Event Attributes * **attribute “name” eq** - attribute equals a specified date * **attribute “name” noteq** - attribute not equal to a specified date * **attribute “name” gte** - attribute after or on a specified date * **attribute “name” lte** - attribute before or on a specified date * **attribute “name” between** - attribute within a specified date range * **attribute “name” in** - attribute equals any of specified dates * **attribute “name” notin** - attribute not equal to any of specified dates * **attribute “name” daysago eq/noteq/gte/lte/between** - attribute relative to days ago * **attribute “name” daysahead from to** - attribute in a specified interval of days from the present day (interval is inclusive on both ends, see Date Tags Operators above for full semantics) * **attribute “name” minutesago gte/lte** - attribute relative to minutes ago * **attribute “name” any** - any value set for the attribute * **attribute “name” notset** - no value set for the attribute Date attribute syntax examples * `Event("11111-11111", "Subscription", attribute "start_date" eq "2022-01-01 01:02:03")` * `Event("11111-11111", "Subscription", attribute "start_date" between "2022-01-01 00:00:00" "2022-12-31 23:59:59")` * `Event("11111-11111", "Subscription", attribute "start_date" daysago lte 30)` - within last 30 days * `Event("11111-11111", "Subscription", attribute "renewal_at" daysahead 0 30)` - renewals in the next 30 days * `Event("11111-11111", "Subscription", attribute "start_date" minutesago gte 60)` - 60+ minutes ago #### Price Event Attributes * **attribute “name” eq** - attribute equals a specified price value * **attribute “name” noteq** - attribute not equal to a specified price value * **attribute “name” gte** - attribute greater than or equal to a specified price * **attribute “name” lte** - attribute less than or equal to a specified price * **attribute “name” between** - attribute in a specified price range * **attribute “name” in** - attribute equals any of specified prices * **attribute “name” notin** - attribute not equal to any of specified prices * **attribute “name” any** - any value set for the attribute * **attribute “name” notset** - no value set for the attribute Price attribute syntax example `Event("11111-11111", "Purchase", attribute "total_price" between 10.00 50.00)` #### List Event Attributes * **attribute “name” in** - attribute contains any of specified values * **attribute “name” notin** - attribute doesn’t contain any of specified values * **attribute “name” any** - any value set for the attribute * **attribute “name” notset** - no value set for the attribute List attribute syntax example `Event("11111-11111", "Cart Update", attribute "product_ids" in ["prod-123", "prod-456"])` ## Additional condition types ### Geo condition Target devices based on geographic location within a specified radius. **Syntax:** `Geo("", , , )` Geo syntax example `Geo("11111-11111", 53.2734, -7.77832031, 100.05)` - devices within 100.05 km of coordinates ### BTTS condition Target devices by their best time to send notifications (hour of day, 0-23). **Operators:** * **any** - any best time to send value set * **eq** - exact hour match * **noteq** - not equal to hour * **gte** - hour greater than or equal to * **lte** - hour less than or equal to BTTS syntax examples * `BTTS("11111-11111", eq 10)` - devices with best time at 10:00 * `BTTS("11111-11111", gte 18)` - devices with best time from 18:00 onwards * `BTTS("11111-11111", any)` - devices with any best time value ### Updated condition Filter devices by their last update timestamp. **Operators:** * **gte** - updated after or on specified date * **lte** - updated before or on specified date * **between** - updated within date range Updated syntax examples * `Updated("11111-11111", gte "2022-01-01 00:00:00")` - devices updated after Jan 1, 2022 * `Updated("11111-11111", lte "2022-12-31 23:59:59")` - devices updated before Dec 31, 2022 * `Updated("11111-11111", between "2022-01-01 00:00:00" "2022-12-31 23:59:59")` - devices updated in 2022 ### Segment condition Reference another filter/segment by its code. Segment syntax example `Segment("11111-11111", "22222-22222")` - reference filter with code “22222-22222” ## Application condition device presence flags Application conditions support additional flags to control device and token filtering: * **with_tokens** - devices with push notification tokens * **without_tokens** - devices without push notification tokens * **with_devices** - users with registered devices * **without_devices** - users/profiles without registered devices Application flags syntax examples * `A("11111-11111", ["ios", "android"], [with_tokens])` - devices with push tokens * `A("11111-11111", ["ios", "android"], [without_tokens])` - devices without push tokens * `A("11111-11111", [], [with_devices])` - all devices with device records * `A("11111-11111", ["ios", "android"], [without_tokens, with_devices])` - devices without tokens but with device records ## Filter expression examples Note When writing JSON queries, be sure to escape quotes (`"`) and backslashes (`\`) with a backslash (`\`). For an example request, see [/exportSegment](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api/#exportsegment). ### Basic examples 1. iOS and Android devices with the app installed and with push tokens: ```json A("11111-11111", ["ios","android"], [with_tokens]) ``` 2. iOS and Android devices with the app installed but without push tokens: ```json A("11111-11111", ["ios","android"], [without_tokens]) ``` 3. iOS and Android devices with the app installed, whether they have push tokens or not: ```json A("11111-11111", ["ios","android"], [with_tokens, without_tokens]) ``` 4. All app subscribers who have purchased something in the app: ```json AT("11111-11111", "In-App Purchase", gte, 1) ``` ### Advanced examples 5. Users in Tokyo who have opened the app in the last 7 days: ```json T("City", eq, "Tokyo") * Event("11111-11111", "App Open", date daysago lte 7) ``` 6. Users who made a purchase over $50 in the last 30 days: ```json Event("11111-11111", "Purchase", attribute "total_price" gte 50.00, date daysago lte 30) ``` 7. Users whose names start with “J” or end with “e”: ```json T("Name", startswith, "J") + T("Name", endswith, "e") ``` 8. Active iOS users within 100km of New York who haven’t purchased recently: ```json A("11111-11111", ["ios"], [with_tokens]) * Geo("11111-11111", 40.7128, -74.0060, 100) \ Event("11111-11111", "Purchase", date daysago lte 30) ``` 9. Users with best time to send between 9 AM and 5 PM: ```json BTTS("11111-11111", gte 9) * BTTS("11111-11111", lte 17) ``` 10. Users who triggered a specific event on Android or iOS in the last hour: ```json Event("11111-11111", "Button Click", platforms ["android", "ios"], date minutesago lte 60) ``` 11. Devices updated in the last 3 months with app version 4.2 or higher: ```json Updated("11111-11111", gte "2024-07-01 00:00:00") * AT("11111-11111", "App Version", gte, "4.2") ``` --- # SMS API **URL:** https://docs.pushwoosh.com/developer/api-reference/sms/ Send SMS notifications to users using API methods for customer communication and engagement. --- /createSMSMessage is deprecated New integrations should use [Messaging API v2](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/) — pass `platforms: ["SMS"]` to `Notify`. See the [migration guide](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/migration-from-v1/#from-createsmsmessage). Note Before sending SMS messages, connect your SMS provider in the Control Panel. [Learn more](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/sms-configuration/) Caution `/createSMSMessage` doesn’t support MMS. If `preset` points at an [SMS preset](https://docs.pushwoosh.com/product/content/sms-presets/) with [MMS attachments](https://docs.pushwoosh.com/product/content/sms-presets/#add-mms-attachments), this method ignores the subject and images and sends only the plain-text body. To send MMS, use [Messaging API v2 `Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#mms) instead. ## createSMSMessage Deprecated Used to send SMS notifications to users POST `https://api.pushwoosh.com/json/1.3/createSMSMessage` ### Request body | Name | Required | Type | Description | | ------------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------ | | **auth*** | Yes | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | **application*** | Yes | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | **notifications*** | Yes | array | Content settings. JSON array of message parameters. See details below. | **Notification parameters** | Name | Required | Type | Description | | ---------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **send_date*** | Yes | string | Date and time to send the notification. Use format `YYYY-MM-DD HH:mm` or `now` to send immediately. | | **content*** | Yes | string | Text content of the SMS message. | | **devices*** | Yes | array | Customer phone number (must be associated with a UserId using `/registerDevice` and specified in the `hwid` parameter or use `use_auto_registration`). Only one number can be specified here. | | **use_auto_registration** | No | boolean | If set to `true` the phone number specified in the `devices` parameter will be automatically registered. | | **dynamic_content_placeholders** | No | object | Dynamic content placeholders to customize the message content. Each placeholder will be replaced with corresponding dynamic values. | | **preset** | No | string | SMS [Preset Code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#preset-code) from your Control Panel. | ### Request example ```json { "request": { "application": "12345-67891", // required. Pushwoosh application code. "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel. "notifications": [{ "send_date": "now", // required. YYYY-MM-DD HH:mm OR "now". "content": "Hello!", // required. SMS text (string). "devices": ["+1234567890"], // required. Customer phone number (must be associated with // a UserId using. /registerDevice and specified in // the "hwid" parameter or use "use_auto_registration"). // Only one number can be specified here. "preset": "XXXXX-XXXXX", // optional. SMS Preset Code from your Control Panel. "use_auto_registration": true // optional. Automatically register phone number specified // in "devices" parameter. }] } } ``` ### Response example ```json { "status_code": 200, "status_message": "OK", "response": { "Messages": [ "9648-0B10ECB6-0D9F214D" ] } } ``` ### Error response ```json { "status_code": 210, "status_message": "Invalid devices list. \"devices\" must be an array.", "response": { "Messages": [] } } ``` Note Currently, each SMS must be sent in a separate request for each customer. To get SMS statistics, use the [totalsByIntervals](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#totalsbyintervals) method. You can also view statistics for each message in the [Message History](https://docs.pushwoosh.com/product/statistics-and-analytics/message-history/) section. Caution Please note that some mobile operators do not transmit delivery status data, so the statistics may need to be more accurate. You can check the details with the mobile operators that provide numbers to your customers. --- # SMTP gateway **URL:** https://docs.pushwoosh.com/developer/api-reference/smtp-gateway/ Send Pushwoosh transactional email through any SMTP client. Authenticate with your application code and API token; the gateway forwards every message to Messaging API v2. --- The SMTP gateway accepts standard mail submission and forwards each message to [Messaging API v2 `Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) as a transactional email. Use it when an existing mail tool — an MTA, a framework mailer, an SDK — is easier to plug in than a JSON request to the API. Note The gateway is transactional-only. For audience segments, scheduling, or A/B campaigns, call [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) directly. ## How it works ```plaintext any SMTP client smtp gateway Messaging API v2 ──────────────── ──────> ──────────────── ──────> ───────────────── submission STARTTLS gRPC Notify AUTH PLAIN + AUTH PLAIN Authorization: Token ``` 1. The client connects to `smtp.pushwoosh.com` on port `587`, upgrades the connection to TLS with `STARTTLS`, then authenticates with `AUTH PLAIN`. 2. The gateway parses the MIME message and builds a `Notify` request with `platforms: ["EMAIL"]` and `message_type: TRANSACTIONAL`. 3. The API token from `AUTH PLAIN` is forwarded to Messaging API as the `Authorization` header. Token validation, application matching, sending identity, and bounce handling all happen on the API side. ## Endpoint | Setting | Value | | ------- | ------------------------------------ | | Host | `smtp.pushwoosh.com` | | Port | `587` (SMTP submission) | | TLS | `STARTTLS` — mandatory before `AUTH` | | Auth | `AUTH PLAIN` | ## Authentication `AUTH PLAIN` uses two Pushwoosh credentials. | AUTH field | Pushwoosh value | | ---------- | --------------------------------------------------------------------------------------------------------- | | `username` | [Application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code), for example `XXXXX-XXXXX` | | `password` | [Server API token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#server-api-token) | `AUTH` is rejected outside TLS. The token never appears in the message — it is only used to authorize the upstream `Notify` call. ## How messages map to Notify | MIME or SMTP field | Notify field | | ------------------ | ----------------------------------------------------------------------------------- | | `RCPT TO` | `target.users.list` — Pushwoosh resolves these addresses to subscribers | | AUTH `username` | `application` | | `Subject:` header | `email_payload.subject["default"]` (RFC 2047 decoded) | | `From:` header | `email_payload.from` — `name` and `email` | | HTML part | `email_payload.body` (preferred when both parts are present) | | Plain-text part | `email_payload.body` (used when HTML is absent) | | `MAIL FROM` | Ignored — Pushwoosh substitutes its own sending identity and handles bounces itself | Every message is sent with `schedule.send_date: now`. ## Limits | Limit | Value | | ------------------------------------------- | ------ | | Maximum message size | 25 MiB | | Maximum recipients per envelope (`RCPT TO`) | 50 | ## Error mapping gRPC status codes returned by Messaging API are translated to standard SMTP reply codes so that any SMTP client surfaces a meaningful error. | Upstream gRPC status | SMTP reply | Meaning | | ------------------------------------------------------- | ----------- | ------------------------------------------------------- | | `Unauthenticated` | `535 5.7.8` | Bad application code or API token. | | `PermissionDenied` | `550 5.7.1` | The token has no rights for this application. | | `InvalidArgument` / `FailedPrecondition` / `OutOfRange` | `550 5.6.0` | Bad MIME content (for example missing subject or body). | | `NotFound` | `550 5.1.1` | Application or recipient was not found. | | `ResourceExhausted` | `452 4.5.3` | Rate limit reached — retry later. | | `DeadlineExceeded` / `Unavailable` | `451 4.4.1` | Transient upstream error — retry later. | | any other failure | `451 4.5.0` | Transient internal error — retry later. | Codes in the `4xx` range are temporary and should be retried by the client; codes in the `5xx` range are permanent and require a client-side fix. ## Example: send with swaks ```bash swaks --server smtp.pushwoosh.com:587 \ --auth-user "XXXXX-XXXXX" \ --auth-password "YOUR_API_TOKEN" \ --tls \ --from from@example.com \ --to user@example.com \ --header "Subject: Hello from SMTP gateway" \ --body "Plain-text body" ``` The `From:` header in the MIME body is what reaches Pushwoosh — the `--from` envelope (`MAIL FROM`) is discarded. ## Notes * The gateway is stateless and does not store messages. Once forwarded, delivery is owned by Messaging API. * Bounces, complaints, and unsubscribe links are handled by Pushwoosh, the same as for any other transactional email. * For campaign sending (segments, scheduling, A/B), use [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) directly — the SMTP gateway is submission-only. ## See also [Messaging API v2 overview ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/) [Notify ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) [Email payload reference ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/email-payload-reference/) [Marketing vs transactional ](https://docs.pushwoosh.com/product/messaging-channels/marketing-vs-transactional/) --- # Application and subscriber statistics **URL:** https://docs.pushwoosh.com/developer/api-reference/statistics-api/application-subscriber-statistics/ Retrieve and analyze your app statistics and subscriber metrics, device types, and engagement data for insights --- ## getAppStats Get the statistics of a specific app for a defined time period. `POST` `https://api.pushwoosh.com/json/1.3/getAppStats` ##### Request body parameters | Name | Required | Type | Description | | ------------- | -------- | ------ | -------------------------------------------------------------------------------------------- | | `auth` | Yes | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/) from Pushwoosh Control Panel. | | `application` | Yes | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | `datefrom` | Yes | string | Start date and time of the reporting period. Format: `Y-m-d H:i:s`. | | `dateto` | Yes | string | End date and time of the reporting period. Format: `Y-m-d H:i:s`. | ##### Request example ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX", // required. Pushwoosh application code "datefrom": "2013-06-04 00:00:00", // required. Date and time, start of the reporting period "dateto": "2013-06-07 00:00:00" // required. Date and time, end of the reporting period } } ``` ##### Response example ```json { "status_code": 200, "status_message": "OK", "response": { "request_id": "c93a202f439235f9adaaa06d651548ab" } } ``` ### Understanding the statistics Statistics display registered actions for an application, device, or message within the specified timeframe. Reports are automatically aggregated using the following rules: * **Yearly**: If the period is longer than one year. * **Monthly**: If the period is longer than one month. * **Daily**: If the period is longer than one day. * **Hourly**: If the period is longer than three hours. * **Minutely**: In all other cases. ##### Action types * **Application Level**: `_open_`, `_install_` * **Device Level**: `_register_`, `_unregister_` * **Message Level**: `_send_`, `_open_` ##### Response format All statistics objects have the same format: | Field | Type | Description | | ----------- | ------ | ------------------------------------------------------- | | `formatter` | string | Report scale: yearly, monthly, daily, hourly, minutely. | | `rows` | list | Contains report data for each registered action. | Each report row contains: | Field | Type | Description | | ---------- | ------ | ------------------------------ | | `count` | int | Number of registered actions. | | `action` | string | The type of registered action. | | `datetime` | string | Formatted date: `Y-m-d H:i:s`. | ### Retrieving scheduled request results Important As with every scheduled request, `/getAppStats` requires an additional [`/getResults`](https://docs.pushwoosh.com/developer/api-reference/scheduled-requests#getresults) request. ##### Response body | Field | Type | Description | | ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------ | | `request_id` | string | Scheduled request ID. Refer to [`/getResults`](https://docs.pushwoosh.com/developer/api-reference/scheduled-requests#getresults) for more details. | ##### Scheduled (/getResults) response body | Field | Type | Description | | -------------- | ---------- | ---------------------------- | | `applications` | dictionary | Statistics for applications. | | `devices` | dictionary | Statistics for devices. | | `messages` | dictionary | Statistics for messages. | ##### Example ```json { "error": { "code": 0, "message": "OK" }, "json_data": { "applications": { "formatter": "hourly", "rows": [{ "count": 0, "action": "open", "datetime": "2013-06-06 00:00:00" }, { ... }] } } } ``` ## getApplicationSubscribersStats Displays the app’s subscribers list grouped by the types of their devices. `POST` `https://api.pushwoosh.com/json/1.3/getApplicationSubscribersStats` ##### Request Body | Name | Required | Type | Description | | ------------- | -------- | ------ | -------------------------------------------------------------------------------------------- | | `auth` | Yes | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/) from Pushwoosh Control Panel. | | `application` | Yes | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | **Request example** ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX" // required. Pushwoosh application code } } ``` * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "IOS": 1, "ANDROID": 1, "OSX": 0, "WINDOWS": 0, "AMAZON": 0, "SAFARI": 0, "FIREFOX": 0 } } ``` ## getSubscribersStatistics Retrieves app subscribers stats for a time period. `POST` `https://api.pushwoosh.com/api/v2/statistics/application/getSubscribersStatistics` ##### Headers | Name | Required | Description | | ------------- | -------- | -------------------------------------------------------------------------------------------------- | | Authorization | Yes | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/) in the format: `Key PKX.......NHg`. | | Content-Type | Yes | Must be set to `application/json`. | ##### Request body parameters | Name | Required | Type | Description | | ----------------- | -------- | ------ | ---------------------------------------------------------------------------------------- | | application_code | Yes | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | timestamp_from | Yes | string | Start date and time of the stats period (format: `YYYY-MM-DD hh:mm:ss`, UTC+0). | | timestamp_to | Yes | string | End date and time of the stats period (format: `YYYY-MM-DD hh:mm:ss`, UTC+0). | **Example request** ```shell curl --location --request POST 'https://api.pushwoosh.com/api/v2/statistics/application/getSubscribersStatistics' \ --header 'Authorization: Key 3a2X......828JreCk48f' \ --header 'Content-Type: application/json' \ --data-raw '{ "application_code": "12345-67890", // Pushwoosh app code "timestamp_from": "2022-08-01 00:00:00", // UTC+0 "timestamp_to": "2022-09-01 00:00:00" // UTC+0 }' ``` **Example response** ```json { "statistics": [{ "timestamp": "YYYY-MM-DD hh:mm:ss", // UTC+0 "platform": 1, "push_enabled": 100, "push_disabled": 100 }] } ``` **Response codes** * 200: OK ```json { "statistics": [{ "timestamp": "YYYY-MM-DD hh:mm:ss", "platform": 1, "push_enabled": 100, "push_disabled": 100 }] } ``` **Explanation**: The request was successful, and the statistics are returned. * 400: Bad Request ```json { // Response } ``` **Explanation**: The request had invalid syntax or parameters. * 500: Internal Server Error ```json { // Response } ``` **Explanation**: The server encountered an error. Try again later. * 401: Unauthorized ```json { // Response } ``` **Explanation**: Authentication failed. Check your API key or token. * 403: Forbidden ```json { // Response } ``` **Explanation**: Access denied for the specified app code. * 404: Not Found ```json { // Response } ``` **Explanation**: The app code was not found or doesn’t exist. ### Timestamp interval rules Note Please take into consideration that the intervals between timestamps in the response depend on the period you send in your request as follows: * if you request the stats for a period longer than one year, the stats timestamps interval will be a year * if the stats period equals a year, the interval between response’s timestamps equals a month * for periods longer than a month but less than a year, stats for every day will be returned * for periods less than a month, the response will include stats for every hour | Requested period | Interval in response | | ----------------- | -------------------- | | More than 1 year | 1 year | | 1 year | 1 month | | 1 month - 1 year | 1 day | | Less than 1 month | 1 hour | --- # Campaign statistics **URL:** https://docs.pushwoosh.com/developer/api-reference/statistics-api/campaign-statistics/ Retrieve detailed campaign statistics in Pushwoosh, including sent, opened, and conversion metrics for a specified time period --- ## getCampaignStats Retrieve statistics of a particular campaign for a specific time period. `POST` `https://api.pushwoosh.com/json/1.3/getCampaignStats` ##### Request body parameters | Name | Required | Type | Description | | ---------- | -------- | ------ | -------------------------------------------------------------------------------------------- | | `auth` | Yes | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/) from Pushwoosh Control Panel. | | `campaign` | Yes | string | Unique [campaign code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#campaign-code). | | `datefrom` | Yes | string | Start of the reporting period (formatted as `Y-m-d H:i:s`). | | `dateto` | Yes | string | End of the reporting period (formatted as `Y-m-d H:i:s`). | ##### Example request ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "campaign": "XXXXX-XXXXX", // required. Campaign code "datefrom": "2024-05-01 00:00:00", // required. Start of reporting period "dateto": "2024-05-10 23:59:59" // required. End of reporting period } } ``` ##### Example response ```json { "status_code": 200, "status_message": "OK", "response": { "request_id": "a3ef436445abfdef6255cc2f65ce7614" } } ``` #### Retrieving scheduled request results Important Like every scheduled request, `/getCampaignStats` requires an additional [`/getResults`](https://docs.pushwoosh.com/developer/api-reference/scheduled-requests#getresults) request. Example getResults response ```json { "status_code": 200, "status_message": "OK", "response": { "formatter": "hourly", "rows": [{ "count": 0, "action": "open", "datetime": "2024-05-09 00:00:00", "platformid": 14 }, { "count": 0, "action": "send", "datetime": "2024-05-09 00:00:00", "platformid": 14 }, { "count": 0, "action": "send", "datetime": "2024-05-11 00:00:00", "platformid": 14 }], // conversion (if goal tracking is allowed) "conversion": { "send": 10, "open": 5, "events": [{ "uid": 1, "event": "event name", "hits": 5, "conversion": "100%", "revenue": 15.34 }] } } } ``` --- # Events and tags statistics **URL:** https://docs.pushwoosh.com/developer/api-reference/statistics-api/events-and-tags-statistics/ Learn how to retrieve event and tag statistics in Pushwoosh, track user interactions, and analyze tag usage with API requests --- ## getEventStatistics Retrieves the number of times an event was triggered during a specified period. `POST` `https://api.pushwoosh.com/json/1.3/getEventStatistics` ##### Request body parameters | Name | Required | Type | Description | | ------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------ | | `auth` | Yes | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/) from Pushwoosh Control Panel. | | `application` | Yes | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | `event` | Yes | string | [Event name](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#event-name), exactly as created in Pushwoosh Control Panel. | | `date_from` | Yes | string | Start of the period to retrieve statistics for. | | `date_to` | Yes | string | End of the period to retrieve statistics for. | | `attributes` | No | array | An array of event attributes for filtering results. | ##### Example request ```json { "request": { "auth":"yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX", // required. Pushwoosh application code "event": "Event name", // required. The name of Event exactly as created in Pushwoosh Control Panel "date_from": "2024-09-12", // required. Start of the reporting period "date_to": "2024-09-12", // required. End of the reporting period "attributes": [{ // optional. "name": "attributeName", "operator": "EQ", "values": ["val"] }] } } ``` ##### Example response ```json { "status_code": 200, "status_message": "OK", "response": { "request_id": "DC1_bc63f00c736696d75cea17aa6855ba19" } } ``` #### Retrieving scheduled request results Important Like every scheduled request, **/getEventStatistics** requires an additional [`/getResults`](https://docs.pushwoosh.com/developer/api-reference/scheduled-requests#getresults) request. ##### Request body parameters | Field | Type | Description | | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------------- | | `request_id` | string | Scheduled request ID. Use [`/getResults`](https://docs.pushwoosh.com/developer/api-reference/scheduled-requests#getresults) to retrieve results. | Scheduled (/getResults) response ```json { "status_code": 200, "status_message": "OK", "response": [{ "date": "2024-09-12 00:00", "count": 12 }, { "date": "2024-09-12 01:00", "count": 2 }, { "date": "2024-09-12 02:00", "count": 4 }, { "date": "2024-09-12 03:00", "count": 8 }, { "date": "2024-09-12 04:00", "count": 9 }, { "date": "2024-09-12 05:00", "count": 2 }, { "date": "2024-09-12 06:00", "count": 0 }, { "date": "2024-09-12 07:00", "count": 0 }, { "date": "2024-09-12 08:00", "count": 0 }, { "date": "2024-09-12 09:00", "count": 0 }, { "date": "2024-09-12 10:00", "count": 0 }, { "date": "2024-09-12 11:00", "count": 0 }, { "date": "2024-09-12 12:00", "count": 0 }, { "date": "2024-09-12 13:00", "count": 0 }, { "date": "2024-09-12 14:00", "count": 0 }, { "date": "2024-09-12 15:00", "count": 0 }, { "date": "2024-09-12 16:00", "count": 0 }, { "date": "2024-09-12 17:00", "count": 0 }, { "date": "2024-09-12 18:00", "count": 0 }, { "date": "2024-09-12 19:00", "count": 0 }, { "date": "2024-09-12 20:00", "count": 0 }, { "date": "2024-09-12 21:00", "count": 0 }, { "date": "2024-09-12 22:00", "count": 0 }, { "date": "2024-09-12 23:00", "count": 0 }] } ``` ## getTagStats Retrieves statistics for a specific tag. `POST` `https://api.pushwoosh.com/json/1.3/getTagStats` ##### Request body parameters | Name | Required | Type | Description | | -------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `auth` | Yes | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/) from Pushwoosh Control Panel. | | `tag` | Yes | string | [Tag name](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#tag), exactly as in Pushwoosh Control Panel. | | `applications` | No | array | List of [applications](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). Specify only if the tag is application-specific. | ##### Example request ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", "tag": "TAG_NAME", "applications": [ "APPLICATION_1", "APPLICATION_2", "APPLICATION_3" ] } } ``` #### Retrieving scheduled request results Important Like every scheduled request, **getTagStats** requires an additional [`/getResults`](https://docs.pushwoosh.com/developer/api-reference/scheduled-requests#getresults) request. ##### `/getResults` response ```json { "status_code": 200, "status_message": "OK", "response": { "fileName": "DIRECT_FILE_URL.csv" } } ``` Note The response file is a CSV with a semicolon (`;`) separator. #### Example CSV content ```csv 13C2B-72C62;ua_settingpushbod;3 13C2B-72C62;ua_settingpushhealth;3 13C2B-72C62;ua_settingpushstrength;3 13C2B-72C62;ua_settingpushupdate;2 ``` --- # Asynchronous message statistics export **URL:** https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/ API methods to export message history and statistics as a CSV file in the background, without the row limits of messages:list. --- `exportMessagesStatistics` exports message history and statistics to a CSV file on the server. Use it for large or full-account pulls that [`messages:list`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#messageslist) can’t handle. ## When to use export instead of messages:list Use `messages:list` for live, paginated lookups of a bounded period. Use `exportMessagesStatistics` when the result would exceed the deep-pagination limit of `messages:list` (`page × per_page > 100000`), or when the goal is a single downloadable file rather than paged JSON. The export has no limit on `date_range` or row count, because it streams the result to a file on disk instead of holding it in one response. Shared export capacity, 7-day retention This account shares a small pool of workers with every other Pushwoosh account, and that pool serves every export task type (message history, tracking-log CSV, journey exports, segment exports), not just this one. Use it for occasional full-history pulls, not frequent reporting. Concurrent export requests (yours, another account’s, or another export type) queue and wait their turn. Download the file within 7 days: after that the cleanup job deletes it and the URL stops resolving. ## How the export flow works 1. Call [`export`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#export) with the same filters as `messages:list`. The response returns a `uid` task identifier immediately, before the file is generated. 2. Poll [`status`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#status) with that `uid` until it reports `STATUS_SUCCESS` (or `STATUS_FAILED`). 3. Call [`result`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#result) with the same `uid` to get the generated file name. 4. [Download](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#download) the file by name. Use [`lastTasks`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#lasttasks) to look up recent export tasks for an application, and [`delete`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#delete) to cancel a task or remove its file early. ## Methods The export lifecycle has five methods, plus a plain download endpoint: | Method | Description | | -------------------------------------------------- | ----------------------------------------------------------------------- | | [`exportMessagesStatistics/export`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#export) | Queues an export and returns a task `uid`. | | [`exportMessagesStatistics/status`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#status) | Checks task progress. | | [`exportMessagesStatistics/result`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#result) | Returns the generated file name once the task is done. | | [`exportMessagesStatistics/lastTasks`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#lasttasks) | Lists recent export tasks for an application. | | [`exportMessagesStatistics/delete`](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#delete) | Cancels a task or removes its file before the retention window expires. | | [Download](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#download) | Downloads the generated CSV file by name. | ### export Queues a message history export and returns a task identifier right away. `POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/export` ##### Headers The request needs a Server API token: | Name | Required | Description | | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Authorization` | Yes | [Server API token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#server-api-token). Must be provided in the following format: `Authorization: Api `. | ##### Request body parameters The request body accepts the following fields: | Name | Required | Type | Description | | ------------------------------------- | -------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `type` | Yes | String | Must be `“TASK_TYPE_EXPORT_MESSAGES_V2”`. | | `export_messages_v2` | Yes | Object | Export parameters, described below. | | `export_messages_v2.application_code` | See note | String | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). Required if `app_group_code` is not set. | | `export_messages_v2.app_group_code` | See note | String | Application group code, exports across every app in the group. Required if `application_code` is not set. | | `export_messages_v2.search` | No | String | Free-text search over message title and content. | | `export_messages_v2.filters` | No | Object | Message filters, described below. Omit to export the whole account history. | | `export_messages_v2.properties` | No | Array | Columns to include in the CSV, described below. | `export_messages_v2.filters` accepts: | Name | Type | Description | | -------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `statuses` | Array | Message statuses to include.Possible values- `”MESSAGE_STATUS_CANCELED"` - `"MESSAGE_STATUS_CREATING"` - `"MESSAGE_STATUS_DONE"` - `"MESSAGE_STATUS_FAIL"` - `"MESSAGE_STATUS_PENDING"` - `"MESSAGE_STATUS_PROCESSING"` - `"MESSAGE_STATUS_WAITING”` | | `platforms` | Array | [Platform codes](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#platforms) (numeric, e.g. `1` for iOS), not the platform name strings used by `messages:list`. | | `sent_date` | Object | Reporting period filtered on send date: `{"date_from": "YYYY-MM-DD", "date_to": "YYYY-MM-DD"}`. | | `created_date` | Object | Reporting period filtered on message creation date, same format as `sent_date`. | | `created_via` | Array | Message source.Possible values- `”AB_TEST"` - `"API"` - `"AUTO_PUSH"` - `"CP"` - `"CSV"` - `"CUSTOMER_JOURNEY"` - `"EMAIL_API"` - `"EMAIL_CP"` - `"GEO_ZONE"` - `"PUSH_ON_EVENT"` - `"RSS"` - `"SYSTEM”` | | `segments` | Array | [Filter codes](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#segment--filter-code) the message was sent to. | | `campaigns` | Array | [Campaign codes](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#campaign-code). Unlike `messages:list`, this takes a list, not a single code. | | `message_id` | String (uint64) | A single numeric message ID, quoted. Unlike `messages:list`, export takes one ID, not an array. | | `message_code` | String | A single [message code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#message-code). | `export_messages_v2.properties` selects which columns the CSV contains. Possible values * `"EXPORT_MESSAGE_PROPERTY_ID"` * `"EXPORT_MESSAGE_PROPERTY_TIMESTAMP"` * `"EXPORT_MESSAGE_PROPERTY_CONTENT"` * `"EXPORT_MESSAGE_PROPERTY_TITLE"` * `"EXPORT_MESSAGE_PROPERTY_APPLICATIONS"` * `"EXPORT_MESSAGE_PROPERTY_STATUS"` * `"EXPORT_MESSAGE_PROPERTY_PLATFORMS"` * `"EXPORT_MESSAGE_PROPERTY_SOURCE"` * `"EXPORT_MESSAGE_PROPERTY_FILTER"` * `"EXPORT_MESSAGE_PROPERTY_SUBSCRIPTION_SEGMENTS"` * `"EXPORT_MESSAGE_PROPERTY_SENT"` * `"EXPORT_MESSAGE_PROPERTY_OPENED"` * `"EXPORT_MESSAGE_PROPERTY_ERRORS"` * `"EXPORT_MESSAGE_PROPERTY_RECIPIENTS"` * `"EXPORT_MESSAGE_PROPERTY_DELIVERED"` * `"EXPORT_MESSAGE_PROPERTY_TOTAL_DELIVERED"` * `"EXPORT_MESSAGE_PROPERTY_TOTAL_OPENED"` * `"EXPORT_MESSAGE_PROPERTY_TOTAL_CLICKS"` * `"EXPORT_MESSAGE_PROPERTY_CLICKS"` * `"EXPORT_MESSAGE_PROPERTY_UNSUBSCRIBED"` properties is not just a filter A property not listed in `properties` does not appear in the file at all, including the base columns (ID, send date, content, status). Leaving `properties` empty produces a CSV with no columns. List every column the export should contain, not only the metrics you want to add on top of a default set. ##### Example request ```json { "type": "TASK_TYPE_EXPORT_MESSAGES_V2", "export_messages_v2": { "application_code": "XXXXX-XXXXX", "filters": { "created_date": { "date_from": "2026-01-01", "date_to": "2026-06-30" }, "statuses": ["MESSAGE_STATUS_DONE"], "platforms": [1, 3] }, "properties": [ "EXPORT_MESSAGE_PROPERTY_ID", "EXPORT_MESSAGE_PROPERTY_TIMESTAMP", "EXPORT_MESSAGE_PROPERTY_STATUS", "EXPORT_MESSAGE_PROPERTY_PLATFORMS", "EXPORT_MESSAGE_PROPERTY_SENT", "EXPORT_MESSAGE_PROPERTY_OPENED" ] } } ``` * 200: OK ```json { "uid": "177458" } ``` * 401: Incorrect API access token ```json { "error": "account not found" } ``` ### status Returns the progress of an export task. `POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/status` ##### Request body parameters Pass the task identifier returned by `export`: | Name | Required | Type | Description | | ----- | -------- | -------------- | ------------------------------------------------------------ | | `uid` | Yes | String (int64) | Task identifier from the `export` response, e.g. `"177458"`. | ##### Example request ```json { "uid": "177458" } ``` * 200: OK ```json { "status": "STATUS_SUCCESS", "progress": 1 } ``` `status` is one of `"STATUS_PENDING"`, `"STATUS_SUCCESS"`, or `"STATUS_FAILED"`. `progress` is a fraction between `0` and `1`; poll `status` until it reaches `"STATUS_SUCCESS"` before calling `result`. ### result Returns the generated file name once the task has completed. `POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/result` ##### Request body parameters Pass the same task identifier returned by `export`: | Name | Required | Type | Description | | ----- | -------- | -------------- | ------------------------------------------------------------ | | `uid` | Yes | String (int64) | Task identifier from the `export` response, e.g. `"177458"`. | ##### Example request ```json { "uid": "177458" } ``` * 200: OK ```json { "export_messages_v2_result": { "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv" } } ``` Calling `result` before `status` reports `"STATUS_SUCCESS"` returns an empty result. Pass the `file` value as-is to the [download endpoint](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/#download). ### lastTasks Lists recent export tasks for an application, most recent first. `POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/lastTasks` ##### Request body parameters Every parameter is an optional filter; omit them all to list every task the token has access to: | Name | Required | Type | Description | | ---------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `application` | No | String | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). Omit to list tasks across all applications the token has access to. | | `types` | No | Array | Restrict to specific task types. Use `[“TASK_TYPE_EXPORT_MESSAGES_V2”]` to only see message exports. | | `campaign` | No | String | Filter by [campaign code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#campaign-code). | | `message_id` | No | String (uint64) | Filter by a single numeric message ID, quoted. | | `message_code` | No | String | Filter by a single [message code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#message-code). | | `limit` | No | Integer | Maximum number of tasks to return. | | `timestamp_from` | No | String | Only return tasks created after this timestamp (RFC 3339). | Note Tasks are kept for 30 days regardless of whether their file has already been deleted after the 7-day file retention window. `lastTasks` can still show a task whose `result` no longer resolves to a downloadable file. ##### Example request ```json { "application": "XXXXX-XXXXX", "types": ["TASK_TYPE_EXPORT_MESSAGES_V2"], "limit": 10 } ``` * 200: OK ```json { "tasks": [ { "id": "177458", "timestamp": "2026-08-13T12:00:00Z", "status": "STATUS_SUCCESS", "requested_by_user": "user@example.com", "export_messages_v2": { "application_code": "XXXXX-XXXXX" }, "export_messages_v2_result": { "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv" } } ] } ``` ### delete Deletes a task and its file before the 7-day retention window expires. `POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/delete` ##### Request body parameters Pass the task identifier returned by `export`: | Name | Required | Type | Description | | ----- | -------- | -------------- | ------------------------------------------------------------ | | `uid` | Yes | String (int64) | Task identifier from the `export` response, e.g. `"177458"`. | ##### Example request ```json { "uid": "177458" } ``` * 200: OK ```json {} ``` ### Download Downloads the CSV file generated by `result`, by name. `GET` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/` ##### Headers Authenticate the same way as the other methods, or rely on an active Control Panel session: | Name | Required | Description | | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Authorization` | Yes | [Server API token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#server-api-token), in the same format as the other `exportMessagesStatistics` methods: `Authorization: Api ` (the `Api` scheme is case-insensitive). A request with no `Authorization` header and no logged-in Control Panel session gets `401 Unauthorized`. | Replace `` with the exact `file` value from the `result` response, for example: ```plaintext https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv ``` The file is a CSV containing the columns selected in `properties`. It stays available for 7 days after the export finishes, then the cleanup job removes it and the URL stops resolving. --- # In-app statistics **URL:** https://docs.pushwoosh.com/developer/api-reference/statistics-api/inapp-statistics/ Retrieve impression, interaction and frequency capping metrics for instant in-app campaigns, as totals or as a time series. --- Two methods return statistics for [instant in-app campaigns](https://docs.pushwoosh.com/product/messaging-channels/in-apps/send-in-apps/send-instant-in-apps/). Use `inapps:totals` for period totals across one or more campaigns, and `inapps:timeline` for a time series of a single campaign. The values match the [in-app statistics screen](https://docs.pushwoosh.com/product/statistics-and-analytics/messaging-statistics/in-app-statistics/) in the Control Panel. In-apps sent from a Journey These methods cover instant in-app campaigns only. In-apps delivered by a Customer Journey element are reported per journey point by [Get Journey stats](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/statistics/). ## Metrics | Field | Type | Description | | --------------------- | ------ | -------------------------------------------------------------------------------------- | | `impressions` | number | How many times the in-app was displayed. Labeled **Impressions** in the Control Panel. | | `unique_impressions` | number | Number of unique devices the in-app was displayed to. | | `interactions` | number | Interactions with the in-app content: button clicks, link clicks and form submits. | | `unique_interactions` | number | Number of unique devices that interacted with the in-app. | | `skips` | number | How many times users dismissed the in-app without interacting. | | `audience` | number | Number of unique devices that produced any in-app event in the period. | Note Unique metrics and `audience` are approximate because they use a probabilistic distinct count. Platform figures do not sum to the campaign total: a device that appears on two platforms is counted once in each platform breakdown and once in the campaign total. ## inapps:totals Returns totals for the period. Pass `inapp_codes` to report on specific campaigns, or omit it to walk every in-app of the application page by page. That is the method to use for a scheduled export. `POST` `https://api.pushwoosh.com/api/v2/statistics/inapps:totals` ##### Headers | Name | Required | Description | | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | `Authorization` | Yes | [Server API token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#server-api-token) in the format `Authorization: Api `. | ##### Request body parameters | Name | Required | Type | Description | | ---------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `application` | Yes | String | [Application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). | | `date_range` | Yes | Object | Reporting period. `date_from` and `date_to` use the `YYYY-MM-DD` format and are inclusive. The period is counted in UTC and must not exceed 366 days. | | `inapp_codes` | No | Array | [In-app codes](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#in-app-code), up to 100 per request. Omit to report on all in-apps of the application. If any code in the list does not belong to the application, the whole request fails with `404`. | | `platforms` | No | Array | Restrict the metrics to these platforms. Possible values: `"IOS"`, `"ANDROID"`, `"HUAWEI_ANDROID"`, `"AMAZON"`, `"OSX"`, `"WINDOWS"`, `"SAFARI"`, `"CHROME"`, `"FIREFOX"`, `"WEB"`. | | `with_platforms` | No | Boolean | Add a per-platform breakdown to every item. | | `page` | No | Integer | Page number, starting at `0`. Applies when `inapp_codes` is omitted. | | `per_page` | No | Integer | Items per page, `20` by default, `100` at most. | ##### Example request ```bash curl -X POST https://api.pushwoosh.com/api/v2/statistics/inapps:totals \ -H "Authorization: Api YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "application": "XXXXX-XXXXX", "date_range": { "date_from": "2026-07-01", "date_to": "2026-07-31" }, "inapp_codes": ["AAAAA-BBBBB"], "with_platforms": true }' ``` ##### Response fields `total` is the number of in-apps the request matches. When `inapp_codes` is omitted, that is all in-apps of the application, so pagination can walk it. `items` holds the current page. `page` counts from `0`. ##### Example response ```json { "total": 1, "page": 0, "per_page": 20, "items": [{ "inapp": { "code": "AAAAA-BBBBB", "name": "Summer sale", "status": "active", "rich_media_code": "CCCCC-DDDDD" }, "metrics": { "impressions": 15230, "unique_impressions": 9120, "interactions": 2311, "unique_interactions": 1980, "skips": 640, "audience": 9120 }, "platforms": [{ "platform": "IOS", "metrics": { "impressions": 8100, "unique_impressions": 4900, "interactions": 1300, "unique_interactions": 1120, "skips": 310, "audience": 4900 } }], "frequency_capping": { "suppressions": 45, "affected_users": 30, "data_available_from": "2026-07-17" } }] } ``` ## inapps:timeline Returns period totals and a time series for one in-app campaign. `POST` `https://api.pushwoosh.com/api/v2/statistics/inapps:timeline` ##### Request body parameters | Name | Required | Type | Description | | ---------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `application` | Yes | String | [Application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). | | `inapp_code` | Yes | String | [In-app code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#in-app-code). | | `date_range` | Yes | Object | Reporting period. `date_from` and `date_to` use the `YYYY-MM-DD` format and are inclusive. The period is counted in UTC and must not exceed 366 days. Optional `interval`: `"HOUR"`, `"DAY"` (default), `"WEEK"` or `"MONTH"`. `"HOUR"` is available for periods up to 31 days. | | `platforms` | No | Array | Restrict the metrics to these platforms. | | `with_platforms` | No | Boolean | Add a per-platform breakdown to the totals and to every row. | ##### Example request ```bash curl -X POST https://api.pushwoosh.com/api/v2/statistics/inapps:timeline \ -H "Authorization: Api YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "application": "XXXXX-XXXXX", "inapp_code": "AAAAA-BBBBB", "date_range": { "date_from": "2026-07-01", "date_to": "2026-07-07", "interval": "DAY" } }' ``` ##### Example response ```json { "inapp": { "code": "AAAAA-BBBBB", "name": "Summer sale", "status": "active", "rich_media_code": "CCCCC-DDDDD" }, "totals": { "impressions": 15230, "unique_impressions": 9120, "interactions": 2311, "unique_interactions": 1980, "skips": 640, "audience": 9120 }, "frequency_capping": { "suppressions": 45, "affected_users": 30, "data_available_from": "2026-07-17" }, "rows": [{ "timestamp": "2026-07-01T00:00:00Z", "metrics": { "impressions": 2140, "unique_impressions": 1700, "interactions": 320, "unique_interactions": 290, "skips": 95, "audience": 1700 } }], "impression_duration": [ { "from_seconds": 0, "to_seconds": 5, "count": 3200 }, { "from_seconds": 5, "to_seconds": 15, "count": 5400 }, { "from_seconds": 15, "to_seconds": 30, "count": 4100 }, { "from_seconds": 30, "to_seconds": 0, "count": 2530 } ] } ``` `impression_duration` buckets how long the in-app stayed on screen. In the last bucket `to_seconds` is `0`, which means “30 seconds and longer”. ## Frequency capping The `frequency_capping` block reports in-app displays that [frequency capping](https://docs.pushwoosh.com/product/messaging-channels/global-frequency-capping/) prevented, and the number of unique users affected. Suppressions are not counted in `impressions`. Suppression data starts on 17 July 2026 Suppressions were not recorded before that date. For a period that ends earlier, the `frequency_capping` block comes back as `null` instead of zeros, so a lack of data is never mistaken for capping that suppressed nothing. `data_available_from` in the response states the first covered day. Frequency capping has no per-platform breakdown. ## Data retention Statistics are kept for 365 days, so a period that starts earlier returns no data for the uncovered days. ## Response codes | Code | Meaning | | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | Success. | | 400 | Invalid request: a missing or malformed `date_range`, a period longer than 366 days, an hourly interval over more than 31 days, or more than 100 `inapp_codes`. | | 401 | Missing or invalid API token. | | 404 | An in-app code was not found in this application. | --- # Message statistics **URL:** https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/ List of API methods for retrieving and analyzing message statistics, including delivery rates, open rates, and user engagement. --- ## messages:list Displays the list of sent messages. `POST` `https://api.pushwoosh.com/api/v2/messages:list` ##### Headers | Name | Required | Description | | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Authorization` | Yes | [Server API token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#server-api-token). Must be provided in the following format: `Authorization: Api `. | ##### Request body parameters | Name | Required | Type | Description | | ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `platforms` | No | Array | Message platforms. Possible values: `"IOS"`, `"ANDROID"`, `"OSX"`, `"WINDOWS"`, `"AMAZON"`, `"SAFARI"`, `"CHROME"`, `"FIREFOX"`, `"IE"`, `"EMAIL"`, `"HUAWEI_ANDROID"`, `"SMS"`. | | `date_range` | No | Object | Reporting period, filtered on message creation date. `date_from` and `date_to` must follow the `YYYY-MM-DD` format (e.g., `"2000-01-01"`); both days are included in full, so `date_from` and `date_to` set to the same date return that whole day. | | `campaign` | No | String | [Campaign code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#campaign-code) | | `filters` | Yes | Object | Message filters. | | `source` | No | String | Message source. For example: `AB_TEST`, `API`, `AUTO_PUSH`, `CP`, `CSV`, `CUSTOMER_JOURNEY`, `EMAIL_API`, `EMAIL_CP`, `GEO_ZONE`, `PUSH_ON_EVENT`, `RSS`. | | `messages_codes` | No | Array | [Message codes](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#message-code) obtained from `/createMessage` API responses. | | `messages_ids` | No | Array | Message IDs obtained from the Message History | | `params` | No | Object | Specify whether to show message details and metrics. Set `with_details: true` to include the `"details"` object and `with_metrics: true` to include the `"metrics"` object in the response. | | `application` | Yes | String | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code). | | `per_page` | No | Integer | Number of results per page, `1` to `499`. Omit the parameter to get the default page size of 500 results; passing `500` or more explicitly is rejected with `400`. | | `page` | No | Integer | Zero-based page number for pagination. See the deep pagination limit below. | Deep pagination `messages:list` rejects requests where `page × per_page` exceeds 100000 results. Narrow the `date_range` or use a smaller `per_page` to stay within the limit. `total` is the exact number of messages matching the filters while that number is at or below 100000, and stops at `100001` above it — more than this endpoint can page through. Do not size a page loop past that limit: pages beyond it are rejected, not empty. To pull a period that holds more messages than that, narrow the `date_range` per request, or use the [asynchronous export](https://docs.pushwoosh.com/developer/api-reference/statistics-api/export-messages-statistics-api/), which writes the whole period to one CSV file without paging. ##### Example request ```json { "filters": { "platforms": [], // IOS, ANDROID, OSX, WINDOWS, AMAZON, SAFARI, CHROME, FIREFOX, IE, EMAIL, HUAWEI_ANDROID, SMS "date_range": { "date_from": "string", // Required format: 2000-01-01 "date_to": "string" // Required format: 2000-01-01 }, "source": "API", // AB_TEST, API, AUTO_PUSH, CP, CSV, CUSTOMER_JOURNEY, EMAIL_API, EMAIL_CP, GEO_ZONE, PUSH_ON_EVENT, RSS "campaign": "string", // Campaign code "messages_ids": [], // Message IDs "messages_codes": [], // Message codes "application": "string" // Pushwoosh application code }, "params": { "with_details": true, // Add message details to the response ("details" object) "with_metrics": true // Add message metrics to the response ("metrics" object) }, "per_page": 20, // <= 499 "page": 0 } ``` Response codes and examples * 200: OK ```json { "total": 0, "items": [{ "id": 0, "code": "string", "created_date": "string", "send_date": "string", "status": "string", "platforms": [], "source": "string", "push_info": { "details": { "title": "string", "filter_name": "string", "filter_code": "string", "content": { "key": "value" }, "platform_parameters": { "android_header": "string", "android_root_params": { "key": "value" }, "ios_title": "string", "ios_subtitle": "string", "ios_root_params": { "key": "value" }, "chrome_header": "string", "chrome_root_params": { "key": "value" }, "firefox_header": "string", "firefox_root_params": { "key": "value" }, "conditions": [ // tag conditions (see /developer/api-reference/messages-api/#tag-conditions) TAG_CONDITION1, TAG_CONDITION2, ..., TAG_CONDITIONN ], "conditions_operator": "AND", // logical operator for conditions arrays; possible values: AND, OR "data": { "key": "value" } }, "follow_user_timezone": true }, "metrics": [{ "sends": 0, "opens": 0, "deliveries": 0, "inbox_opens": 0, "unshowable_sends": 0, "errors": 0, "platform": 0 }] }, "email_info": { "details": { "template": "string", "filter_name": "string", "filter_code": "string", "subject": { "key": "value" }, "from_name": "string", "from_email": "string", "reply_name": "string", "reply_email": "string", "follow_user_timezone": true, "conditions": [ // tag conditions (see Messages-api - tag-conditions) TAG_CONDITION1, TAG_CONDITION2, ..., TAG_CONDITIONN ], "conditions_operator": "AND" // logical operator for conditions arrays; possible values: AND, OR }, "metrics": [{ "sends": 0, "opens": 0, "deliveries": 0, "hard_bounces": 0, "soft_bounces": 0, "rejects": 0, "confirmed_sends": 0, "unsubs": 0, "complaints": 0, "errors": 0 }] } }] } ``` * 400: Bad Request Error `date_range` spans more than 30 days: ```json { "error": "exceeded the maximum date interval. Max interval: 30 days" } ``` `page × per_page` exceeds the deep pagination limit: ```json { "error": "requested result window is too large, narrow the date range" } ``` * 401: Incorrect API access token ```json { "error": "account not found" } ``` * 500: Internal Server Error Note For iOS, please make sure that you have added the Notification Service Extension to your project for tracking push delivery. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/ios-sdk/ios-message-delivery-tracking) ## totalsByIntervals Returns metrics and conversion data based on the message code, aggregated by hour. **POST** `https://api.pushwoosh.com/api/v2/statistics/messages/totalsByIntervals` ##### Authorization Authorization is handled via the API Access Token in the request header. ##### Request body parameters | Parameter Name | Type | Description | Required | | -------------- | ------ | -------------------------------------------------------------------------------------------------------------------- | -------- | | `message_code` | string | [Message code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#message-code) obtained from `/createMessage` API responses. | Yes | | `platforms` | [int] | [Platforms](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#platforms) | No | ##### Request example ```json { "message_code": "XXXXX-XXXXXXXXX-XXXXXXXX", // required. Unique message identifier "platforms": [1, 3, 7, 10, 11, 12] // optional. List of platform codes } ``` ##### Response fields | Name | Type | Description | | ------------------ | ---------- | -------------------------------------------------------------------------- | | **`metrics`** | **array** | **Contains an array of message metrics** | | `timestamp` | string | The time of the metric. | | `platform` | int | The platform code (e.g., iOS, Android). | | `sends` | string | The number of sent messages. | | `opens` | string | The number of opened messages. | | `deliveries` | string | The number of delivered messages. | | `inbox_opens` | string | The number of inbox opens. | | `unshowable_sends` | string | The number of sent messages that could not be shown. | | `errors` | string | The number of errors. | | **`conversion`** | **object** | **Contains conversion data** | | `sends` | string | The total number of sent messages. | | `opens` | string | The total number of opened messages. | | **`events`** | **array** | **An array of events with their statistics** | | `name` | string | The name of the event (e.g., cart add). | | `hits` | string | The number of hits. | | `conversion` | float | The conversion rate relative to opens. | | `revenue` | float | The revenue (only for events with `__amount` and `__currency` attributes). | ##### Response example ```json { "metrics": [{ "timestamp": "2024-08-03 15:00:00", // Timestamp of the metrics in "YYYY-MM-DD HH:MM:SS" format "platform": 3, // Platform code "sends": "55902", // Number of messages sent "opens": "382", // Number of messages opened "deliveries": "22931", // Number of messages delivered "inbox_opens": "0", // Number of messages opened in the inbox "unshowable_sends": "2", // Number of messages that couldn't be shown "errors": "0" // Number of errors encountered }], "conversion": { "sends": "55902", // Total number of messages sent "opens": "772", // Total number of messages opened "events": [{ "name": "cart_add", // Name of the event "hits": "96", // Number of hits for the event "conversion": 0.12, // Conversion rate relative to opens "revenue": 0 // Revenue generated by the event (only for events with amount/currency attributes) }] } } ``` ## getDeliveryFunnel Returns the delivery funnel for a single message, split by channel: audience → sent → errors → deliveries → opened, plus interactions for email broadcasts. Includes a breakdown of where each channel’s audience is lost at each stage. `POST` `https://api.pushwoosh.com/api/v2/statistics/messages/getDeliveryFunnel` ##### Headers | Name | Required | Description | | --------------- | -------- | -------------------------------------------------------------------------------------------- | | `Authorization` | Required | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/) from Pushwoosh Control Panel. | ##### Request body parameters | Name | Required | Type | Description | | -------------- | -------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- | | `message_code` | Yes | String | [Message code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#message-code) obtained from `/createMessage` API responses. | | `platforms` | No | Array of Integer | Optional [platform ID](https://docs.pushwoosh.com/developer/api-reference/messages-api/api-prerequisites/#platforms) filter. | There is no time-range parameter: the funnel has no time axis, so the server derives the window from the message’s own send and confirmation data (returned as `window_from`/`window_to`). ##### Example request ```json { "message_code": "A444-AAABBBCC-00112233", // required, message code obtained from /createMessage response "platforms": [1, 3, 7] // optional, list of platform codes } ``` ##### Response fields | Name | Type | Description | | ---------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`channels`** | **array** | **One entry per channel with data for this message. A channel the message never used is omitted — its absence means “no data”, not zero.** | | `channels[].channel` | string | `CHANNEL_MOBILE_PUSH` (iOS, OSX, Android, Amazon, Huawei), `CHANNEL_WEB_PUSH` (Safari, Chrome, Firefox), `CHANNEL_EMAIL`, or `CHANNEL_OTHER` (SMS, messengers, Wallet, Windows, and other platforms). | | `channels[].funnel` | array | Funnel stages for this channel, always in this order: `STAGE_AUDIENCE`, `STAGE_SENT`, `STAGE_ERRORS`, `STAGE_DELIVERIES`, `STAGE_OPENED`, and — for email broadcasts only, not transactional messages — `STAGE_INTERACTIONS`. | | `channels[].funnel[].stage` | string | Funnel stage name. | | `channels[].funnel[].count` | string | Total count for the stage. | | `channels[].funnel[].pieces` | array | Breakdown of `count` into categories. Empty on `STAGE_ERRORS`, which carries `errors` instead. A category with a zero count is omitted rather than returned as `0`. | | `channels[].funnel[].pieces[].kind` | string | How the piece relates to the stage total: `KIND_PASSED` (moved on to the next stage) or `KIND_REASON` (dropped out for this reason). Every piece is a summand — a stage’s pieces always add up to its `count`. | | `channels[].funnel[].pieces[].category` | string | Breakdown category, e.g. `INVALID_TOKEN`, `FREQUENCY_CAPPING`, `ELIGIBLE_AUDIENCE` — see the stage table below. | | `channels[].funnel[].pieces[].count` | string | Count for this category. | | `channels[].funnel[].pieces[].platforms` | array | Per-platform breakdown of this category: `{ "platform": , "count": "" }`. A platform with nothing to report is omitted, not returned as `0`. | | `channels[].funnel[].errors` | array | `STAGE_ERRORS` only, in place of `pieces`: one row per drop-out category (`category`, `count`, `platforms`) — same shape as a piece, minus `kind`. | | `channels[].funnel[].platforms` | array | Per-platform breakdown of the stage’s own `count`. | | `channels[].deliveries_form` | string | Which breakdown `STAGE_DELIVERIES` carries: `DELIVERIES_FORM_PER_DEVICE` (three rows, alert state known) or `DELIVERIES_FORM_BASIC` (two rows, alert state unknown). | | `channels[].basic_form_reason` | string | Set only when `deliveries_form` is `DELIVERIES_FORM_BASIC`: `BASIC_FORM_REASON_RETENTION` (message older than the row-level log retains), `BASIC_FORM_REASON_UNAVAILABLE` (no per-device data for this account), `BASIC_FORM_REASON_NO_DELIVERIES` (nothing accepted yet), or `BASIC_FORM_REASON_NOT_APPLICABLE` (this channel has no alert state — not a degradation). | | `channels[].confirmed_deliveries` | object | `{ "count": "", "platforms": [...] }` — unique devices that confirmed delivery, independent of `deliveries_form`. `confirmed_deliveries` is not clamped to `STAGE_DELIVERIES.count`, so it can drift slightly past that total; use `confirmed_deliveries` for a continuous delivery trend across messages of different ages. | | `window_from`, `window_to` | string (RFC 3339 date-time) | The time window the funnel was actually computed over, derived from the message’s own data. | | `funnel_state` | string | `FUNNEL_STATE_READY` (`channels` populated), `FUNNEL_STATE_NO_EVENTS` (nothing has happened for this message yet — `channels` is empty), or `FUNNEL_STATE_EXPIRED` (message older than 365 days, statistics no longer stored — `channels` is empty). | ##### Funnel stages | Stage | Applies to | `count` means | `pieces` / `errors` | | -------------------- | -------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `STAGE_AUDIENCE` | all channels | Taken into processing. | `KIND_PASSED` `ELIGIBLE_AUDIENCE`; `KIND_REASON`: `FREQUENCY_CAPPING`, `CONTROL_GROUP` (all channels), `UNSUBSCRIBED`, `BOUNCED`, `COMPLAINT`, `FILTERED_BY_CATEGORY` (email only) | | `STAGE_SENT` | all channels | Accepted by the gateway/provider (`ACCEPTED_BY_GATEWAY`). | none — the stage is entirely the accepted total; rejections show up under `STAGE_ERRORS` instead | | `STAGE_ERRORS` | all channels | Rejected before reaching the recipient. | `errors[]`, not `pieces`: `INTERNAL_ERROR`, `INVALID_TOKEN`, `NO_TOKEN`, `NO_DEVICE`, `PLATFORM_DISABLED`, `QUOTA_EXCEEDED`, `INVALID_CONTENT`, `INVALID_CONFIGURATION`, `PROVIDER_ERROR` (uncategorized) | | `STAGE_DELIVERIES` | all channels | Accepted sends to confirm — how many there were, not how many confirmed. | Per-device form: `KIND_PASSED` `DISPLAYABLE_CONFIRMED`; `KIND_REASON`: `DISPLAYABLE_NO_CONFIRMATION`, `ALERTS_DISABLED`. Basic form: `KIND_PASSED` `CONFIRMED_BY_DEVICE`; `KIND_REASON` `NO_CONFIRMATION` | | `STAGE_OPENED` | all channels | Unique devices/addresses that opened. | Email only, and only while the message is under 60 days old: `KIND_PASSED` `OPENED_BY_RECIPIENT`; `KIND_REASON`: `MACHINE_OPENS_ONLY` (automated opens, e.g. mailbox preview clients), `OPEN_TYPE_UNKNOWN`. Other channels, and email past 60 days: no `pieces`. | | `STAGE_INTERACTIONS` | email broadcasts only (not transactional messages) | What the recipient did with the email. | `KIND_PASSED` `CLICKED_ONLY`; `KIND_REASON`: `CLICKED_AND_UNSUBSCRIBED`, `CLICKED_AND_COMPLAINED`, `UNSUBSCRIBED_WITHOUT_CLICK`, `COMPLAINED_WITHOUT_CLICK` | ##### Response example ```json { "channels": [ { "channel": "CHANNEL_EMAIL", "funnel": [ { "stage": "STAGE_AUDIENCE", "count": "600000", "pieces": [ { "kind": "KIND_PASSED", "category": "ELIGIBLE_AUDIENCE", "count": "580000" }, { "kind": "KIND_REASON", "category": "UNSUBSCRIBED", "count": "14000" }, { "kind": "KIND_REASON", "category": "BOUNCED", "count": "6000" } ] }, { "stage": "STAGE_SENT", "count": "560000", "pieces": [] }, { "stage": "STAGE_ERRORS", "count": "20000", "errors": [ { "category": "INVALID_TOKEN", "count": "18000" }, { "category": "PROVIDER_ERROR", "count": "2000" } ] }, { "stage": "STAGE_DELIVERIES", "count": "560000", "pieces": [ { "kind": "KIND_PASSED", "category": "CONFIRMED_BY_DEVICE", "count": "540000" }, { "kind": "KIND_REASON", "category": "NO_CONFIRMATION", "count": "20000" } ] }, { "stage": "STAGE_OPENED", "count": "30514", "pieces": [ { "kind": "KIND_PASSED", "category": "OPENED_BY_RECIPIENT", "count": "26102" }, { "kind": "KIND_REASON", "category": "MACHINE_OPENS_ONLY", "count": "4412" } ] }, { "stage": "STAGE_INTERACTIONS", "count": "1980", "pieces": [ { "kind": "KIND_PASSED", "category": "CLICKED_ONLY", "count": "1820" }, { "kind": "KIND_REASON", "category": "UNSUBSCRIBED_WITHOUT_CLICK", "count": "140" }, { "kind": "KIND_REASON", "category": "CLICKED_AND_COMPLAINED", "count": "20" } ] } ], "deliveries_form": "DELIVERIES_FORM_BASIC", "basic_form_reason": "BASIC_FORM_REASON_NOT_APPLICABLE", "confirmed_deliveries": { "count": "540000" } }, { "channel": "CHANNEL_MOBILE_PUSH", "funnel": [ { "stage": "STAGE_DELIVERIES", "count": "168316", "pieces": [ { "kind": "KIND_PASSED", "category": "DISPLAYABLE_CONFIRMED", "count": "89570" }, { "kind": "KIND_REASON", "category": "DISPLAYABLE_NO_CONFIRMATION", "count": "78746" } ] }, { "stage": "STAGE_OPENED", "count": "30514", "pieces": [] } ], "deliveries_form": "DELIVERIES_FORM_PER_DEVICE", "confirmed_deliveries": { "count": "91240" } } ], "window_from": "2026-08-01T00:00:00Z", "window_to": "2026-08-04T00:00:00Z", "funnel_state": "FUNNEL_STATE_READY" } ``` Response codes and examples * 200: OK ```json { "channels": [], "funnel_state": "FUNNEL_STATE_NO_EVENTS" } ``` * 400: Bad Request ```json { "error": "message_code must be set" } ``` * 401: Unauthorized ```json { "error": "account not found" } ``` * 404: Not Found ```json { "error": "message not found" } ``` * 500: Internal Server Error Note Where a stage carries `pieces` (or, on `STAGE_ERRORS`, `errors`), they are disjoint and always add up to that stage’s `count`. Some stages have no breakdown at all — `STAGE_SENT` always, `STAGE_OPENED` outside email or past the 60-day window — and their `count` is just a total, with `pieces` returned empty. A stage with no data for a channel is omitted rather than returned empty. Note `confirmed_deliveries` is included for `CHANNEL_EMAIL` regardless of account settings. For other channels, it’s included only for accounts with delivery-statistics visibility enabled. ## getMessageLog Displays detailed information about the messages sent. `POST` `https://api.pushwoosh.com/api/v2/statistics/getMessageLog` ##### Headers | Name | Required | Description | | --------------- | -------- | -------------------------------------------------------------------------------------------- | | `Authorization` | Required | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/) from Pushwoosh Control Panel. | ##### Request body parameters | Name | Required | Type | Description | | ------------------ | ---------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `message_id` | No | Integer | Select messages events by Message ID obtained from message history. Example: `12345678900`. | | `message_code` | No | String | Select messages events by [Message code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#message-code) obtained from `/createMessage` API responses. Example: `"A444-AAABBBCC-00112233"`. | | `campaign_code` | No | String | Select messages events by [Campaign code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#campaign-code) specified in your message payload. Example: `"AAAAA-XXXXX"`. | | `hwid` | No | String or Array | Select messages events by [HWID (Hardware ID)](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) or an array of HWIDs. | | `date_from` | Required if `message_id`, `message_code`, or `campaign_code` is not provided | Datetime | Start date for filtering messages. Format: `"YYYY-MM-DD HH:MM:SS"`. Example: `"2000-01-25 00:00:00"`. | | `date_to` | Required if `message_id`, `message_code`, or `campaign_code` is not provided | Datetime | End date for filtering messages. Format: `"YYYY-MM-DD HH:MM:SS"`. Example: `"2000-01-26 00:00:00"`. | | `limit` | No | Integer | Maximum number of message events returned in a single response. Maximum value: `100000`. | | `pagination_token` | No | String | Pagination token obtained from a previous `/getMessageLog` response. Use it to retrieve additional results. | | `user_id` | No | String | Select messages events by a custom [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id). See `/registerUser` for more details. | | `application_code` | Yes | String | Select messages events by [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | `actions` | No | Array | Filter results by specific message actions. Possible values: `"sent"`, `"delivered"`, `"opened"`, `"inbox_delivered"`, `"inbox_read"`, `"inbox_opened"`, `"inbox_deleted"`. | | `platforms` | No | Array | Array of target platforms to filter results. Possible values: `"ios"`, `"android"`, `"osx"`, `"windows"`, `"amazon"`, `"safari"`, `"chrome"`, `"firefox"`, `"ie"`, `"email"`, `"huawei_android"`. | ##### Example request ```shell curl --location --request POST 'https://api.pushwoosh.com/api/v2/statistics/getMessageLog' \ --header 'Authorization: Key API_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "pagination_token": "PAGINATION_TOKEN_FROM_PREVIOUS_RESPONSE", // optional, token for pagination "limit": 1000, // optional, the max number of entries for a single response "application_code": "XXXXX-XXXXX", // Pushwoosh app code "message_code": "A444-AAABBBCC-00112233", // optional, message code obtained from /createMessaage request "message_id": 1234567890, // optional, message ID obtained from Pushwoosh Control Panel "campaign_code": "AAAAA-XXXXX", // optional, code of a campaign to get the log for "hwid": "aaazzzqqqqxxx", // optional, hardware ID of a specific device targeted with a message "user_id": "user_123", // optional, ID of a user targeted with the message "date_from": "2000-01-25 00:00:00", // optional, start of the stats period "date_to": "2000-02-10 23:59:59", // optional, end of the stats period "actions": ["opened", "inbox_opened"], // optional, used for results filtration. Possible values: "sent", "opened", "delivered", "inbox_delivered", "inbox_read", "inbox_opened", "inbox_deleted". The response will include all the messages with the specified action(s). "platforms": ["ios", "chrome"] // optional, used for results filtration. Possible values: "ios", "android", "osx", "windows", "amazon", "safari", "chrome", "firefox", "ie", "email", "huawei android" }' ``` Important One of the following fields is required:\ - *message_id*\ *- message_code*\ *- campaign_code*\ *- hwid*\ *- user_id*\ *- date_from* and *date_to* Consider applying various filtration params to get the most of your messages stats. Response codes and examples * 200: OK ```json { "pagination_token": "PAGINATION_TOKEN_FOR_NEXT_REQUEST", "data": [{ "timestamp": "2000-01-25T11:18:47Z", "application_code": "XXXXX-XXXXX", "message_id": 12345678900, "message_code": "A444-AAABBBCC-00112233", "campaign_code": "AAAAA-XXXXX", "hwid": "aaazzzqqqqxxx", "user_id": "user_123", "platform": "android", "action": "sent", "status": "success", "push_alerts_enabled": "true" }, { "timestamp": "2000-01-25T11:18:49Z", "application_code": "XXXXX-XXXXX", "message_id": 12345678900, "message_code": "A444-AAABBBCC-00112233", "campaign_code": "AAAAA-XXXXX", "hwid": "aaazzzqqqqxxx", "user_id": "user_123", "platform": "android", "action": "delivered", "push_alerts_enabled": "true" }, { "timestamp": "2000-01-25T11:19:23Z", "application_code": "XXXXX-XXXXX", "message_id": 12345678900, "message_code": "A444-AAABBBCC-00112233", "campaign_code": "AAAAA-XXXXX", "hwid": "aaazzzqqqqxxx", "user_id": "user_123", "platform": "android", "action": "opened", "push_alerts_enabled": "true" }] } ``` * 400: Bad Request ```json { "error": "exceeded the maximum date interval. Max interval: 30 days" } ``` * 401: Unauthorized ```json { "error": "account not found" } ``` * 500: Internal Server Error Note Data can be downloaded up to a maximum of 30 days from the current time. Tip For iOS, please make sure that you have added the Notification Service Extension to your project for tracking push delivery. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/ios-sdk/ios-message-delivery-tracking) ## Email statistics ### linksInteractions Displays statistics on link clicks in emails `POST` `https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractions` ##### Headers | Name | Required | Description | | --------------- | -------- | -------------------------------------------------------------------------------------------- | | `Authorization` | Yes | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/) from Pushwoosh Control Panel. | ##### Request body parameters | Name | Required | Type | Description | | -------------------- | ----------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `date_range` | No | Object | Defines the reporting period. Contains `date_from` and `date_to`. | | `filters` | Yes | Object | Email filters. | | `application` | Yes | String | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) (alternatively, specify `campaign`, `messages_ids`, or `message_codes`). | | `messages_codes` | Yes | Array | [Message codes](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#message-code) (alternatively, specify `application`, `campaign`, or `messages_ids`). | | `campaign` | Yes | String | [Campaign code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#campaign-code) (alternatively, specify `application`, `messages_ids`, or `message_codes`). | | `messages_ids` | Yes | Array | Message IDs (alternatively, specify `application`, `campaign`, or `message_codes`). | | `link_template` | Required if `application` or `campaign` is specified. | String | Filters email link interactions by keyword. Only links that include the specified text in their URL will be returned in the API response. For example, if your email contains links like `https://example.com/news` and `https://example.com/shop`, setting “link_template”: “shop” will return interactions for `https://example.com/shop` only. | | `email_content_code` | No | String | [Unique identifier for the email content](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#email-content-code). | | `params` | No | Object | Defines additional response options. Includes `with_full_links`, which adds a list of full links with statistics. | ##### Request example ```shell curl --location --request POST 'https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractions' \ --header 'Authorization: Api API_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "filters": { "date_range": { "date_from": "string", // Required format: 2000-01-01 "date_to": "string" // Required format: 2000-01-01 }, "campaign": "string", // Campaign code (you can specify application, messages_ids, or message_codes instead) "application": "string", // Application code (you can specify campaign, messages_ids, or message_codes instead) "messages_ids": [], // Message IDs (you can specify application, campaign, or message_codes instead) "messages_codes": [], // Message codes (you can specify application, campaign, or message_ids instead) "link_template": "string", // Link template (required if application or campaign is specified) "email_content_code": "string" // Unique identifier for the email content. }, "params": { "with_full_links": true // Specify whether to show detailed statistics. A list of full links with statistics will be passed in the full_links array. } }' ``` ##### Response codes and examples * 200: OK ```json { "items": [{ "template": "string", "link": "string", "title": "string", "clicks": 0, "full_links": [{ "full_link": "string", "clicks": 0 }] }] } ``` * 400: Bad Request ```json { "error": "exceeded the maximum date interval. Max interval: 30 days" } ``` * 401: Unauthorized ```json { "error": "account not found" } ``` * 500: Internal Server Error ### linksInteractionsDevices Shows users who clicked on links in emails `POST` `https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractionsDevices` ##### Headers | Name | Required | Description | | --------------- | -------- | ------------------------------------------------------------------------------------------------ | | `Authorization` | Yes | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/) from the Pushwoosh Control Panel. | ##### Request body parameters | Name | Required | Type | Description | | -------------------- | ----------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `date_range` | No | Object | Defines the reporting period. Contains `date_from` and `date_to`. | | `filters` | Yes | Object | Email filters. | | `application` | Yes | String | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) (alternatively, specify `campaign`, `messages_ids`, or `message_codes`). | | `messages_codes` | Yes | Array | [Message codes](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#message-code) (alternatively, specify `application`, `campaign`, or `messages_ids`). | | `campaign` | Yes | String | [Campaign code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#campaign-code) (alternatively, specify `application`, `messages_ids`, or `message_codes`). | | `messages_ids` | Yes | Array | Message IDs (alternatively, specify `application`, `campaign`, or `message_codes`). | | `link_template` | Required if `application` or `campaign` is specified. | String | Filters email link interactions by keyword. Only links that include the specified text in their URL will be returned in the API response. For example, if your email contains links like `https://example.com/news` and `https://example.com/shop`, setting “link_template”: “shop” will return interactions for `https://example.com/shop` only. | | `email_content_code` | No | String | [Unique identifier for the email content](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#email-content-code). | | `page` | No | Integer | Page number for pagination. | | `per_page` | No | Integer | Number of results per page (≤ 1000). | ##### Request example ```shell curl --location --request POST 'https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractionsDevices' \ --header 'Authorization: Api API_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "filters": { "date_range": { "date_from": "string", // Required format: 2000-01-01 "date_to": "string" // Required format: 2000-01-01 }, "campaign": "string", // Campaign code (you can specify application, messages_ids, or message_codes instead) "application": "string", // Application code (you can specify campaign, messages_ids, or message_codes instead) "messages_ids": [], // Message IDs (you can specify application, campaign, or message_codes instead) "messages_codes": [], // Message codes (you can specify application, campaign, or message_ids instead) "link_template": "string", // Link template (required if application or campaign is specified) "email_content_code": "string" // Unique identifier for the email content. }, "per_page": 100, "page": 0 }' ``` ##### Response codes and examples * 200: OK ```json { "total": 0, "items": [{ "timestamp": "string", "link": "string", "hwid": "string" }] } ``` * 400: Bad Request ```json { "error": "exceeded the maximum date interval. Max interval: 30 days" } ``` * 401: Unauthorized ```json { "error": "account not found" } ``` * 500: Internal Server Error ### bouncedEmails **POST** `https://api.pushwoosh.com/api/v2/statistics/emails/bouncedEmails` Provides data on email complaints, soft bounces, and hard bounces, including the date, email address, and reason for each bounce. ##### Authorization Authorization is handled via the API Access Token in the request header. ##### Request body parameters | Parameter Name | Type | Description | Required | | -------------- | ------ | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | `application` | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | Yes | | `message_code` | string | [Message code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#message-code). | Required if `date range` or `campaign` is not provided | | `campaign` | string | [Campaign code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#campaign-code). | Required if `message_code` or `date range` is not provided | | `date_from` | string | The start date for the data in the format `YYYY-MM-DDTHH:MM:SS.000Z` (ISO 8601 standard). | Required if `message_code` or `campaign` is not provided | | `date_to` | string | The end date for the data in the format `YYYY-MM-DDTHH:MM:SS.000Z` (ISO 8601 standard). | Required if `message_code` or `campaign` is not provided | | `per_page` | int | The number of rows per page, maximum 5000. | Yes | | `page` | int | The page number, starting from zero. | Yes | | `type` | string | The type of bounce: Complaint, Softbounce, Hardbounce. | No | ##### Request example ```json { "application": "XXXXX-XXXXX", // required. Pushwoosh app code "message_code": "XXXXX-XXXXXXXXX-XXXXXXXX", // required if campaign or date range is not provided. // Unique message identifier "campaign": "XXXXX-XXXXX", // required if message_code or date range is not provided. // Campaign code "date_from": "2024-07-20T00:00:00.000Z", // required if message_code or campaign is not provided. // Start date in ISO 8601 format "YYYY-MM-DDTHH:MM:SS.SSSZ" "date_to": "2024-07-20T00:00:00.000Z", // required if message_code or campaign is not provided. // End date in ISO 8601 format "YYYY-MM-DDTHH:MM:SS.SSSZ" "per_page": 1000, // required. Number of results per page, maximum 5000 "page": 5, // optional. Page number, starting from zero "type": "Softbounce" // optional. The type of bounce: Complaint, Softbounce, Hardbounce } ``` ##### Response fields | Field Name | Type | Description | | ---------------- | ------ | ------------------------------------------------------------ | | `total` | int | The total count of rows. | | `bounced_emails` | array | An array of bounced email details. | | ├── `email` | string | The email address that bounced. | | ├── `date` | string | The date of the bounce (format: `YYYY-MM-DDTHH:MM:SS.000Z`). | | ├── `reason` | string | The reason for the bounce. | | └── `type` | string | The type of bounce: Complaint, Softbounce, Hardbounce. | ##### Response example ```json { "total": 25, // Total count of rows. "bounced_emails": [{ "email": "example@example.com", // Email address that bounced "date": "2024-07-20T00:00:00.000Z", // Bounce date in ISO 8601 format "reason": "Invalid recipient address", // Reason for the bounce "type": "Hardbounce" // Type of bounce: Complaint, Softbounce, Hardbounce }] } ``` --- # Tags API **URL:** https://docs.pushwoosh.com/developer/api-reference/tags/ Create, delete, and list tags using API methods to manage custom attributes for users and devices. --- Note To set tag values for HWIDs and UserIDs, use the [/setTags](https://docs.pushwoosh.com/developer/api-reference/device-api#settags) method from Device API. ## addTag `POST` `https://api.pushwoosh.com/json/1.3/addTag` Creates a tag in your account. #### Request body | Name | Type | Description | | ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | tag* | object | Tag parameters. | | tag.name* | string | Tag name. | | tag.type* | integer | Tag type. See possible values below. | | tag.user_specific | boolean | When `true`, the tag value is stored at the user level and shared across all of a user’s devices when set by UserID. When `false` (default), the tag is device-level and set per HWID. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "result": true } } ``` Example ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "tag": { "name": "TAG_NAME", // required. "type": 1, // required. See possible values below "user_specific": false // optional. true = user-level tag (shared across all devices); false = device-level tag (default) } } } ``` **Possible tag value types:** * 1 - Integer * 2 - String * 3 - List * 4 - Date * 5 - Boolean * 6 - Decimal. Ex: 19.95 * 7 - Version. Ex: “1.0.0.0” ## deleteTag `POST` `https://api.pushwoosh.com/json/1.3/deleteTag` Completely removes a tag with all the associated information from the database. #### Request body | Name | Type | Description | | ---------- | ------ | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | tag* | object | Tag parameters. | | tag.name* | string | Name of a [tag](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#tag) to delete. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "result": true } } ``` Example ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "tag": { "name": "TAG_NAME" // required. Name of a tag to delete } } } ``` ## listTags `POST` `https://api.pushwoosh.com/json/1.3/listTags` Retrieves a list of tags on the account. #### Request body | Name | Type | Description | | ------ | ------ | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "tags": [{ "name":"Language", "type":2 }, { "name":"List tag", "type":3 }] } } ``` Example ```json { "request":{ "auth": "yxoPUlwqm…………pIyEX4H" // API access token from Pushwoosh Control Panel } } ``` **Tag types**: * 1 - Integer * 2 - String * 3 - List * 4 - Date * 5 - Boolean * 6 - Decimal. Ex: 19.95 * 7 - Version. Ex: “1.0.0.0” --- # Test devices API **URL:** https://docs.pushwoosh.com/developer/api-reference/test-devices/ Register and manage test devices using API methods for testing push notifications and app functionality. --- ## createTestDevice Registers a test device for the application. `POST` `https://api.pushwoosh.com/json/1.3/createTestDevice` #### Request Body | Name | Type | Description | | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | push_token | string | [Push token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#push-token) of the device. Required if `hwid` is not provided. | | hwid | string | [Hardware ID (HWID)](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) of the device. Required if `push_token` is not provided. | | device_type* | integer | [Device type](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#device-type). See possible values in `/registerDevice` method. | | name* | string | Test device name. | | description | string | Test device description. | * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` Example ```json { "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "push_token": "DEVICE_PUSH_TOKEN", // required if hwid is not provided. "device_type": 1, // required. Refer to /registerDevice for device types "name": "TEST_DEVICE_1", // required. Test device name "description": "android test device" // optional. Test device description } } ``` ## listTestDevices Returns all the test devices for the specific application. `POST` `https://api.pushwoosh.com/json/1.3/listTestDevices` #### Request Body | Name | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------ | | auth* | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "TestDevices": [{ "name": "iosDevice", "type": "1", "pushtoken": "token", "description": "ios device" }] } } ``` Example ```json { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel "application": "XXXXX-XXXXX" // required. Pushwoosh application code } } ``` For device types see [`/registerDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api/#registerdevice). --- # User centric API **URL:** https://docs.pushwoosh.com/developer/api-reference/user-centric-api/ Register users, link user IDs with devices, remove users, and track user events with User-centric API methods. --- ## registerUser `POST` `https://api.pushwoosh.com/json/1.3/registerUser` Associates external User ID with a specified device. #### Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | #### Request body | Name | Required | Type | Description | | ------------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------- | | userId | No | string | [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) to associate with a device. If empty, use hwid. | | application | Yes | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | hwid | Yes | string | [Pushwoosh HWID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) | | tz_offset | No | integer | Timezone offset in seconds for the device. | | device_type | No | integer | [Device type](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#device-type). See possible values in `/registerDevice`. | Can be used later in [`/createMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api/#createmessage) API call (the *users* parameter).\ You can call this function before you have the push token and before the [`/registerDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api/#registerdevice) call. #### Request example ```json { "request": { "userId": "user_3078a", // optional. If empty, use hwid "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "8f65b16df378e7a6bece9614e1530fb2", // required. Hardware device ID "tz_offset": -3600, // optional. Timezone offset in seconds "device_type": 3 // optional. Device type, see /registerDevice // for device types } } ``` #### Response example * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` Note For emails, call [`/registerEmailUser`](https://docs.pushwoosh.com/developer/api-reference/email-api/#registeremailuser). ## deleteUser `POST` `https://api.pushwoosh.com/api/v2/device-api/deleteUser` Deletes a user and all devices associated with the specified [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) within the application. The request is processed asynchronously, and the endpoint returns `200 OK` as soon as the delete request has been accepted for processing. #### Request headers | Name | Required | Value | Description | | ------------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | | Content-Type | Yes | application/json | | #### Request body | Name | Required | Type | Description | | ----------- | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | application | Yes | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | user_id | Yes | string | [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) to delete. All devices associated with this user in the specified application will be removed. | #### Request example ```json { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "user_id": "user_3078a" // required. User ID to delete } ``` #### Response example * 200 ```json { "status_code": 200, "status_message": "OK", "response": null } ``` ##### Status codes | HTTP Status code | status_code | Description | | ---------------- | ------------ | -------------------------------------------------- | | 200 | 200 | Delete request accepted | | 200 | 210 | Argument error. See status_message for more info. | | 400 | N/A | Malformed request string | | 401 | N/A | Missing or invalid Authorization token | | 500 | 500 | Internal error | ## postEvent `POST` `https://api.pushwoosh.com/json/1.3/postEvent` Triggers an event. #### Request headers | Name | Required | Value | Description | | ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Yes | Token `XXXX` | [API Device Token](https://docs.pushwoosh.com/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. | #### Request body | Name | Required | Type | Description | | ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | hwid | Yes | string | [Hardware device ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#hardware-id) used in a /registerDevice request. Can be used along with ‘userId’ to identify a user who has triggered an event. | | application | Yes | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | event | Yes | string | [Event name](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#event-name) exactly as created in Pushwoosh Control Panel. | | attributes | Yes | object | JSON object with the event attributes. Leave it empty if no attributes need to be passed. | | timestampUTC | No | integer | Timestamp in UTC. | | timestampCurrent | No | integer | Timestamp in local time. | | userId | Yes | string | [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) associated with a user who has triggered the event. Can be replaced by or used along with an HWID. | | device_type | No | integer | [See possible values](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#device-type) | The event’s name in the request must match the event name in Pushwoosh Control Panel. Note that “attributes” property may be empty (but not omitted) in case the event has no attributes. #### Request example ```json { "request":{ "hwid": "8f65b16df378e7a6bece9614e1530fb2", // required. Hardware device ID used in a /registerDevice API. // Can be used along with an userId to identify a // user who has triggered an event. "application": "XXXXX-XXXXX", // required. Pushwoosh application code "event": "activityCompleted", // required. Event name exactly as created in Pushwoosh Control Panel "attributes": { // required. Leave empty if no attributes need to be passed. "login": "facebook", "success": "yes", "internet": "wifi" }, "timestampUTC": 1435228403, // optional. Timestamp in UTC "timestampCurrent": 1435253603, // optional. Timestamp in local time "userId": "someuser@user.com", // required. A user id which is used for identification of // users on multiple devices. Can be replaced by // or used along with an HWID. "device_type": 1 // optional. } } ``` #### Response example * 200 ```json { "status_code": 200, "status_message": "OK", "response": { "code": "61BC9-84DD0" } } ``` #### Sending conversion events To report revenue directly instead of [mapping an existing event](https://docs.pushwoosh.com/product/audience-data-and-segmentation/events/conversion-events/), send `postEvent` with `PW_Conversion` as the event name and the transaction’s `value` and `currency` in `attributes`: ```json { "request":{ "hwid": "8f65b16df378e7a6bece9614e1530fb2", "application": "XXXXX-XXXXX", "event": "PW_Conversion", "attributes": { "value": 49.99, // required. Transaction amount "currency": "USD", // required. ISO 4217 currency code "transaction_id": "txn_8f21", // optional. Your own transaction reference "product_id": "prod_premium" // optional }, "userId": "someuser@user.com" } } ``` Note `transaction_id` is not used by Pushwoosh to deduplicate revenue — it’s stored as-is for your own reporting and reconciliation. If you report the same transaction more than once, each call is recorded separately. See [Conversion events](https://docs.pushwoosh.com/product/audience-data-and-segmentation/events/conversion-events/) for how canonical events and event mapping fit together. --- # WhatsApp API **URL:** https://docs.pushwoosh.com/developer/api-reference/whatsapp/ Send personalized and automated WhatsApp messages to your users, enhancing engagement and communication. --- /createWhatsAppMessage is deprecated New integrations should use [Messaging API v2](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/) — pass `platforms: ["WHATS_APP"]` to `Notify` and use the `whatsapp` block inside `payload.content.localized_content`. See the [migration guide](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/migration-from-v1/#from-createwhatsappmessage). Note Before sending WhatsApp messages, ensure that the WhatsApp platform is properly configured. [Learn more](https://docs.pushwoosh.com/product/first-steps/start-with-your-project/configure-platforms/whatsapp-configuration/) ## createWhatsAppMessage Deprecated Used to send WhatsApp messages to users `POST` `https://api.pushwoosh.com/json/1.3/createWhatsAppMessage` ### Request body | Name | Required | Type | Description | | :-------------- | :------- | :----- | :----------------------------------------------------------------------------------------------------------- | | auth* | Yes | string | [API access token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. | | application* | Yes | string | [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) | | notifications* | Yes | array | Content settings. JSON array of message parameters. See details below. | ### Notification parameters | Name | Required | Type | Description | | :---------------------- | :---------------------------------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | send_date* | Yes | string | Date and time to send the notification. Use format `YYYY-MM-DD HH:mm` or `'now'` to send immediately. | | content | Required if `content_id` is not provided. | string | Text content of the WhatsApp message. | | content_id | Required if `content` is not provided. | string | Identifier for a pre-approved WhatsApp template from your Meta account. | | devices* | Yes | array | Customer phone number (must be associated with a [User ID](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#user-id) using [`/registerDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api#registerdevice) and specified in the `hwid` parameter, or use `use_auto_registration`). Only one number can be specified here. | | use_auto_registration | No | boolean | If set to `true`, the phone number specified in the `devices` parameter will be automatically registered. | | content_variables | No | object | Content variables to customize the message content. Each placeholder will be replaced with corresponding dynamic values. | | button_url_variables | No | object | Dynamic URL variables for buttons. Each key represents a button index, and its value is the dynamic variable to replace in the button’s URL. **Note**: Button indexing starts at 0, with the first button as 0, the second as 1, and so on. | | header_variables | No | object | Variables for the header in a WhatsApp template message. Specify the `type` (e.g., `text`, `image`, `video`, `document`) and the corresponding value. **Example**: `"header_variables": {"image": "https://image-url.png"}` | | preset | No | string | WhatsApp Preset Code from your Control Panel. | | language | No | string | Language locale of the WhatsApp template (must match the locale in Meta WhatsApp template editor). Default: `"en_US"`. Example: `"en_GB"`. | Important *** Currently, each WhatsApp message must be sent in a separate request for each customer. ### Request example ```json { "request": { "application": "12XXX-67XXX", // required. Pushwoosh application code. "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel. "notifications": [{ "send_date": "now", // required. YYYY-MM-DD HH:mm OR "now". "content": "Hello! {{1}}", // required if content_id is not provided. Message text. "content_id": "hello_world", // required if content is not provided. WhatsApp template identifier. "devices": ["whatsapp:+1234567890"], // required. Customer WhatsApp phone number (must be associated // with a UserId using /registerDevice and specified in // the "hwid" parameter or use "use_auto_registration"). // Only one WhatsApp number can be specified here. "preset": "XXXXX-XXXXX", // optional. WhatsApp Preset Code from your Control Panel. "content_variables": { // optional. Content variables to customize the message content. "1": "John" }, "header_variables": { // optional. Variables for the WhatsApp message header. "image": "https://image-url.png" }, "language": "en_GB", // optional. Language locale for the WhatsApp template (must match the locale in Meta WhatsApp template editor). Default: "en_US". "use_auto_registration": true // optional. Automatically register WhatsApp number specified // in "devices" parameter. }] } } ``` ### Example: Sending a two-factor authentication code via WhatsApp ```json { "request": { "application":"APP_CODE", "auth":"AUTH_TOKEN", "notifications":[{ "send_date":"now", "content_id":"replace_with_your_meta_two_factor_template_name", "content_variables":{"1":"AUTH_CODE"}, "button_url_variables":{"0":"AUTH_CODE"}, "devices":["whatsapp:REPLACE_WITH_YOUR_PHONE_NO"] }] } } ``` ### Response example ```json { "status_code": 200, "status_message": "OK", "response": { "Messages": [ "9648-0B10EXXX-0D9F2XXX" ] } } ``` ### Error response ```json { "status_code": 210, "status_message": "Invalid devices list. \"devices\" must be an array.", "response": { "Messages": [] } } ``` --- # Developer changelog **URL:** https://docs.pushwoosh.com/developer/changelog/ Track monthly SDK releases, API updates, and platform changes to plan upgrades and keep your Pushwoosh integrations current. --- This page lists SDK releases, API updates, and platform changes that affect Pushwoosh integrations. ## August 2026 | Date | Component | Change | Details | | ------ | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Aug 13 | Statistics API | Breaking | `getDeliveryFunnel` response is now split per channel under `channels[]`. `STAGE_OPENS` is renamed `STAGE_OPENED`, `KIND_SUBSET`/`MACHINE_OPENS_AMPP` are removed, and a `STAGE_INTERACTIONS` stage (clicks, unsubscribes, complaints) is added for email broadcasts. The request no longer takes `timestamp_from`/`timestamp_to` — the window is derived from the message. [Learn more](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/#getdeliveryfunnel) | ## July 2026 | Date | Component | Change | Details | | ------ | ------------------------------------------------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Jul 31 | iOS SDK [v7.2.1](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.2.1) | Added | **PushwooshInApp** supports sheet (bottom card), carousel (swipeable slides), and banner (compact toast) in-app templates, in addition to modal, fullscreen, and stories. [Learn more](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.2.1) | | Jul 31 | Statistics API | Changed | `messages:list` now errors when `page × per_page` exceeds 100,000. Narrow the date range or use smaller pages. [Learn more](https://docs.pushwoosh.com/developer/api-reference/statistics-api/message-statistics-api/) | | Jul 29 | Messaging API v2 | Fixed | `Notify` no longer drops deeplink URLs that contain Liquid personalization (`{{ }}` / `{% %}`). [Learn more](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#openaction) | | Jul 28 | Messaging API v2 | Changed | Setting `days: 0` and `count: 0` together now disables frequency capping entirely, instead of returning an error. This makes it easier to turn off capping without extra logic on your end. Sending only one of `days` or `count` is still rejected. [Learn more](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/#frequencycapping) | | Jul 27 | Web Push SDK [v3.63.0](https://github.com/Pushwoosh/web-push-notifications/releases/tag/v3.63.0) | Added | Web popups can now be controlled entirely from your own code, with a new API to show, hide, and check popup state, plus events to react to visibility changes in real time. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/#webpopups-methods) | | Jul 24 | iOS SDK [v7.2.0](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.2.0) | Added | In-app messages can now render natively on device. Added **PushwooshInApp**, supporting modal, fullscreen, and stories templates via the `Pushwoosh.inApp` API. [Learn more](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.2.0) | | Jul 24 | Android SDK [v6.10.0](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.10.0) | Added | In-app messages can now render natively on device. Added **pushwoosh-inapp-ui**, supporting modal, fullscreen, and stories templates via the `PushwooshInAppUi` API. [Learn more](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.10.0) | | Jul 24 | Android SDK [v6.10.0](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.10.0) | Fixed | Fixed an issue that could prevent some in-app messages from being displayed. [Learn more](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.10.0) | | Jul 21 | User-centric API | Added | `postEvent` now supports `PW_Conversion` for revenue tracking. [Learn more](https://docs.pushwoosh.com/developer/api-reference/user-centric-api/#sending-conversion-events) | | Jul 15 | iOS SDK [v7.1.5](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.1.5) | Fixed | Fixed an issue with custom VoIP ringtone configuration, and made the SDK more resilient to malformed push payloads, tags, inbox data, and rich media content. [Learn more](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.1.5) | | Jul 15 | iOS SDK [v7.1.5](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.1.5) | Changed | Live Activity push tokens are now re-registered after an app relaunch, and duplicate token updates are skipped, for more reliable remote updates. [Learn more](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.1.5) | | Jul 14 | Liquid Templates | Added | The `connected_content` tag can now send request headers, so you can pass an authorization token when pulling dynamic content from a URL. [Learn more](https://docs.pushwoosh.com/developer/guides/personalization/liquid-templates/#connected-content) | | Jul 09 | Android SDK [v6.9.6](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.9.6) | Changed | Made the SDK more resilient to rare issues in in-app messages, Rich Media, and notification handling. Geolocation, geofencing, and Firebase push registration are also more reliable now on devices with an outdated or missing Google Play services library, along with tag updates and local notification storage handling. [Learn more](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.9.6) | | Jul 03 | Android SDK [v6.9.5](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.9.5) | Changed | Modal Rich Media animation duration can now be configured remotely via the in-app’s style settings, no app update required. Notifications, in-app messages, and Rich Media also got a stability pass this release. [Learn more](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.9.5) | | Jul 03 | iOS SDK [v7.1.4](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.1.4) | Added | Live Activities can now be scheduled to start at a future date and cancelled by `activityId`. Modal Rich Media now supports fade and no-animation transitions, with a configurable animation duration. [Learn more](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.1.4) | | Jul 03 | iOS SDK [v7.1.4](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.1.4) | Fixed | Fixed the modal Rich Media auto-close timer, which previously only worked on the first presentation, along with a resource cleanup issue after a modal Rich Media was dismissed. [Learn more](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.1.4) | | Jul 01 | Messaging API v2 | Added | `Notify` now supports Viber as a channel via the `viber` payload block. [Learn more](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#viber-viber) | ## June 2026 | Date | Component | Change | Details | | ------ | ------------------------------------------------------------------------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Jun 26 | Messaging API v2 | Added | Send Android Live Updates by adding a `live_update` object (`OPERATION_START`/`OPERATION_UPDATE`/`OPERATION_END`, shared `live_update.id`) to the `android` block of a transactional `Notify`. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/android-sdk/live-updates/) | | Jun 25 | iOS SDK [v7.1.3](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.1.3) | Added | Added `handleWillPresentNotification()` and `handleNotificationResponse()` for apps that own the `UNUserNotificationCenter` delegate, plus a startup integration checker that prints config diagnostics. [Learn more](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.1.3) | | Jun 25 | Android SDK [v6.9.4](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.9.4) | Changed | Modal in-app messages can now be presented without a transition animation. [Learn more](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.9.4) | | Jun 24 | Messaging API v2 | Added | `Notify` can now build SMS from a saved preset: set payload-level `sms_preset` instead of inlining `sms.body` per locale (an inline `sms.body` still overrides the preset for that locale). [Learn more](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/) | | Jun 24 | Android SDK [v6.9.3](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.9.3) | Fixed | Fixed modal Rich Media crashes on background transitions and when opening external links. Core and WebKit now ship as transitive dependencies. Supersedes the withdrawn 6.9.2. [Learn more](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.9.3) | | Jun 19 | Google Wallet API | Added | Issue and update Google Wallet passes from your backend. Changes sync to every device that saved the pass. [Learn more](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/) | | Jun 18 | iOS SDK [v7.1.2](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.1.2) | Added | PushwooshInboxKit now supports rich card types (carousel, video, and Apple Wallet) selected per message via `displayType`, with delegate callbacks for wallet-pass actions. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-inboxkit-ios/) | | Jun 18 | Customer Journey API | Added | New REST/JSON Customer Journey API to create, update, and manage journeys, trigger API entries, and read journey statistics (base `https://journey.pushwoosh.com`). [Learn more](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/) | | Jun 16 | Android SDK [v6.9.1](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.9.1) | Added | Added `getSubscriptionAccountId()` for Google Play Billing subscription attribution. Firebase Messaging now ships as a transitive dependency. Live Updates progress bar can be hidden for status-only updates. [Learn more](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.9.1) | | Jun 16 | Web Push SDK [v3.59.0](https://github.com/Pushwoosh/web-push-notifications/releases/tag/v3.59.0) | Added | Embed web popups from code: export `WebPopupsWidget` from the SDK package. [Learn more](https://github.com/Pushwoosh/web-push-notifications/releases/tag/v3.59.0) | | Jun 15 | Messaging API v2 | Added | Added the `Cancel` method (`POST /messaging/v2/cancel`) to cancel a pending, waiting, or processing message by `message_code`. [Learn more](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/cancel/) | | Jun 15 | iOS SDK [v7.1.1](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.1.1) | Added | Added `Pushwoosh.configure.pushPrimer`, a customizable soft opt-in dialog shown before the iOS system permission prompt. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/ios-sdk/ios-push-primer/) | | Jun 15 | iOS SDK [v7.1.0](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.1.0) | Added | Added `PushwooshNotificationServiceExtension`, a drop-in base class for Notification Service Extensions. [Learn more](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.1.0) | | Jun 15 | iOS SDK [v7.1.0](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.1.0) | Deprecated | `PWNotificationExtensionManager` is deprecated in favor of subclassing `PushwooshNotificationServiceExtension`. [Learn more](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.1.0) | | Jun 11 | Messaging API v2 | Added | Added `use_latest_user_device` to NotifyTransactional: when targeting `users`, deliver only to each user’s most recently active device. [Learn more](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) | | Jun 11 | Customer Journey Statistics API | Changed | In-app journey elements now return `pointStat` metrics `shows`, `interactions`, and `skipped` instead of `sent`/`opened`/`conversion`. [Learn more](https://docs.pushwoosh.com/developer/api-reference/customer-journey-api/statistics/) | | Jun 08 | iOS SDK [v7.0.46](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.0.46) | Added | Added the `PushwooshNotificationUI` module: a drop-in full-screen “stories” experience for expanded push notifications, rendered by subclassing `PushwooshStoriesViewController` in a Notification Content Extension. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/ios-sdk/ios-push-stories/) | | Jun 08 | iOS SDK [v7.0.46](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.0.46) | Fixed | Fixed App Store upload rejections (error 409), a notification service extension hang with App Groups, and a crash on malformed badge values. [Learn more](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.0.46) | | Jun 02 | Android SDK [v6.9.0](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.9.0) | Added | Added the `pushwoosh-liveupdates` module for ongoing, progress-style notifications on Android 16 (API 36+), for use cases like orders, rides, and deliveries. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/android-sdk/live-updates/) | | Jun 02 | Apple Wallet PassKit API | Added | Added Apple Wallet passes as a channel, with a PassKit API to issue and update passes. Updates sync to every device that added the pass. [Learn more](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/) | | Jun 01 | Tags API | Added | Added email system tags for email segmentation: `Last Email Open Message Code`, `Last Email Click Message Code`, `Last Email Confirm`, `Bounced Email`, and `Unsubscribed Emails`. [Learn more](https://docs.pushwoosh.com/developer/guides/audience-and-segmentation/tags/) | ## May 2026 | Date | Component | Change | Details | | ------ | ------------------------------------------------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | May 26 | Messaging API v2 | Added | `Notify` now supports SMS as a first-class channel. [Learn more](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) | | May 22 | Web Push SDK [v3.57.0](https://github.com/Pushwoosh/web-push-notifications/releases/tag/v3.57.0) | Added | Added `api.setLanguage(...)` to override device locale. It takes priority over `initParams` and `navigator.language`. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/) | | May 22 | Web Push SDK [v3.57.0](https://github.com/Pushwoosh/web-push-notifications/releases/tag/v3.57.0) | Added | Added support for the `webPopups` widget option in the SDK `init` params. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/#web-popups) | | May 22 | SMTP gateway | Added | Added SMTP submission endpoint `smtp.pushwoosh.com:587` (STARTTLS + AUTH PLAIN). Messages are forwarded to Messaging API v2 as transactional email. [Learn more](https://docs.pushwoosh.com/developer/api-reference/smtp-gateway/) | | May 21 | Android SDK [v6.8.1](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.8.1) | Changed | Improved session, idle, and exit-intent tracking accuracy. `setLogLevel()` now keeps the previous level and logs an error instead of throwing on an unrecognized value. [Learn more](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.8.1) | | May 18 | iOS SDK [v7.0.43](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.0.43) | Removed | Legacy `PushwooshInboxUI` was removed from build and release pipelines. Migrate to PushwooshInboxKit. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-inboxkit-ios/) | | May 18 | iOS SDK [v7.0.43](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.0.43) | Changed | Application codes containing `.` are now explicitly rejected. This format has long been deprecated. Contact Pushwoosh Support if you still use one. [Learn more](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.0.43) | | May 18 | iOS SDK [v7.0.43](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.0.43) | Fixed | InboxKit refresh now runs only on real background transitions to prevent extra POST requests | | May 14 | Android SDK [v6.8.0](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/tag/6.8.0) | Added | Added `setAdvertisingId()` for passing GAID to Pushwoosh for Meta Ads MADID matching. Requires user consent and manual integration in your app. [Learn more](https://docs.pushwoosh.com/product/integrations/meta-ads-integration/) | | May 13 | iOS SDK [v7.0.41](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.0.41) | Added | Added `setAdvertisingId()` for passing IDFA to Pushwoosh for Meta Ads MADID matching. Requires ATT consent and manual integration in your app. [Learn more](https://docs.pushwoosh.com/product/integrations/meta-ads-integration/) | | May 07 | iOS SDK [v7.0.40](https://github.com/Pushwoosh/pushwoosh-ios-sdk/releases/tag/7.0.40) | Added | Added PushwooshInboxKit with banner, captioned, and classic card layouts, inline CTA buttons, and swipe-to-delete. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-inboxkit-ios/) | | May 04 | Tags API | Removed | Removed `application_specific` field from Tags API responses. [Learn more](https://docs.pushwoosh.com/developer/api-reference/tags/) | --- # Set a custom User ID and link it to multiple devices **URL:** https://docs.pushwoosh.com/developer/first-steps/collecting-user-ids/ Learn how to set and manage custom User IDs in Pushwoosh to link multiple devices and contact methods under a single user profile for accurate billing and consistent messaging. --- To enable seamless, personalized communication across all platforms and devices, it is essential to assign a custom User ID to each user. ## What is a User ID? User ID is a unique identifier assigned to each user. A single User ID can be linked to multiple devices, where each contact method (mobile app, email address, phone number) is [treated as a separate device](https://docs.pushwoosh.com/product/pushwoosh-knowledge-hub/omnichannel-campaigns/#understanding-how-pushwoosh-handles-devices). Linking all devices (contact methods) under one User ID allows you to reach users across channels and coordinate messaging in [omnichannel campaigns](https://docs.pushwoosh.com/product/pushwoosh-knowledge-hub/omnichannel-campaigns/). Note Each user can have up to **20 devices** linked to their User ID. If a new device is registered beyond this limit, the oldest inactive device is automatically removed. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-knowledge-hub/users-userids/#device-limit-per-user) > For a detailed explanation of how User IDs work and how they relate to devices, see [this guide](https://docs.pushwoosh.com/developer/pushwoosh-knowledge-hub/users-userids/). ## Why you need to set a custom User ID By default, when your app is first launched, Pushwoosh creates a User ID equal to the device’s Hardware ID (HWID). This means each device is treated as a separate user. So if one person uses more than one device, like a phone and a tablet, Pushwoosh sees them as two separate users, and their data won’t be connected. If you want Pushwoosh to recognize multiple devices as belonging to the same user, you need to set a custom User ID and assign it to all of that user’s devices. Doing so links all devices and contact methods under a single user profile, unlocking several important benefits: ### Accurate user counts for billing Pushwoosh charges based on the number of unique users in your database. > [Learn more about Pushwoosh pricing](https://pushwoosh.com/pricing) If you don’t set a custom User ID, each device counts as a separate user, even if they belong to the same person. For example, if one user uses both a mobile phone and a tablet, they may be counted as two users. ### Consistent messaging across channels For a unified experience across push notifications, email, SMS, in-app, WhatsApp, and other channels, all user data must be linked under a single User ID. By setting a custom User ID, you ensure that Pushwoosh recognizes all contact methods (devices, emails, phone numbers) as belonging to the same user, which is essential for consistent and personalized omnichannel campaigns. > Learn more about [Omnichannel campaigns](https://docs.pushwoosh.com/product/pushwoosh-knowledge-hub/omnichannel-campaigns/) ### Persistent user profiles A custom User ID allows Pushwoosh to maintain a complete, unified profile for each user. This profile includes: * All devices and contact info linked to the same user * Tags * Event history and campaign participation * Messages sent and opened You can view and manage this data in [User Explorer](https://docs.pushwoosh.com/product/audience-data-and-segmentation/user-explorer/), helping you deliver more accurate targeting and better personalization. ## How to assign and manage User IDs Pushwoosh offers several methods to assign and manage User IDs: ### setUserID SDK method By default, when an app with Pushwoosh SDK is launched for the first time, it sets a device HWID as a User ID. However, you can set a custom user ID at various points depending on the app’s design and user flow. For this, use the setUserId method provided by the Pushwoosh SDK. Here are some key moments when you can set or update a custom User ID: * When the user registers in the app * When the user logs in * When the user makes a purchase or subscription * When the user interacts with specific features, etc. **iOS example** `[[Pushwoosh sharedInstance] setUserId:@"userId"];` **Android example** `Pushwoosh.getInstance().setUserId("testUser");` **Web example** `api.registerUser('user123');` ### Managing User IDs during login and logout When a user logs out, it’s recommended to reset their User ID to a default value using another `setUserId` call. When the user logs in again, update the User ID to the custom value specific to that user. If the User ID changes (e.g., if one user logs out and another user logs in), call `setUserId` to update the User ID associated with that device. This ensures that the correct User ID is always linked to the device, allowing personalized notifications to be sent to the appropriate user. ### registerEmail or registerEmailUser API method Use the [registerEmail](https://docs.pushwoosh.com/developer/api-reference/email-api#registeremail) or [registerEmailUser](https://docs.pushwoosh.com/developer/api-reference/email-api#registeremailuser) API method to associate an external User ID with a specified email address. Please note that [registerEmailUser](https://docs.pushwoosh.com/developer/api-reference/email-api#registeremailuser) does not register an email address in your user base; it should be used only for assigning user IDs to email addresses that have been registered already by registerEmail request. ### registerDevice API method While primarily used to register a new device in Pushwoosh, this method can also set a User ID at the time of device registration. If you pass a custom User ID in this call (for example, “userId”: “Alex”), it will be associated with the device. If no User ID is provided, the device will be associated with an anonymous User ID equal to the hardware ID (HWID) To associate customer phone numbers with **UserId** using the [**/registerDevice**](https://docs.pushwoosh.com/developer/api-reference/device-api/#registerdevice) method, please specify the phone number in the “hwid” parameter. ### registerUser API method This API method allows you to associate an external User ID with a specified device or transfer a device between users while retaining device tags, for example when a user logs out and a new user logs in. This method can be used before the device is registered or before obtaining the push token, for example, when you need to pre-register a user in Pushwoosh. [Learn more](https://docs.pushwoosh.com/developer/api-reference/user-centric-api#registeruser) --- # Amazon Device Messaging configuration **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/amazon-configuration/ Configure the Amazon platform in Pushwoosh using Amazon Device Messaging (ADM) credentials including Client ID and Client Secret. --- To send push notifications to Amazon devices, configure the Amazon platform in Pushwoosh with your ADM OAuth credentials. ## Get Client ID and Client Secret from Amazon 1. Sign in to the [Amazon Developer Console](https://developer.amazon.com/dashboard) and open **My Apps**. 2. Select your app (or create one) and go to **App Services**. 3. Under **Device Messaging**, select your security profile or create a new one. 4. Click **View Security Profile**, then open the **Web Settings** tab. 5. Copy **Client ID** and click **Show Secret** to reveal **Client Secret**. Keep credentials secure Do not share your Client Secret. Store it securely and use it only in the Pushwoosh configuration form. For details on security profiles and API keys for your app, see [Obtain credentials (Amazon Device Messaging)](https://developer.amazon.com/docs/adm/obtain-credentials.html). ## Configure Amazon in your Pushwoosh project 1. In your Pushwoosh project, go to **Configure Platforms** and click **Connect** next to **Amazon**. ![Configure Platforms section with Connect button next to Amazon](https://docs.pushwoosh.com/configure-project-amazon-configuration-1.webp) 2. In the **Amazon Device Messaging** form, enter your credentials: * **CLIENT ID:** paste the Client ID from Amazon Developer Console. * **CLIENT SECRET:** paste the Client Secret from Amazon Developer Console. * **FRAMEWORK:** select **None**, **Native**, **Unity**, **Adobe AIR**, or **React Native** depending on how you integrate the SDK. ![Amazon Device Messaging form in Pushwoosh showing CLIENT ID, CLIENT SECRET, FRAMEWORK dropdown, and Apply button](https://docs.pushwoosh.com/configure-project-amazon-configuration-2.webp) 3. Click **Apply**. To integrate the Pushwoosh SDK into your Amazon app: [Amazon integration ](https://docs.pushwoosh.com/developer/pushwoosh-sdk/android-sdk/amazon/) --- # Android configuration options **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/android-configuration/ Configure Android push messaging with Firebase and set up Google Wallet passes for your Pushwoosh application. --- This section provides step-by-step instructions for configuring your Android application in Pushwoosh, including Firebase push messaging and Google Wallet passes. ## Android Firebase configuration Set up Firebase Cloud Messaging credentials so Pushwoosh can deliver push notifications to your Android app. [Learn more ](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/android-configuration/android-firebase-configuration/) ## Google Wallet pass configuration for Android Add your Google Pay & Wallet Console Issuer ID and a Google Cloud service account key so Pushwoosh can issue and update Google Wallet passes for your app. [Learn more ](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/) --- # Android Firebase configuration **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/android-configuration/android-firebase-configuration/ Follow the steps below to set up an Android platform in Pushwoosh Control Panel using Firebase configuration. --- ## Get the Firebase **API key** 1. Create a [**Firebase project**](https://firebase.google.com/docs/cloud-messaging/android/client#create_a_firebase_project). 2. Open your [**Firebase Console**](https://console.firebase.google.com/) and choose the project you created. ![Choosing a project in the Firebase Console](https://docs.pushwoosh.com/configure-project-configure-android-platform-1.webp) 3. Go to **Your Project** > **Project settings.** ![Project settings](https://docs.pushwoosh.com/configure-project-configure-android-platform-2.webp) 4. In **Service accounts** tab, press **Generate new private key:** ![Generating a new private key](https://docs.pushwoosh.com/configure-project-configure-android-platform-3.webp) 5. In the window opened, press **Generate key**. The JSON file will be downloaded. ![Generating key](https://docs.pushwoosh.com/configure-project-configure-android-platform-4.webp) 6. Please verify that the API is enabled. If not, please enable it. Caution Make sure that you enabled FCM send API that provides a cross-platform messaging solution to reliably deliver messages at no cost. 1. Visit 2. Select your project. 3. Press **Enable.** ![API enabled](https://docs.pushwoosh.com/configure-project-configure-android-platform-5.webp) ## Configure Android in your Pushwoosh project 7. Go to your Pushwoosh project. Open **Settings → Configure platforms** and click **Connect** in the **Android** row. ![Configure platforms page with Android row showing Connect among platform action buttons](https://docs.pushwoosh.com/configure-project-configure-android-platform-6.webp) 8. In **IMPORT FCM SERVICE ACCOUNT KEY**, upload the JSON private key you downloaded from your Firebase project settings. ![Android Configuration form with Import FCM service account key field and Apply button](https://docs.pushwoosh.com/configure-project-configure-android-platform-7.webp) 9. Click **Apply**. 10. Now you can move on to [integrating the Pushwoosh SDK](https://docs.pushwoosh.com/developer/pushwoosh-sdk/android-sdk/firebase-integration/integrate-pushwoosh-android-sdk/) --- # Google Wallet pass configuration for Android **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/ Add Issuer ID and a Google Cloud service account key in Configure platforms so Pushwoosh can issue Google Wallet passes. --- Configure your **Google Pay & Wallet Console Issuer ID** and a **Google Cloud service account key** so Pushwoosh can issue and update [Google Wallet passes](https://docs.pushwoosh.com/product/messaging-channels/google-wallet-passes/) for your app. This is a one-time setup. Once a valid configuration is in place, the Google Wallet [pass builder](https://docs.pushwoosh.com/product/messaging-channels/google-wallet-passes/pass-builder/) unlocks for the application. ## Create the issuer account Important The configuration is stored **per application**. Configure it for each application that issues passes. **Sign up for an issuer account.** In the [Google Pay & Wallet Console](https://pay.google.com/business/console), complete the Google Wallet API onboarding to get your **Issuer ID** (a numeric value). You can start in demo mode and request production access later. ![Google Pay and Wallet Console screen showing the numeric Issuer ID after Google Wallet API onboarding](https://docs.pushwoosh.com/android-google-wallet-configuration-1.webp) ## Create the service account key 1. **Create (or pick) a Google Cloud project** and enable the **Google Wallet API** for it. Use the same Google Cloud project that is linked to your issuer in the Google Pay & Wallet Console during onboarding. See [Google’s getting started guide](https://developers.google.com/wallet/generic/getting-started/onboarding-guide). 2. **Create a service account** in that project and download its **JSON key**. Follow [Google’s guide on generating REST API credentials](https://developers.google.com/wallet/generic/getting-started/auth/rest). The key file must be of type `service_account` and contain a `client_email` and a PEM private key. 3. **Copy the service account’s email address** from the JSON key (the `client_email` field). You’ll need it in the next step. ### Grant the service account access In the [Google Pay & Wallet Console](https://pay.google.com/business/console): 1. Open **Users** in the left sidebar. 2. Click **Invite a user**. 3. Paste the service account’s email address (from step 3 above). 4. Set **Access level** to **Developer**. 5. Click **Invite**. Without this step, Pushwoosh cannot create or update Google Wallet passes. ## Configure Google Wallet in the Control Panel 1. Go to **Settings → Configure platforms** in the Control Panel. 2. Under **MOBILE PLATFORMS**, find **Android** and open the **Google Wallet** setup. ![Configure platforms page with Android row showing Google Wallet setup among platform action buttons](https://docs.pushwoosh.com/android-google-wallet-configuration-3.webp) 3. In **Issuer ID**, enter the numeric Issuer ID from the Google Pay & Wallet Console. 4. Next to **Service account key (JSON)**, click **Browse…** and select your service account `.json` key file. ![Pushwoosh Configure platforms Google Wallet form with Issuer ID, service account key import, and Apply button](https://docs.pushwoosh.com/android-google-wallet-configuration-2.webp) 5. Click **Apply**. Keep the service account valid If you remove the service account in Google Cloud, revoke its key, or remove its access in the Wallet Console, Pushwoosh can no longer create or update passes. Creating and updating passes will fail until you add a valid key again. ## Next steps Once you click **Apply**, you can design passes in the pass builder. [Getting started with Google Wallet passes ](https://docs.pushwoosh.com/product/messaging-channels/google-wallet-passes/) ## Manage passes via API Use the Google Wallet API to create passes, issue save links, and send them to users. [Google Wallet API ](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/) --- # How to configure platforms **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/configure-project/ Configure platforms in Pushwoosh for iOS, Android, Web, Email, WhatsApp, LINE, Kakao, Telegram, Viber, SMS, Apple Wallet, and Google Wallet passes. --- To enable Pushwoosh to send messages to your users, it’s essential to configure the platforms you plan to work with. To start configuring a platform, go to **Settings → Configure platforms** and click **Connect** next to the required platform. ![Configure platforms page in Pushwoosh showing platform list and Connect buttons](https://docs.pushwoosh.com/configure-platforms.webp) ## Mobile[](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/configure-project/#mobile) ### iOS configuration * [iOS certificate-based configuration](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-platform-configuration/) * [iOS token-based configuration](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-token-based-configuration/) * [Apple Wallet pass configuration for iOS](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-wallet-pass-configuration/) ### Android configuration * [Android Firebase configuration](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/android-configuration/android-firebase-configuration/) * [Google Wallet pass configuration for Android](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/) ### Amazon configuration * [Amazon Device Messaging configuration](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/amazon-configuration/) ### Huawei configuration * [Huawei configuration](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/huawei-configuration/) ## Web[](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/configure-project/#web) * [Web push configuration](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/web-push-configuration/) ## Desktop platforms * [macOS configuration](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/macos-configuration/) * [Windows configuration](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/windows-configuration/) ## Email[](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/configure-project/#email) * [Email configuration](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/email-verification/) ## WhatsApp Add your WhatsApp Business Account credentials directly in the Control Panel to enable WhatsApp messaging. * [WhatsApp configuration](https://docs.pushwoosh.com/product/first-steps/start-with-your-project/configure-platforms/whatsapp-configuration/) ## LINE To enable message delivery through the LINE messaging app, configure the LINE platform in your project settings. * [LINE configuration](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/line-configuration/) ## Kakao To enable message delivery through KakaoTalk, configure the Kakao platform in your project settings. * [Kakao configuration](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/kakao-configuration/) ## Telegram Connect your Telegram bot to Pushwoosh to run Telegram as part of your omnichannel journeys. * [Telegram configuration](https://docs.pushwoosh.com/product/first-steps/start-with-your-project/configure-platforms/telegram-configuration/) ## Viber Connect your Rakuten Viber account to send Viber messages as part of your omnichannel campaigns. * [Viber configuration](https://docs.pushwoosh.com/product/first-steps/start-with-your-project/configure-platforms/viber-configuration/) ## SMS Connect your own SMS provider directly in the Control Panel to enable SMS messaging. Once configured, you can send SMS in one-time campaigns and Customer Journeys. * [SMS configuration](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/sms-configuration/) * [SMS provider webhooks](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/sms-configuration/sms-provider-webhooks/) ## Edit project Click **Edit project** at the top right of the **Configure platforms** page to open project settings. There you can change the project title and icon, connect your bit.ly account to shorten links in push notifications, and manage email notification preferences. Tip **Connect your bit.ly account to shorten links** Push payload size is limited, so the best practice is to shorten the links you use in your push notifications. Using your own bit.ly account assures all your messages are shortened and sent properly as you control the shortener limits yourself. In the **Edit project** dialog, check **I want to add my bit.ly account** and enter your bit.ly access token in the **ACCESS TOKEN** field. [Learn more about editing your project](https://docs.pushwoosh.com/product/account-management-and-security/managing-projects/#editing-projects) ## Hide unconfigured platforms At the bottom of the **Configure platforms** page, use **Hide unconfigured platforms** to show only the platforms you have already set up. This keeps the list short when you work with a subset of channels. ## Delete project To delete a project, go to **Settings → Configure platforms**, open the three-dot menu at the top right of the page (next to **Edit project**), and select **Delete project**. Caution Deleting a project is permanent. The project and all its user base will be removed from your account. This action cannot be undone. For more on project management, see [Manage projects](https://docs.pushwoosh.com/product/account-management-and-security/managing-projects/#deleting-projects). --- # Email configuration **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/email-verification/ Step-by-step setup for email configuration, including DKIM, SPF, and DMARC records and sender identity settings. --- Note Please note that platform configuration is project-specific. Configure the Email platform for each project you want to use for sending emails. Verified emails and domains are available for all projects in your account. To start sending emails through Pushwoosh, you’ll need to complete a series of setup steps to verify your account, configure sender details, and authenticate your domain. This process ensures secure, compliant email delivery and enables accurate tracking of engagement metrics. ## Verify your account Before you start sending emails through Pushwoosh, you need to verify your account. This is an important step to guarantee the reliable and secure delivery of your emails. Verification helps prevent misuse of the platform for spam or malicious activities and ensures compliance with regulations. Follow these steps to complete the verification process: 1. Navigate to **Settings > Configure platforms**. 2. Locate Emails and click **Connect**. ![Emails direct channel in Pushwoosh Control Panel with Connect button](https://docs.pushwoosh.com/configure-project-email-verification-1.webp) 3. In the form that appears, provide the URL of your company’s website in the Your company website URL field (e.g., ). 4. In the **Primary technical contact** field, enter the email address of the person responsible for managing the technical aspects of your integration. This contact will be used for any technical-related inquiries or issues. 5. In the **Tell us about how you’ll be using Pushwoosh** field, provide details on how you intend to use Pushwoosh for your email campaigns. Include information such as: * The types of messages you plan to send (e.g., newsletters, promotional offers, etc). * How your subscribers sign up to receive these messages (e.g., website form, mobile app registration). ![Email verification form with company website URL, primary technical contact, and usage details fields](https://docs.pushwoosh.com/configure-project-email-verification-2.webp) Once all the information is filled out, click the **Verify my account** button to submit your request. Pushwoosh will review your details, and get back to you as soon as possible. After your account is verified, you will receive a confirmation email. You can then proceed to configure your email sender settings. For this, go to **Settings**, select **Configure Platforms**, and click **Continue Configuration** next to the Email platform. ![Continue Configuration button next to Email platform in Pushwoosh Control Panel](https://docs.pushwoosh.com/configure-project-email-verification-3.webp) ## Configure sender details ### Add a domain To send emails with Pushwoosh, add and verify a domain. In the **Domain** field, enter the domain you wish to use for sending emails (e.g., yourcompany.com). ![Domain field for adding a sender domain in Pushwoosh email configuration](https://docs.pushwoosh.com/configure-project-email-verification-4.webp) **Important:** This domain must be verified via DNS in the next step before it can be used in your email campaigns. Note You will see the remaining number of domains you can add at the top of the screen. To increase this limit, please [contact our support team](https://help.pushwoosh.com/hc/en-us/) ### Add default sender details #### From address Set up a default sender name and email address that will appear in recipients’ inboxes. This helps users recognize the sender and builds trust. * **Name**: Enter the sender’s name (e.g., John). * **Email**: Enter the sender’s email address before the ”@” symbol (e.g., for **, enter *marketing*) **Note**: These default sender details will be used automatically in campaigns unless you specify different sender details for an individual campaign. ![Default sender details form with From address name and email fields in Pushwoosh](https://docs.pushwoosh.com/configure-project-email-verification-5.webp) Select **Use this as reply-to address to track replies** checkbox if you want replies from recipients to go directly to the sender’s email address. #### Reply to address To use a different reply-to address, leave the checkbox unchecked, and specify: * **Reply-To name**: The name that will appear as the contact for replies. * **Reply-To email**: The email address where replies should be sent. ![Reply-To address configuration fields with name and email in Pushwoosh](https://docs.pushwoosh.com/configure-project-email-verification-6.webp) If both fields are left blank, replies will be sent to the default sender’s email specified in the **From address** section. After completing the required fields, click **Next** to proceed with domain verification. ## Configure DNS records To authenticate your domain and enable email sending for your campaigns, you’ll need to configure the following DNS records in your hosting provider’s DNS settings: * **DKIM (Required)**. This record digitally signs your emails, allowing email providers to verify that an email originates from your domain and has not been altered in transit. * **SPF (Required)**: This record specifies which mail servers are permitted to send emails on behalf of your domain, helping to prevent spoofing. * **DMARC (Required)**: This record provides instructions for handling unauthenticated emails and reporting back to you, enhancing email security. ### DKIM records (required) What are DKIM Records? DKIM (DomainKeys Identified Mail) is an email authentication method that lets receiving servers verify that an email was sent by the stated domain and has not been altered in transit. By adding DKIM records to your DNS settings, you apply a cryptographic signature to outgoing emails. This signature verifies that the message’s content remains unchanged and authenticates it as a legitimate message from your domain. To set up DKIM, you’ll need to add all four CNAME (Canonical Name) records to your DNS settings. These records are essential for authenticating your domain and confirming that emails sent from your domain are authorized. ![DKIM CNAME records displayed in Pushwoosh email configuration](https://docs.pushwoosh.com/configure-project-email-verification-8.webp) Copy the CNAME records and add them to your DNS settings. Note DNS providers handle records differently. Some require you to paste the entire record (host name + domain), while others only need the unique key portion (host name without the domain). Check your DNS provider’s instructions on how to add the records. Once you’ve added the required DNS records, the domain verification process usually takes about 5 to 10 minutes, but it can take up to 24 hours in some cases. During this time, you won’t be able to send emails through Pushwoosh until the verification is complete. Click **Check DNS Records** to refresh the verification status after adding the DNS records. Once verification is successful, the Domain verification status will change to **Verified**. ![Domain verification status showing Verified status after DNS records are configured](https://docs.pushwoosh.com/configure-project-email-verification-9.webp) Meanwhile, feel free to move on to other setup steps and come back later to check the verification status. #### Send test email Once your domain configuration and DKIM verification are complete, you can send a test email to ensure your email settings are functioning correctly and that emails will be successfully delivered to users once your campaign goes live. To send a test email: 1. In the **Email Channel Configuration** section, click **Send test email**. ![Send test email button in Email Channel Configuration section](https://docs.pushwoosh.com/configure-project-email-verification-10.webp) 2. Enter Sender and Recipient details: * **From**: The sender’s email address you configured. * **Recipient**: Enter the email address where you want to send the test email. By default, this field is pre-filled with the email of the logged-in user, but you can change it if needed. 3. Select the email content from the dropdown to include in the test email. 4. Click **Send**. ![Test email form with sender, recipient, and email content selection fields](https://docs.pushwoosh.com/configure-project-email-verification-11.webp) ### SPF records (required) Pushwoosh requires setting up a **Sender Policy Framework (SPF) record** to authorize its mail servers to send emails on behalf of your domain. SPF is an email authentication protocol that helps prevent spoofing and improves email deliverability. Note Before adding a new SPF record, check if your domain already has one, as most DNS providers allow only one SPF record per domain. #### Adding a new SPF record If your domain does not have an SPF record, add a new TXT record with the following value. **SPF Value** ```plaintext "v=spf1 include:spf.pushwoosh.io ~all" ``` Depending on your DNS provider, the name of the record may be either blank or set as @. #### Adding to an existing SPF record If your domain already has an SPF record, simply add the following SPF mechanism to your existing record to authorize Pushwoosh. ```plaintext include:spf.pushwoosh.io ``` ![SPF record configuration example showing how to add include:spf.pushwoosh.io to existing SPF record](https://docs.pushwoosh.com/configure-project-email-verification-12.webp) ### DMARC verification (required) **DMARC** (Domain-based Message Authentication, Reporting, and Conformance) is an email authentication protocol that helps protect your domain from unauthorized use, such as email spoofing. Pushwoosh requires DMARC to be configured on your domain to ensure secure and authenticated email delivery. For more information on DMARC, see the [DMARC Protocol Documentation](https://dmarc.org/overview/). To configure DMARC: 1. Copy the DMARC TXT record ![DMARC TXT record displayed in Pushwoosh email configuration](https://docs.pushwoosh.com/configure-project-email-verification-13.webp) 2. Go to your DNS provider’s settings and add the DMARC record to the DNS settings. (Refer to your DNS provider’s documentation if you need help adding these records.) 3. Enable reporting (optional). To receive reports on email authentication and security issues, add an email address in the `rua` field within the **Value** parameter. ### Choosing a different domain If you realize that you need to change your domain at this step, click **Choose different domain**. Then, you can add a new sender domain. Keep in mind that changing your domain name will generate new DNS records. This ensures that the domain limit is tracked correctly and excludes any domains you no longer need. ![Choose different domain button in Pushwoosh email configuration](https://docs.pushwoosh.com/configure-project-email-verification-14.webp) ## Configure link tracking Link tracking helps you understand how your audience interacts with links in your emails by adding **UTM parameters**. With UTM tags, you can track email engagement directly in Google Analytics or any other analytics system that tracks UTM. Note If you choose not to configure Google Analytics URL tracking, Pushwoosh will still track link clicks and provide basic statistics. Simply leave the **Google Analytics URL tracking** toggle off and click **Complete setup**. To add link tracking, enable Google Analytics URL tracking. The following UTM parameters will be added to your links: * **utm_source**: Identifies the traffic source. * **utm_medium**: Specifies the marketing medium, which is set to “email” by default. * **utm_campaign**: Adds the campaign code (e.g., campaign ID). This is inserted automatically. * **utm_content**: Tracks the specific content within the email, such as the subject. This is inserted automatically. The **Link Preview** shows an example of how your links will look with the selected UTM parameters. ![Google Analytics URL tracking configuration with UTM parameters and link preview](https://docs.pushwoosh.com/configure-project-email-verification-15.webp) Once you’ve configured the UTM parameters, click **Complete setup** to save your settings. The UTM tags will be added automatically to every link in your email, allowing you to track the source, medium, campaign, and content performance directly in Google Analytics. ## Email channel configuration overview Once your email channel is configured, the **Email channel configuration** dashboard provides an overview and allows you to manage key settings for sending emails, including sender domains, default sender details, and link tracking options. ### Configuration status At the top, you can view the email platform status, which indicates whether it is configured. If the platform is not configured, it may be due to the following reasons: * **Default sender details** have not been specified. [Learn more about default sender details](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/email-verification/#add-default-sender-details). ![Email platform status showing configuration issue due to missing default sender details](https://docs.pushwoosh.com/configure-project-email-verification-16.webp) * An **unverified domain** is set as the default sender. [Learn more about verifying your domain](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/email-verification/#configure-dns-records). ![Email platform status showing unverified domain warning in Pushwoosh](https://docs.pushwoosh.com/configure-project-email-verification-17.webp) ### Your sender domains In the **Your sender domains** section, you can view and manage the domains you use for sending emails and the status of each domain: * **READY**: The domain is configured and ready to send emails. * **NOT READY**: The domain verification is incomplete, typically due to pending DKIM verification, which is required. Domains marked as **NOT READY** cannot send emails until all necessary verifications are completed. To complete the configuration, click on the domain name in the list. Additionally, this section displays the status of each verification record (DKIM, SPF, DMARC) as **Verified** or **Pending**. **Pending** indicates that the record is either awaiting verification or has not yet been configured. Click **Update status** to refresh the verification status for each domain. ##### Adding a domain To add additional domains, click **Add domain**. To increase this limit, please contact support. ![Add domain button in Your sender domains section of Pushwoosh email configuration](https://docs.pushwoosh.com/configure-project-email-verification-18.webp) ##### Deleting a domain To delete a domain: 1. In **Your Sender Domains**, locate the domain to delete. 2. Click the **three-dot menu** next to the domain name and select **Delete domain**. 3. Confirm deletion, or click **Cancel** to retain the domain. > **Important**: Deleting a domain can disrupt active email campaigns that use it as the sender. Be sure to check all ongoing campaigns before deleting the domain. Note If a domain is set as the default “From” address in any project, you cannot delete it until the sender information is updated in those projects. An error message will appear, along with a list of projects using this domain as the default sender. Update the “From” address in each project to a different verified domain, then try deleting the domain again. ##### Sending a test email From the list of domains, you can also send a test email. To do this, click the three-dot menu next to the configured domain and select **Send Test Email**. Note that this option is only available for domains that have been fully configured. ### Default sender details In this section, you can view and manage the default sender details, including: * **From Address**: The name and email address that will appear as the sender in emails. * **Reply-To Address**: The default name and email for replies. To make changes, click **Edit default sender details**. > **Important**: The email channel will not be configured if you don’t specify the default sender details, and a warning message will appear. To set default sender details, click **Set sender details.** ### Google Analytics URL tracking In this section, you can manage **Link Tracking** settings. When enabled, UTM parameters are automatically added to email links, allowing you to track user engagement in Google Analytics. You’ll also see a **Link Preview** displaying how your URLs will appear with UTM tags. To enable tracking, switch the toggle to **Enable**. ## Configuring emails via Pushwoosh API To configure Email platform via the Pushwoosh API, submit the [`configureApplication`](https://docs.pushwoosh.com/developer/api-reference/app-configuration#configureapplication-for-email) request. ## Set up a custom tracking domain The **Click Tracking Domain (CTD)** is the domain part of a tracked link URL shown in an email message. It combines a subdomain with your main domain, for example, `click.yourdomain.com`. The subdomain is created in your domain’s DNS settings with your domain provider, usually by adding a CNAME record. With a CTD, you can wrap email links for click tracking on your own subdomain and keep deliverability and deep links working as expected. To set up a custom tracking domain: 1. Decide which subdomain you will use as your CTD (for example, `click.yourdomain.com`). 2. In Pushwoosh, open **Settings**, then select **Configure Platforms**. 3. On the **Email channel configuration** page, scroll to **Custom tracking domain** and select **Enable**. Note The **Custom tracking domain** section is shown only after the email channel is configured for your application. If you do not see it, complete [email configuration](https://docs.pushwoosh.com/product/first-steps/start-with-your-project/configure-platforms/email-verification/) first. ![Pushwoosh Control Panel showing Settings, Configure Platforms, Email channel configuration, and the Custom tracking domain card with the Enable control.](https://docs.pushwoosh.com/integrations-appsflyer-esp2-email-integration-2.webp) 4. Enter your CTD in the **Domain** field and select **Next**. ![Enable custom tracking domain dialog with the Domain field for entering the CTD and Cancel and Next buttons.](https://docs.pushwoosh.com/integrations-appsflyer-esp2-email-integration-3.webp) 5. Outside Pushwoosh, open the service where you manage public DNS for the domain of your CTD (typically your domain registrar, a DNS host, or your hosting account). In its DNS or zone editor for that domain, add the **CNAME** Pushwoosh shows on this step so your CTD points to `api.pushwoosh.com`. DNS propagation DNS changes usually take effect within minutes but can take up to 48 hours. 6. In Pushwoosh, select **Verify**. ![Custom tracking domain DNS verification step showing the CNAME target api.pushwoosh.com and Back, Verify, and Save controls.](https://docs.pushwoosh.com/integrations-appsflyer-esp2-email-integration-4.webp) 7. When verification succeeds, select **Save**. 8. If you need to change the **Domain** or DNS record, select **Back** and adjust the earlier steps. 9. After you click **Save**, your CTD appears in the **Custom tracking domain** list in **Email channel configuration**. ![Email channel configuration with the Custom tracking domain section showing the saved click tracking domain in the list.](https://docs.pushwoosh.com/integrations-appsflyer-esp2-email-integration-5.webp) To disable it later, select `...` next to your CTD, then select **Disable custom tracking domain**. --- # Huawei configuration **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/huawei-configuration/ Step-by-step guide to configure the Huawei platform in Pushwoosh using AppGallery Connect credentials including Client ID and Client secret. --- 1. Select your app from the [Huawei AppGallery Connect projects list](https://developer.huawei.com/consumer/en/service/josp/agc/index.html#/myProject). 2. Go to **Project Setting** > **App information**. 3. Copy **Client ID** and **Client secret** values. ![Huawei AppGallery Connect showing app information including Client ID and Client secret](https://docs.pushwoosh.com/configure-project-huawei-configuration-1.webp) 4. Go to your Pushwoosh project, open the **Configure Platforms** section, and click **Connect** for the **Huawei Android** platform. ![Pushwoosh Configure Platforms section with the Huawei Android row and Connect button.](https://docs.pushwoosh.com/configure-project-huawei-configuration-2.webp) 5. Select the framework. Paste the **Client ID** and **Client secret** into the **App ID** and **App Secret** fields respectively, then press **Apply**. ![Pushwoosh Huawei configuration screen.](https://docs.pushwoosh.com/configure-project-huawei-configuration-3.webp) --- # iOS configuration options **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ Learn how to set up messaging services using either certificate-based or token-based authentication, depending on your needs. --- This section provides step-by-step instructions for configuring your iOS application to enable messaging services using Pushwoosh. Choose between certificate-based or token-based configuration depending on your project requirements. Tip Regardless of the method chosen, keep your certificates and keys secure. Unauthorized access can lead to misuse of your push notification capabilities. ## iOS certificate-based configuration Learn how to configure Pushwoosh for iOS using certificate-based authentication for APNs (Apple Push Notification Service). [Learn more ](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-platform-configuration/) ## iOS token-based configuration Set up Pushwoosh with token-based authentication for APNs, offering a more secure and efficient alternative to certificates. [Learn more ](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-token-based-configuration/) ## VoIP certificate configuration for iOS Enable Pushwoosh to deliver VoIP push notifications to your iOS app so you can send incoming-call alerts and other VoIP events to users’ devices. [Learn more ](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-voip-certificate-configuration/) ## Apple Wallet pass configuration for iOS Upload your Pass Type ID signing certificate so Pushwoosh can sign and update Apple Wallet passes (`.pkpass`) for your app. [Learn more ](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-wallet-pass-configuration/) ## iOS action buttons configuration Create custom action buttons (iOS categories) so users can interact with your push notifications directly from the notification banner. [Learn more ](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-action-buttons-configuration/) ## Choosing between .p12 certificates and .p8 keys for iOS push notifications When configuring iOS push notifications in Pushwoosh, you must authenticate with Apple Push Notification service (APNs). There are two supported methods: 1. **`.p12` certificate**: the traditional, certificate-based approach. 2. **`.p8` key**: the modern, token-based method recommended by Apple. This guide will help you determine which method best fits your use case. Important [Live Activities](https://docs.pushwoosh.com/developer/pushwoosh-sdk/ios-sdk/ios-live-activities/) in Pushwoosh require [token-based configuration](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-token-based-configuration/). If you intend to use Live Activities, ensure your iOS configuration uses this method, as certificate-based configuration is not supported. ## Understanding the options | Feature | `.p12` Certificate | `.p8` Authentication Key | | ------------------ | ------------------------------------------------------- | ----------------------------------------------------- | | **How it works** | Uses a cryptographic certificate to establish trust. | Uses a persistent token signed by a private key. | | **File** | `.p12` file containing the certificate and private key. | `.p8` file containing a private key. | | **Expiration** | Expires (typically yearly); requires renewal. | Does not expire automatically. | | **Setup** | More complex to generate and manage. | Generally simpler to set up. | | **Usage** | One certificate per Bundle ID for each environment. | One key supports multiple apps and both environments. | | **Recommendation** | Legacy method. Use only for existing setups. | Recommended by Apple and Pushwoosh. | ## Pros and cons of each method ### `.p12` certificate: the traditional approach **Pros:** * Widely supported. * Allows separate certificates for development and production. **Cons:** * Certificates expire and require renewal. Failure to renew can disrupt push delivery. * More complex to manage. ### `.p8` key: the modern, recommended approach **Pros:** * No renewals required, reducing maintenance overhead. * Easier to generate and integrate. * One key works across projects. * Recommended by Apple and Pushwoosh. **Cons:** * If compromised, all associated apps are at risk. Secure your `.p8` key properly. ## Which method should you choose? Important security note Regardless of which method you choose, always secure your certificates and keys. Unauthorized access can compromise your push notification infrastructure. We recommend using the **`.p8` key method** for all new projects. It is simpler, more scalable, and aligned with Apple’s best practices. Use `.p12` certificates only if: * You have existing infrastructure dependent on `.p12` certificates. * You require strict environment separation that cannot be achieved with a `.p8` key. ## Configuration guides [Certificate-based configuration ](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-platform-configuration) [Token-based configuration ](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-token-based-configuration) [VoIP certificate configuration for iOS ](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-voip-certificate-configuration) [Apple Wallet pass configuration for iOS ](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-wallet-pass-configuration) [Action buttons configuration for iOS ](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-action-buttons-configuration) --- # iOS action buttons configuration **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-action-buttons-configuration/ Create custom iOS action buttons as notification categories in the Pushwoosh Control Panel for interactive push notifications. --- iOS interactive notifications let users take an action from the notification banner without opening the app. In Pushwoosh you set this up with **iOS categories**: each category holds one or two buttons that you create in the Control Panel and attach to a push. Note Your app must handle button taps in the notification delegate. Share the [Developers’ Guide on iOS Interactive Push Notifications](https://docs.pushwoosh.com/developer/guides/messaging-channels/ios-interactive-push) with your development team. ## Create a category 1. Open the **Configure platforms** page of your application in Pushwoosh. 2. Click **Action buttons** next to the iOS platform. You can do this before or after the main iOS platform setup. ![Action buttons entry for the iOS platform on the Configure platforms page](https://docs.pushwoosh.com/ios-configuration-ios-action-buttons-configuration-1.webp) 3. Enter a **Category name**. You will use this name to find the category later. 4. Specify the **Button label**. This is the text on the button. iOS shows up to two lines of text. 5. Select a **Button type**: * **Destructive:** for actions such as delete, reject, or dismiss. * **Non-destructive:** for positive or neutral actions. 6. Set a **Button ID**. It must be unique within the category. Your app receives this ID when the user taps the button. See the [Developers’ Guide on iOS Interactive Push Notifications](https://docs.pushwoosh.com/developer/guides/messaging-channels/ios-interactive-push) for how to read it in the notification delegate. 7. Optionally enable **Launch app on action** to open the app when the user taps the button. 8. To add a second button, click **+** next to the first button and repeat steps 4–7. A category supports up to two buttons. Use **−** to remove the second button. 9. Click **Create** to save the category. It appears in the list below with its **Category ID**. ## Use the category in a push Once created, attach the category when you send a push via the API, pass the **Category ID** as `ios_category_id` in [`createMessage`](https://docs.pushwoosh.com/developer/api-reference/messages-api/#createmessage). ## Example For a fitness re-engagement push, you might define a category **fitness_reengagement** with: * **Claim 20% Off** (`claim_offer`): Non-destructive, **Launch app on action** on * **Maybe Later** (`dismiss`): Destructive, **Launch app on action** off ![Category form with Claim 20% Off and Maybe Later action buttons](https://docs.pushwoosh.com/ios-configuration-ios-action-buttons-configuration-2.webp) When the user taps **Claim 20% Off**, the app opens and your code receives `claim_offer`. **Maybe Later** dismisses the notification without opening the app. --- # iOS certificate-based configuration **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-platform-configuration/ Set up iOS push notifications in Pushwoosh using certificate-based configuration with APNs for manual, secure delivery. --- Important [Live Activities](https://docs.pushwoosh.com/developer/pushwoosh-sdk/ios-sdk/ios-live-activities/) in Pushwoosh require [token-based configuration](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-token-based-configuration/). If you intend to use Live Activities, ensure your iOS configuration uses this method, as certificate-based configuration is not supported. Follow this guide to configure the iOS platform manually. Note Make sure you’ve created a provisioning profile for your app to submit it to the App Store. Read more in the [Apple developer documentation](https://developer.apple.com/help/account/provisioning-profiles/create-an-app-store-provisioning-profile). ## Generating a certificate request file 1. Launch **Keychain Access,** go to **Certificate Assistant** and click **Request a Certificate From a Certificate Authority**: ![Keychain Access on macOS showing Certificate Assistant menu to request a CSR for APNs certificate](https://docs.pushwoosh.com/ios-configuration-ios-platform-configuration-1.webp) 2. Enter the required information and choose **Saved to disk**. You should leave the CA email field blank. Click **Continue** and **Save** the certificate request using the suggested name. ![Create CSR in Keychain Access](https://docs.pushwoosh.com/ios-configuration-ios-platform-configuration-2.webp) ## Creating an APNs certificate in Apple Developer Portal 1. Sign in to the [Apple Developer Portal](https://developer.apple.com/account/) and open **Certificates, Identifiers & Profiles** in the **Account** tab. Click **Add**: ![Apple Developer Portal—Certificates, Identifiers & Profiles dashboard with Add certificate button](https://docs.pushwoosh.com/ios-configuration-ios-platform-configuration-3.webp) 2. Choose the certificate type you need and click **Continue** at the bottom of the page. Note You can select the **Sandbox & Production** certificate type shown in the screenshot below and then choose the appropriate **Gateway** when configuring the iOS platform in the Pushwoosh Control Panel. You can also create Sandbox and Production certificates separately if needed. ![Selecting APNs SSL (Sandbox & Production) certificate type in Apple Developer Portal](https://docs.pushwoosh.com/ios-configuration-ios-platform-configuration-4.webp) 3. Select your project’s **App ID** on the next page, then click **Continue**. ![Choosing App ID for APNs certificate issuance in Apple Developer Portal](https://docs.pushwoosh.com/ios-configuration-ios-platform-configuration-5.webp) Note You can skip **About Creating a Certificate Signing Request (CSR)** as you have already created one. 4. Choose the **Certificate Signing Request** you created previously. ![Uploading the CSR file](https://docs.pushwoosh.com/ios-configuration-ios-platform-configuration-6.webp) 5. Download the certificate and add it to the **Keychain Access**. Once you click on the certificate, **Keychain Access** will be launched. ![Downloading the certificate from Apple Developer Portal](https://docs.pushwoosh.com/ios-configuration-ios-platform-configuration-7.webp) ## Exporting the private key (.p12) In **Keychain Access**, right-click the certificate you just added and choose Export. ![Export the private key as .p12 from Keychain Access](https://docs.pushwoosh.com/ios-configuration-ios-platform-configuration-8.webp) Save the **Personal Information Exchange (.p12)** file. You will be prompted to set up a password. Important Make sure to remember the Private Key Password, you will need it later. After you type in your password, click **Allow** to finish exporting the Private Key. ## Configuring the iOS platform in Pushwoosh In your Pushwoosh project, go to the **Configure Platforms** section and click **Connect** in the iOS row: ![Pushwoosh Control Panel showing iOS row with Connect button](https://docs.pushwoosh.com/ios-configuration-ios-platform-configuration-9.webp) In the opened form, choose **certificate-based manual configuration** and click **Next**: ![Pushwoosh form with certificate-based manual configuration selected](https://docs.pushwoosh.com/ios-configuration-ios-platform-configuration-10.webp) In the opened window, do the following: * Upload the certificate file (.p12) * Enter the **Private key password** * Choose the **Gateway** ![Fields for uploading .p12 file, entering password, and selecting gateway in Pushwoosh](https://docs.pushwoosh.com/ios-configuration-ios-platform-configuration-11.webp) Click **Configure** to complete the setup. --- # iOS token-based configuration **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-token-based-configuration/ Configure iOS push notifications with APNs using token-based authentication for faster, secure delivery. --- For faster communication with APNs, you can configure your iOS project using token-based authentication. Note To learn more, please check out the [Apple Developer docs](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/establishing_a_token-based_connection_to_apns). ## Obtain an Encryption Key and Key ID from Apple 1. Log in to your Apple Developer account and navigate to the **Keys** section in the left-hand menu. Press **+** to create a new key. 2. In the **Key Description** field, enter a unique name for the key. Then, enable APNs in the **Key Services** section. Click **Continue**. 3. Copy the **Key ID**, which is a 10-character string, and download the **authentication token signing key**, which is a text file with a .p8 file extension. ## Configure the iOS platform in Pushwoosh 1. In your Pushwoosh project, go to the **Configure Platforms** section and click **Connect** next to the iOS platform. ![Pushwoosh platform configuration screen showing the iOS row with the 'Connect' button.](https://docs.pushwoosh.com/ios-configuration-ios-platform-configuration-9.webp) 2. In the configuration form that opens, choose **Token-based manual configuration** and click **Next**. ![iOS configuration form with token-based manual configuration option selected.](https://docs.pushwoosh.com/ios-configuration-ios-token-based-configuration-2.webp) 3. Paste the **Key ID** into the appropriate field. ![Field in Pushwoosh form to input the Key ID.](https://docs.pushwoosh.com/ios-configuration-ios-token-based-configuration-3.webp) 4. Upload the **.p8 signing key file** you downloaded from Apple in the **Auth Key** field. ![Field in Pushwoosh form to upload the .p8 authentication key file.](https://docs.pushwoosh.com/ios-configuration-ios-token-based-configuration-4.webp) 5. Enter your Apple Developer **Team ID** and **Bundle ID**. ![Form fields in Pushwoosh for entering Team ID and Bundle ID.](https://docs.pushwoosh.com/ios-configuration-ios-token-based-configuration-5.webp) > To get your Team ID, go to your Apple Developer account and navigate to the **Membership** section. > > You can find a Bundle ID in the **Certificates, Identifiers & Profiles** section of your Apple Developer console. 6. Choose the appropriate gateway: **Sandbox** or **Production**. ![Gateway selection options for Sandbox and Production in the Pushwoosh configuration form.](https://docs.pushwoosh.com/ios-configuration-ios-token-based-configuration-6.webp) 7. Click **Configure** to complete the setup. Tip To check whether the iOS platform is configured successfully, send a test push or target a message to a specific device. For guidelines, see the [Test your integration](https://docs.pushwoosh.com/developer/first-steps/test-your-integration) page. --- # VoIP certificate configuration for iOS **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-voip-certificate-configuration/ Upload a .p12 VoIP certificate in the Control Panel and select the gateway for Sandbox or Production iOS VoIP pushes. --- Upload your VoIP certificate in the Control Panel so that Pushwoosh can deliver VoIP push notifications to your iOS app. After you complete the steps below, you can send incoming-call alerts and other VoIP events through Pushwoosh to devices that have your app installed. ## Creating the certificate Follow the same flow as for a standard APNs certificate: 1. [Generate a certificate request file](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-platform-configuration/#generating-a-certificate-request-file) in Keychain Access. 2. Create the certificate in Apple Developer Portal. Under **Services**, choose **VoIP Services Certificate**. See [Create VoIP services certificates](https://developer.apple.com/help/account/certificates/create-voip-services-certificates) in Apple Help. 3. [Export the private key as .p12](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-platform-configuration/#exporting-the-private-key-p12) from Keychain Access. You will need the .p12 file and the private key password when filling the form below. ## Configuring the certificate in the Control Panel 1. Go to **Settings → Configure platforms** in the Control Panel. 2. Find **iOS** in the **Mobile platforms** list and click **Connect** next to it. 3. In the dropdown, select **VoIP push notifications**. ![Control Panel dropdown with VoIP push notifications selected for iOS platform](https://docs.pushwoosh.com/configure-platforms-voip-certificate-1.webp) 4. Next to **VoIP certificate file (.p12)**, click the attachment icon and select the .p12 file you exported from Keychain Access. 5. In **Private key password**, enter the password you set when exporting the .p12 file. 6. Under **Gateway**, select **Sandbox** for development and testing, or **Production** for live apps. ![VoIP certificate configuration form for iOS with .p12 upload, password field, gateway options, and Configure button](https://docs.pushwoosh.com/configure-platforms-voip-certificate-2.webp) 7. Click **Configure** to save the configuration. Once the configuration is saved, Pushwoosh can deliver VoIP push notifications to your iOS app. To implement receiving and handling VoIP pushes in the app, use the [Pushwoosh VoIP module](https://docs.pushwoosh.com/developer/pushwoosh-sdk/ios-sdk/voip-pushes/) and the [Messages API](https://docs.pushwoosh.com/developer/api-reference/messages-api/) for sending. --- # Apple Wallet pass configuration for iOS **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-wallet-pass-configuration/ Upload your Pass Type ID certificate in the Control Panel so Pushwoosh can sign and update Apple Wallet passes for your app. --- Configure your **Pass Type ID signing certificate** so Pushwoosh can sign and update [Apple Wallet passes](https://docs.pushwoosh.com/product/messaging-channels/apple-wallet-passes/) (`.pkpass`) for your app. This is a one-time setup. Once a valid certificate is in place, the Apple Wallet [pass builder](https://docs.pushwoosh.com/product/messaging-channels/apple-wallet-passes/pass-builder/) unlocks for the application. ## Create the certificate Important The certificate is stored **per application**. Configure it for each application that issues passes. 1. **Register a Pass Type ID.** In the [Apple Developer Portal](https://developer.apple.com/account/resources/identifiers/list), go to **Certificates, Identifiers & Profiles → Identifiers**, click **+**, select **Pass Type IDs**, and enter a reverse-DNS identifier such as `pass.com.yourcompany.passtype`. 2. [**Generate a certificate signing request (CSR)**](https://developer.apple.com/help/account/certificates/create-a-certificate-signing-request) in Keychain Access. You will upload this file in the next step. 3. **Create the certificate.** Open your Pass Type ID in the Apple Developer Portal and click **Create Certificate**. Select **Pass Type ID Certificate**, upload your CSR file, and download the resulting `.cer` file. Double-click it to add it to Keychain Access. See [Create a certificate](https://developer.apple.com/help/account/capabilities/create-wallet-identifiers-and-certificates) in Apple documentation. 4. **Export the certificate as .p12** from Keychain Access. In the **My Certificates** section, find your Pass Type ID certificate, right-click it, and select **Export**. Choose `.p12` format and set an export password. You need this file and password in Pushwoosh. ## Configure the certificate in the Control Panel 1. Go to **Settings → Configure platforms** in the Control Panel. 2. Under **MOBILE PLATFORMS**, find **iOS** and click **SET UP PASSKIT**. ![Configure platforms page with iOS row showing SET UP PASSKIT among platform action buttons](https://docs.pushwoosh.com/configure-platforms-passkit-1.webp) 3. Click the attachment icon next to **PASS TYPE ID CERTIFICATE FILE (.P12)** and select your `.p12` file. 4. In **PRIVATE KEY PASSWORD**, enter the password you set when you exported the `.p12` file from Keychain Access. 5. Click **Configure**. ![Apple Wallet Pass Type ID certificate form with p12 file upload, private key password field, and Configure button](https://docs.pushwoosh.com/configure-platforms-passkit-2.webp) Keep the certificate current Pass Type ID certificates expire (Apple issues them with a limited validity period). When a certificate is close to expiry, renew it in your Apple Developer account, export a new `.p12`, and upload it again on **Configure platforms** → **SET UP PASSKIT**. If the configured certificate has expired, Pushwoosh can no longer sign passes. Creating and updating passes will fail until you upload a current certificate. Replace it before it lapses to avoid interrupting live passes. --- # KakaoTalk configuration **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/kakao-configuration/ Learn how to configure the KakaoTalk platform to send messages to users in South Korea and other regions. --- Pushwoosh enables you to send messages to users via KakaoTalk. By integrating KakaoTalk, you can extend your reach to users in South Korea and other regions where this messaging platform is dominant. ## Prerequisites Before configuring KakaoTalk, ensure the following requirements are met: * **Pushwoosh account**: A project where you want to enable KakaoTalk. * **A registered Kakao Business account** * **User Code and Secret Key**: Credentials from the Kakao Business Center required to connect your KakaoTalk account to Pushwoosh and authorize message sending. ## Setting up the KakaoTalk configuration To set up the KakaoTalk configuration, follow these steps: 1. Navigate to **Settings > Configure Platforms**. Scroll down the list of platforms to find **KakaoTalk** and click **Connect**. ![KakaoTalk platform in the Configure Platforms list](https://docs.pushwoosh.com/configure-project-kakao-configuration-1.webp) 2. In the **KakaoTalk notifications** modal, enter your Kakao Business credentials: * **USER CODE**: Your unique User Code from the Kakao Business Center. * **SECRET KEY**: Your corresponding Secret Key. These credentials verify your identity and authorize Pushwoosh to send messages on your behalf. ![KakaoTalk configuration modal with User Code and Secret Key fields](https://docs.pushwoosh.com/configure-project-kakao-configuration-2.webp) 3. Click **Apply** to save your configuration. ## What’s next KakaoTalk uses a template-based messaging system. Before you can send campaigns or transactional messages, you need to: 1. Create a message template. 2. Submit it for approval by the Kakao team. [Learn how to create and manage KakaoTalk message templates](https://docs.pushwoosh.com/product/content/kakao-presets/). Once your templates are approved, you can send KakaoTalk messages using: * **API**: Send messages programmatically via the [Kakao API endpoint](https://docs.pushwoosh.com/developer/api-reference/kakao/). * **Journey**: Create automated messaging flows in the [Customer Journey](https://docs.pushwoosh.com/product/messaging-channels/kakao/send-kakao-messages/) builder. --- # LINE configuration **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/line-configuration/ Configure LINE in Pushwoosh to send messages via API and Customer Journey. Reach users on one of the top messaging platforms. --- To enable message delivery through the LINE messaging app, you must first configure the LINE platform within your project settings. ## Prerequisites Before you begin, make sure you have: * [A LINE official account](https://developers.line.biz/en/docs/messaging-api/getting-started/#step-one-enable-use-of-messaging-api) * A registered **Messaging API** channel in the LINE Developers Console. [Learn more](https://developers.line.biz/en/docs/messaging-api/getting-started/) * The following credentials from LINE: * **Channel ID** * **Channel secret** ## Configure LINE in Pushwoosh 1. In the **Pushwoosh Control Panel**, navigate to **Settings > Configure Platforms** 2. Find **LINE** in the list of platforms and click **Connect**. ![Connect LINE](https://docs.pushwoosh.com/configure-project-line-configuration-1.webp) 3. In the configuration window, enter the following: * **Channel ID:** Your LINE Messaging API Channel ID * **Channel secret:** Your LINE Messaging API Channel Secret ![Fill in Channel ID and secret](https://docs.pushwoosh.com/configure-project-line-configuration-2.webp) After entering the required credentials and setting the webhook, click **Save** to complete the configuration. ### Where to find the Channel ID and Channel secret #### Channel ID To find your Channel ID: 1. Go to the [LINE Developers Console](https://developers.line.biz/console/) 2. Select your provider 3. Choose the appropriate channel 4. Go to the **Basic settings tab**, locate and copy the **Channel ID** [Learn how to find your Channel ID in the LINE Developers Console](https://developers.line.biz/en/faq/#where-can-i-find-channel-id) ![Find your Channel ID](https://docs.pushwoosh.com/configure-project-line-configuration-3.webp) #### Channel secret To find your Channel Secret: 1. Go to the [LINE Developers Console](https://developers.line.biz/console/) 2. Select your provider 3. Choose the relevant channel 4. Navigate to the **Basic settings** tab 5. Scroll down to the **Channel secret** field and click **Copy**. [Learn more](https://developers.line.biz/en/glossary/#channel-secret) ![Find your Channel Secret](https://docs.pushwoosh.com/configure-project-line-configuration-4.webp) > **Important:** The Channel secret is required to authenticate your application with the LINE Messaging API. Keep this value secure and do not share it publicly. ## Set the Webhook URL in LINE To allow LINE to send incoming messages and events to Pushwoosh, you need to configure a webhook URL in the LINE Developers Console. Follow these steps to set it up: 1. Go to the **Messaging API** tab in the LINE Developers Console. 2. In the **Webhook URL** field, enter: ```plaintext https://tw-callback.svc-nue.pushwoosh.com/api/v1/lineCallback/XXXXX-XXXXX ``` Replace `XXXXX-XXXXX` with your actual **Pushwoosh application code**. 3. Click **Verify**. If the URL is valid and responsive, you will see a **Success** message. 4. Enable the **Use webhook** option to activate webhook delivery. ![Set the Webhook URL in LINE](https://docs.pushwoosh.com/configure-project-line-configuration-5.webp) [Refer to the official LINE documentation for details on setting the webhook URL](https://developers.line.biz/en/docs/messaging-api/building-bot/#setting-webhook-url) --- # macOS configuration **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/macos-configuration/ Configure macOS push notifications in Pushwoosh using APNs certificate-based (.p12) or token-based (.p8) authentication. --- macOS apps receive push notifications through Apple Push Notification service (APNs), the same delivery channel iOS uses. Configure the macOS platform in Pushwoosh with either a certificate-based (.p12) or a token-based (.p8) connection to APNs. Note Make sure your macOS app has the Push Notifications capability enabled and an App ID registered in the Apple Developer Portal before you start. Read more in the [Apple developer documentation](https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns). ## Certificate-based configuration ### Create the .p12 certificate The Keychain, Apple Developer Portal, and export steps match the iOS certificate flow. Follow that guide and use your **macOS** App ID when Apple asks you to choose one: 1. [Generate a certificate request file](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-platform-configuration/#generating-a-certificate-request-file) in **Keychain Access**. 2. [Create an APNs certificate in Apple Developer Portal](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-platform-configuration/#creating-an-apns-certificate-in-apple-developer-portal). When you select an **App ID**, pick the ID for your macOS app, not the iOS one. 3. [Export the private key as .p12](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-platform-configuration/#exporting-the-private-key-p12) from **Keychain Access**. You will need the .p12 file and the private key password in the next section. ### Configure the macOS platform in Pushwoosh 1. In your Pushwoosh project, go to **Settings → Configure Platforms**. 2. Click **Connect** next to **macOS** in the **Desktop platforms** section. ![Desktop platforms section showing the macOS row with Not configured status and Connect button](https://docs.pushwoosh.com/configure-project-macos-configuration-1.webp) 3. In **Configuration mode for macOS**, select **Certificate-based manual configuration**. 4. Click **Next**. ![Configuration mode for macOS with Certificate-based manual configuration selected](https://docs.pushwoosh.com/configure-project-macos-configuration-2.webp) 5. On **Certificate-based configuration for macOS**, fill in the form: * **Certificate file (.p12):** upload the .p12 file you exported from Keychain Access. * **Private key password:** enter the password you set when exporting the .p12 file. * **Gateway:** select **Sandbox** for development or **Production** for live apps. ![Certificate-based configuration for macOS with p12 upload password Gateway and Configure](https://docs.pushwoosh.com/configure-project-macos-configuration-3.webp) 6. Click **Configure** to complete the setup. ## Token-based configuration You can configure the macOS platform with token-based authentication for faster communication with APNs. Note To learn more, check out the [Apple Developer docs](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/establishing_a_token-based_connection_to_apns). ### Obtain a signing key from Apple Creating the APNs key is the same as for iOS. Follow [Obtain an Encryption Key and Key ID from Apple](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-token-based-configuration/#obtain-an-encryption-key-and-key-id-from-apple) in the iOS token-based guide. You will need the **Key ID** and the **.p8** file in the next section. You can reuse the same APNs key you already use for iOS if you have one. ### Configure the macOS platform in Pushwoosh 1. In your Pushwoosh project, go to **Settings → Configure Platforms**. 2. Click **Connect** next to **macOS** in the **Desktop platforms** section. ![Desktop platforms section showing the macOS row with Not configured status and Connect button](https://docs.pushwoosh.com/configure-project-macos-configuration-1.webp) 3. In **Configuration mode for macOS**, select **Token-based configuration**. 4. Click **Next**. ![Configuration mode for macOS with Token-based configuration selected and Next button](https://docs.pushwoosh.com/configure-project-macos-configuration-4.webp) 5. On **Token-based configuration for macOS**, fill in the form: * **Key ID:** paste the 10-character Key ID from Apple. * **Team ID:** enter your Apple Developer Team ID from the **Membership** section of your Apple Developer account. * **Bundle ID:** enter the Bundle ID of your macOS app from **Certificates, Identifiers & Profiles**. * **Auth Key (.p8):** upload the .p8 signing key file you downloaded from Apple. * **Gateway:** select **Sandbox** for development or **Production** for live apps. ![Token-based configuration for macOS with Key ID Team ID Bundle ID Auth Key Gateway](https://docs.pushwoosh.com/configure-project-macos-configuration-5.webp) 6. Click **Configure** to complete the setup. Tip To check whether the macOS platform is configured successfully, send a test push or target a message to a specific device. For guidelines, see the [Test your integration](https://docs.pushwoosh.com/developer/first-steps/test-your-integration) page. --- # SMS platform configuration **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/sms-configuration/ Connect your SMS provider in Pushwoosh, configure provider webhooks for delivery receipts, and integrate SMS sends with the Messaging API. --- Pushwoosh enables you to send SMS messages to users by connecting your own SMS provider. Once configured, you can send [SMS](https://docs.pushwoosh.com/product/messaging-channels/sms) in one-time campaigns and Customer Journeys, or through the [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) API method. ## Prerequisites Before configuring SMS, ensure the following requirements are met: * **Pushwoosh project**: A project where you want to enable the SMS channel. * **SMS provider account**: An account with one of the [supported SMS providers](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/sms-configuration/#supported-sms-providers). * **Provider credentials**: The credentials required by your provider, such as account identifiers, API keys, a sender ID, or a phone number. ## Setting up the SMS configuration To set up the SMS configuration, follow these steps: 1. Go to **Settings → Configure Platforms**, select **SMS**, and click **Connect**. ![SMS platform in the Configure Platforms list](https://docs.pushwoosh.com/configure-project-sms-configuration-2.webp) 2. Choose your **SMS provider** from the list of [supported SMS providers](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/sms-configuration/#supported-sms-providers). 3. Enter the provider credentials. The required fields depend on the provider you select, such as account identifiers, API keys, a sender ID, or a phone number. ![SMS provider credential fields in the configuration form](https://docs.pushwoosh.com/configure-project-sms-configuration-1.webp) 4. Click **Save** to activate the channel. ## Supported SMS providers Pushwoosh supports the following SMS providers: * [Twilio](https://www.twilio.com/) * [Amazon SNS](https://aws.amazon.com/sns/) * [SMSGlobal](https://www.smsglobal.com/) * [SMSAla](https://smsala.com/) * [CapitoleMobile](https://www.capitolemobile.com/) * [Mobipace](https://www.mobipace.com/) * [SMSCenter](https://smscentre.com/) * [SMSTraffic](https://www.smstraffic.ru/) * [TextMe.co.il](https://textme.co.il/) * [AbleMobile](https://ablemobile.com/) * [MStat](https://campaign.omni-messaging.com/) To get your credentials, refer to your SMS provider’s documentation. Provider availability may depend on your account and region. Note MMS (subject + image attachments in an SMS message) is delivered only through **AbleMobile**. Other providers ignore the MMS fields and send the plain-text body. See [MMS](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/payload-reference/#mms) in the Messaging API v2 payload reference. ## Provider webhooks Some providers also require callback URLs registered on the provider side so Pushwoosh can receive delivery receipts, inbound replies, and channel events such as Viber subscription status. [SMS provider webhooks ](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/sms-configuration/sms-provider-webhooks/) ## What’s next After you connect a provider, register webhooks if your provider requires them, then send SMS from campaigns, journeys, or the API. [Send SMS with Messaging API v2 ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) [Learn more about SMS ](https://docs.pushwoosh.com/product/messaging-channels/sms/) --- # SMS provider webhooks **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/sms-configuration/sms-provider-webhooks/ Set up SMS provider webhooks so Pushwoosh receives delivery receipts, incoming replies, and Viber subscription events. --- After you [connect an SMS provider](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/sms-configuration/), some providers need a webhook URL registered on their side so Pushwoosh can receive delivery receipts, incoming replies, or channel-specific events such as Viber subscription status. Other providers submit this URL automatically with every message, so no extra setup is required. All webhooks are received at `https://tw-callback.svc-nue.pushwoosh.com/api/v1/...`. Where a URL includes `{APP_CODE}`, replace it with your [Pushwoosh application code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#application-code) (**Settings → Applications**). ## Automatic setup For these providers, Pushwoosh submits the callback URL automatically with every message. No action is required on the provider’s side. * **Twilio:** delivery status is submitted automatically with each message. To also receive replies (two-way SMS), set your Twilio phone number’s **“A message comes in”** webhook in the Twilio Console to: ```plaintext https://tw-callback.svc-nue.pushwoosh.com/api/v1/smsCallback/{APP_CODE} ``` * **SMSGlobal:** both delivery and incoming URLs are submitted automatically with each message. * **SMSAla:** the delivery URL is submitted automatically with each message. SMSAla does not support incoming SMS. ## Manual setup required For these providers, register the webhook URL once in the provider’s own dashboard. | Provider | Event | Method | URL | | -------------- | ------------------ | ---------- | --------------------------------------- | | MStat | Delivery | POST | `.../mstatCallback` | | MStat | Incoming | POST | `.../mstatIncoming/{APP_CODE}` | | MStat | Viber subscription | POST | `.../mstatViberSubscription/{APP_CODE}` | | Amazon SNS | Delivery | POST | `.../awsSmsCallback` | | CapitoleMobile | Delivery | GET | `.../capitoleMobileCallback` | | CapitoleMobile | Incoming | GET | `.../capitoleMobileIncoming/{APP_CODE}` | | AbleMobile | Delivery | GET / POST | `.../amSmsCallback` | | SMSTraffic | Delivery | POST | `.../smsTrafficCallback` | | TextMe.co.il | Delivery | GET | `.../textMeCoilCallback` | | TextMe.co.il | Incoming | GET | `.../textMeCoilCallback/{APP_CODE}` | Each URL above is relative to `https://tw-callback.svc-nue.pushwoosh.com/api/v1`. Amazon SNS Delivery receipts arrive through an SNS topic subscription, not a per-message parameter. 1. In the **AWS Console**, add an HTTPS subscription to your SMS delivery status topic. Use the `awsSmsCallback` URL from the table above. 2. When AWS sends a `SubscriptionConfirmation` request, find the `SubscribeURL` in the AWS Console under the pending subscription. 3. Open that URL to confirm the subscription. Until you confirm the subscription, Pushwoosh does not receive delivery receipts. ## No webhook support **Mobipace** and **SMSCenter** don’t send delivery or incoming webhooks to Pushwoosh. No setup is possible or required for these providers. --- # Web push configuration **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/web-push-configuration/ Configure web push notifications in Pushwoosh across supported browsers using simple setup steps and flexible customization. --- To start sending web push notifications with Pushwoosh, you need to configure your web push platform and enable the subscription prompt shown to users. Important Make sure the **Web Push SDK is properly integrated** into your website. This is a required step to allow users to subscribe and receive notifications. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/) To begin configuration, go to **Settings > Configure Platforms > Web Push Notifications** and click **Connect**. ![Connect web push notifications](https://docs.pushwoosh.com/web-configuration-1.webp) ## Configure web push for all browsers (except older Safari versions) This configuration applies to all modern browsers, including the latest versions of Safari, which now support web push notifications natively. **Note:** Older Safari versions (macOS 10.14–12) require a separate setup. You can configure that in a dedicated section. Learn more To begin the setup, click **Configure** under **All browsers configuration**. ![Configure web push for all browsers](https://docs.pushwoosh.com/web-configuration-2.webp) In the configuration window, choose one of the following options: * **Create a new push configuration** Recommended if you haven’t previously set up web push notifications through another service. Pushwoosh will automatically generate a new VAPID key pair. * **Use existing configuration** Choose this option if you already have VAPID keys, for example, from Firebase, and want to keep using them without asking users to subscribe again. ### Create a new push configuration Choose **Create a new push configuration** if you haven’t previously set up web push notifications with another service. Pushwoosh will automatically generate the required VAPID (Voluntary Application Server Identification) keys for you. What are VAPID keys? VAPID keys are a public-private key pair used in the Web Push Protocol to authenticate the application server when sending push notifications to web browsers. The **public key** is shared with the browser when a user subscribes to notifications. The **private key** stays on your server and is used to securely sign each message you send. Click **Configure** to generate and apply the keys. ![Create a new push configuration](https://docs.pushwoosh.com/web-configuration-3.webp) Once created, Pushwoosh will automatically use these keys in the SDK configuration. [Learn more about integrating the Web Push SDK](https://docs.pushwoosh.com/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/) ### Use existing configuration If you already have VAPID keys (such as those generated through Firebase), you can reuse them to set up web push notifications in Pushwoosh. For this: 1. Select **Use existing configuration**. 2. In the **Web Push Certificate** field, enter your **VAPID public key**. 3. In the **Web Push Private Key** field, enter your **VAPID private key**. 4. Click **Configure** to save and apply the settings. ![Use existing configuration](https://docs.pushwoosh.com/web-configuration-4.webp) #### How to find VAPID keys in Firebase If you’re migrating from Firebase and need to reuse your existing VAPID keys, follow these steps to find them. ##### Web Push certificate 1. In **Firebase**, navigate to **Project Settings → Cloud Messaging**. 2. Scroll down to the **Web Configuration** section and copy the existing key pair. ![Find Web Push certificate](https://docs.pushwoosh.com/web-configuration-6.webp) 3. Paste it into the **Web Push Certificate** field in Pushwoosh web configuration form. ![Paste it into the Web Push Certificate field](https://docs.pushwoosh.com/web-configuration-7.webp) ##### Web Push private key 1. In **Firebase Console**, go to **Project Settings → Cloud Messaging → Web Configuration**. 2. Click the **three-dot menu** under **Actions** next to the key pair and select **Show private key**. This key is essential for ensuring that Web Push notifications function correctly. ![Find Web Push private key](https://docs.pushwoosh.com/web-configuration-8.webp) 3. Copy the displayed key to your clipboard. 4. In the **Pushwoosh Web Configuration** form, paste it into the **Web Push Private Key** field. ![Paste Web Push private key](https://docs.pushwoosh.com/web-configuration-9.webp) 5. Click **Apply** to save your changes. ### Reconfigure web push configuration If you’ve already set up web push notifications but need to update your credentials (like replacing your VAPID keys), here’s how to do it: 1. Click **Reconfigure** under **All browsers configuration**. ![Reconfigure web push configuration](https://docs.pushwoosh.com/web-configuration-5.webp) 2. In the popup that appears, enter your new VAPID keys: * **Web Push Certificate**: your new public VAPID key * **Web Push Private Key**: your new private VAPID key 3. Click **Configure** to save the changes. Important Replacing your VAPID keys affects your entire web push setup and may disrupt notification delivery if not managed correctly. Only change the keys if it’s really necessary, and make sure you understand the impact before making any updates. ### Configure the Subscription prompt To send push notifications, users must explicitly grant permission through the browser’s system-level prompt. Without this permission, notifications cannot be delivered. Due to recent Chrome and Firefox policy changes, the native permission pop-up can only appear after the user interacts with the page (e.g., by clicking a button). To meet this requirement, Pushwoosh displays a [Subscription Prompt widget](https://docs.pushwoosh.com/developer/guides/messaging-channels/subscription-prompt/) by default. This widget encourages users to opt in and, upon agreement, triggers the native browser prompt. Tip A well-designed prompt explaining the value of notifications (e.g., “Get the latest news and updates”) can significantly improve opt-in rates. To customize the prompt text and appearance, click **Settings**. ![Configure the Subscription prompt](https://docs.pushwoosh.com/web-configuration-16.webp) #### Prompt types There are two types of subscription prompts available: * **Default widget** Provided by Pushwoosh and displayed automatically. [Learn how to customize the default widget](https://docs.pushwoosh.com/developer/guides/messaging-channels/subscription-prompt/default-widget/). * **Custom widget** Use your own widget design. [Learn more](https://docs.pushwoosh.com/developer/guides/messaging-channels/subscription-prompt/custom-subscription-widget/) > **Note:** Due to platform limitations, changes to the widget may take up to 30 minutes to appear. If changes are not reflected, contact the Pushwoosh Support team. ### Safari Configuration (macOS 10.14–12) To support push notifications on older versions of Safari (macOS 10.14–12), you need to complete a separate configuration process using your Apple Developer credentials. This step is only required for these older versions as newer Safari versions (macOS Ventura and later) support the standard web push setup included in the [All Browsers Configuration](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/web-push-configuration/#configure-web-push-for-all-browsers-except-older-safari-versions). #### Get the required credentials from Apple 1. Go to [Certificates, Identifiers & Profiles section](https://developer.apple.com/account/overview.action) of Apple Developer Portal. 2. Add new certificate. ![Add new certificate option in Apple Developer Portal](https://docs.pushwoosh.com/web-configuration-13.webp) 3. Choose **Website Push ID Certificate** type and click **Continue**. ![Website Push ID Certificate type selection in Apple Developer Portal](https://docs.pushwoosh.com/web-configuration-14.webp) 4. Select the **Website Push ID** - your unique reverse-domain string, such as *web.com.example.domain* (must start with *web.*). ![Website Push ID selection in Apple Developer Portal](https://docs.pushwoosh.com/configure-project-safari-configuration-4.webp) 5. Upload a **Certificate Signing Request**. To learn more on creating Certificate Signing Requests, please refer to the [Developer Account Help article](https://developer.apple.com/help/account/create-certificates/create-a-certificate-signing-request). 6. Afterwards, download the push notification certificate. ![Download push notification certificate from Apple Developer Portal](https://docs.pushwoosh.com/web-configuration-15.webp) Note The certificate you download from Apple is a **.cer** file. To get the **.p12** file necessary to configure Pushwoosh, you must export a private key. See details in the [iOS Configuration guide](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-platform-configuration/). #### Configure Safari in Pushwoosh 1. Click **Configure** under **Safari Configuration**. ![Configure Safari in Pushwoosh](https://docs.pushwoosh.com/web-configuration-11.webp) 2. Fill in the following fields in the configuration form: | | | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **Website name** | The name of your website that appears in the push prompt. | | **Allowed domains** | List of domains allowed to request notification permission (one per line). | | **URL template** | URL opened when a user clicks the notification. Supports placeholders like `%@`to insert dynamic values. Example: `https://yourwebsite.com/%@` | | **Website icon** | Upload a square PNG image (256×256 px). Pushwoosh resizes it automatically for different interfaces. | | **Key file** | Upload the `.p12` certificate exported from your Apple Developer account. | | **Private key password** | Password used when exporting the `.p12` file. | ![Fill in the Safari configuration form](https://docs.pushwoosh.com/web-configuration-12.webp) 3. Click **Configure** to save your changes. Pushwoosh will automatically generate the push package with the icon set, website JSON dictionary, and the manifest file that Safari requests from the server. You can download it whenever you need. Important When a user is asked for permission to receive push notifications, Safari asks Pushwoosh’s web server for a `push package`. The package contains data used by the notification UI, such as your website name and icon, as well as a cryptographic signature that verifies that your notification is coming from a trusted source: you. **Push package with all its content is downloaded ONLY ONCE by each subscribed user upon registration, and cannot be force-updated on devices.** Consider this when launching Safari push notifications for your website in production. --- # Windows configuration **URL:** https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/windows-configuration/ Step-by-step guide to configure Windows platform for push notifications in Pushwoosh using WNS authentication with Package Security ID and Client Secret. --- Note #### Supports Windows 8.1, Windows 10, and Windows 11 ## WNS authentication First, authenticate your application with Windows Push Notification Service according to the Microsoft Dev Center guide [here](https://msdn.microsoft.com/en-us/library/windows/apps/hh465407.aspx). ## Pushwoosh configuration 1. In your Pushwoosh project, navigate to **Configure Platforms** and click **Connect** next to **Windows**. ![Pushwoosh platform configuration screen showing the Windows platform with a Connect button.](https://docs.pushwoosh.com/configure-project-windows-configuration-1.webp) 2. Specify your **Package Security ID** and **Client Secret** in the configuration window and click **Save**. ![Windows platform configuration form with fields for Package Security ID and Client Secret.](https://docs.pushwoosh.com/configure-project-windows-configuration-2.webp) ## Templates Check out these Windows Templates: [Windows Tile Template](http://msdn.microsoft.com/en-us/library/windows/apps/hh761491.aspx) [Windows Toast Template](http://msdn.microsoft.com/en-us/library/windows/apps/hh761494.aspx) [Windows Badge Template](http://msdn.microsoft.com/en-us/library/windows/apps/hh779719.aspx) --- # Integrate Pushwoosh SDK **URL:** https://docs.pushwoosh.com/developer/first-steps/integrate-pushwoosh-sdk/ Learn how to integrate Pushwoosh SDK into your app, website, or cross-platform project to enable push notifications, user tracking, and messaging functionality. --- Pushwoosh SDK, being integrated into your mobile app or website, enables all the functionality Pushwoosh provides for your project: registering users, tracking their behavior, sending messages, gathering stats, etc. Once integrated, Pushwoosh SDK starts collecting data about your users and their interactions with the app or website — to enable this, set up Events (see the [Events](https://docs.pushwoosh.com/developer/guides/audience-and-segmentation/events/) guide). Every user and device with your app installed can be tagged — see the [Tags](https://docs.pushwoosh.com/developer/guides/audience-and-segmentation/tags/) guide to learn more. Users’ tags are applied for segmentation purposes letting you send entirely relevant messages based on what users do and who they are. The SDK provides sending messages to your audience and tracks all your marketing activities, including the number of push and email subscribers, messages you send and their efficiency metrics, variety of users and their data, etc. [Learn more about Pushwoosh SDK](https://docs.pushwoosh.com/developer/pushwoosh-sdk/pushwoosh-sdk-overview) To integrate the SDK into your app or site, follow the how-to guides: * [iOS SDK](https://docs.pushwoosh.com/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-ios-sdk/quick-start/) * [Android SDK](https://docs.pushwoosh.com/developer/pushwoosh-sdk/android-sdk/firebase-integration/integrate-pushwoosh-android-sdk/) * [Web Push SDK 3.0](https://docs.pushwoosh.com/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/) * [Windows SDK](https://docs.pushwoosh.com/developer/pushwoosh-sdk/windows/windows-sdk-integration/) * [Mac OS X SDK](https://docs.pushwoosh.com/developer/pushwoosh-sdk/os-x/) If your project is built with a cross-platform framework, choose an appropriate SDK from the list available: * [Cordova](https://docs.pushwoosh.com/developer/pushwoosh-sdk/cross-platform-frameworks/cordova/integrating-cordova-plugin/) * [Flutter](https://docs.pushwoosh.com/developer/pushwoosh-sdk/cross-platform-frameworks/flutter/) * [MAUI Dotnet](https://docs.pushwoosh.com/developer/pushwoosh-sdk/cross-platform-frameworks/maui-dotnet/) * [Outsystems](https://docs.pushwoosh.com/developer/pushwoosh-sdk/cross-platform-frameworks/outsystems/huawei-for-outsystems/) * [React Native](https://docs.pushwoosh.com/developer/pushwoosh-sdk/cross-platform-frameworks/react-native/integration/integrating-react-native-plugin/) * [Unity](https://docs.pushwoosh.com/developer/pushwoosh-sdk/cross-platform-frameworks/unity/) --- # Project setup guide **URL:** https://docs.pushwoosh.com/developer/first-steps/start-with-your-project/ Learn how to set up your Pushwoosh project and configure messaging channels such as Push, In-App, Email, WhatsApp, LINE, Kakao, SMS, and Apple and Google Wallet passes using SDKs and APIs. --- This guide outlines the steps to set up your Pushwoosh project and messaging channels such as push notifications, message inbox, in-app messaging, email, WhatsApp, LINE, Kakao, SMS, and Apple and Google Wallet passes. Depending on the channel, you’ll configure platform settings, integrate SDKs (if required), and register user data. Once a channel is configured, you can start sending messages through the Pushwoosh Control Panel or via the API. ## Prerequisites Before you start working with any communication channel, complete these steps: * **Create a Pushwoosh account** * **Use your default project or create a new one** A default project (**My project**) is created when you register. Use it for one app across multiple platforms, or create separate projects for different apps [Learn how to create a project ](https://docs.pushwoosh.com/product/first-steps/start-with-your-project/create-your-project/) ## Set up messaging channels ### Push notifications Send timely and personalized alerts to users across mobile and web platforms. To enable push notifications: 1. **Configure your platform** Set up credentials for iOS, Android, Huawei, and Web. [Learn more](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/configure-project/) 2. **Integrate the SDK** Add the Pushwoosh SDK to your app or website. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/pushwoosh-sdk-overview/) 3. **Test the integration and publish your app or website** Ensure push functionality works as expected. * For apps, release the version with integrated SDK to the app stores. For websites, just update your live site. [Learn more](https://docs.pushwoosh.com/developer/first-steps/test-your-integration/test-devices/) 4. **Register users** Subscribe devices and sync user data to enable push delivery. [Learn more](https://docs.pushwoosh.com/developer/first-steps/subscribe-users/) 5. **Set custom User IDs** Assign a custom User ID to unify a person’s devices/contacts under one profile. [Learn more](https://docs.pushwoosh.com/developer/first-steps/collecting-user-ids/) Once the setup is complete, you can start [sending push notifications via the Control Panel](https://docs.pushwoosh.com/product/messaging-channels/push-notifications/#start-sending-different-types-of-push-notifications) or use the [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) API method. ### Message inbox Store important messages in a dedicated in-app space to reach users even if they opt out of push notifications. To enable Message inbox: 1. **Configure platforms** Set up your app for push messaging on supported platforms. [Learn more](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/configure-project/) 2. **Integrate the SDK** Add Pushwoosh SDK to your app to enable inbox functionality. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/pushwoosh-sdk-overview/) 3. **Register users** Sync user data to allow inbox message delivery. [Learn more](https://docs.pushwoosh.com/developer/first-steps/subscribe-users/) 4. **Set custom User IDs** Assign a custom User ID to unify a person’s devices/contacts under one profile. [Learn more](https://docs.pushwoosh.com/developer/first-steps/collecting-user-ids/) 5. **Implement Message inbox** Follow platform-specific guides to implement inbox UI. [Learn more](https://docs.pushwoosh.com/developer/guides/message-inbox/) 6. **Customize the UI (optional)** Customize the inbox appearance as needed. [Learn more](https://docs.pushwoosh.com/developer/guides/message-inbox/) Once integration is complete, you can deliver inbox messages using [Pushwoosh Customer Journey](https://docs.pushwoosh.com/product/customer-journey/journey-elements/#save-to-inbox) or the [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) API method. ### In-app messages Display contextual messages directly inside your app. To enable in-app messaging: 1. **Configure your platform** Ensure your app supports in-app messaging. [Learn more](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/configure-project/) 2. **Integrate the SDK** Required for in-app message delivery. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/pushwoosh-sdk-overview/) 3. **Test the integration and publish your app** Ensure in-app functionality works as expected and release the version with the integrated SDK to the app stores. [Learn more](https://docs.pushwoosh.com/developer/first-steps/test-your-integration/) 4. **Register users** Ensure devices are subscribed and user data is synced. [Learn more](https://docs.pushwoosh.com/developer/first-steps/subscribe-users/) 5. **Set custom User IDs** Assign a custom User ID to unify a person’s devices/contacts under one profile. [Learn more](https://docs.pushwoosh.com/developer/first-steps/collecting-user-ids/) After setup, you can send in-app messages via [Customer Journey](https://docs.pushwoosh.com/product/messaging-channels/in-apps/sending-in-apps/#send-in-apps-via-customer-journey) or use the [Instant in-apps](https://docs.pushwoosh.com/product/messaging-channels/in-apps/sending-in-apps/#send-instant-in-apps) functionality. ### Emails Reach your users with personalized email campaigns or transactional messages. To start sending emails: 1. **Configure email platform** Authenticate your domain and sender address. [Learn more](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/email-verification/) 2. **Register users** Import and sync user email addresses. [Learn more](https://docs.pushwoosh.com/developer/first-steps/subscribe-users/) 3. **Set custom User IDs** Assign a custom User ID to unify a person’s devices/contacts under one profile. [Learn more](https://docs.pushwoosh.com/developer/first-steps/collecting-user-ids/) Once setup is complete, you can start sending emails using the Pushwoosh Control Panel or the [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) method. ### WhatsApp Engage users on one of the world’s most widely used messaging apps, delivering secure and approved messages that drive meaningful interactions. To enable WhatsApp messaging: 1. **Connect your WhatsApp Business account** [Learn more](https://docs.pushwoosh.com/product/first-steps/start-with-your-project/configure-platforms/whatsapp-configuration/) 2. **Approve templates** Submit your own templates to Meta or use pre-approved ones. [Learn more](https://docs.pushwoosh.com/product/messaging-channels/whatsapp-messages/#create-whatsapp-templates) 3. **Register WhatsApp contacts** [Learn more](https://docs.pushwoosh.com/developer/first-steps/subscribe-users/) 4. **Set custom User IDs** Assign a custom User ID to unify a person’s devices/contacts under one profile. [Learn more](https://docs.pushwoosh.com/developer/first-steps/collecting-user-ids/) Once the integration is ready, you can send WhatsApp messages [using the Control Panel](https://docs.pushwoosh.com/product/messaging-channels/whatsapp-messages/send-whatsapp-messages/) or the [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) API method. ### SMS Send text messages directly to user mobile numbers. To enable SMS: 1. **Connect your SMS provider** [Learn more](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/sms-configuration/) For provider callback URLs, see [SMS provider webhooks](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/sms-configuration/sms-provider-webhooks/). 2. **Register phone numbers** Collect and format numbers correctly (E.164) with user opt-in. [Learn more](https://docs.pushwoosh.com/developer/first-steps/subscribe-users/) 3. **Set custom User IDs** Assign a custom User ID to unify a person’s devices/contacts under one profile. [Learn more](https://docs.pushwoosh.com/developer/first-steps/collecting-user-ids/) After setup, you can send SMS messages using the [Customer Journey](https://docs.pushwoosh.com/product/customer-journey/journey-elements/#sms), or via the [`Notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) API method. ### LINE Use LINE to connect with users via Customer Journeys, API, or 1:1 chat, using either templates or plain-text messages. To start using LINE messaging: 1. **Set up your LINE accounts** Create a [LINE Official Business Account](https://www.linebiz.com/jp-en/) and a [LINE Developers Account](https://developers.line.biz/en/docs/line-developers-console/login-account/). 2. **Connect LINE to Pushwoosh** Configure the LINE platform in your Pushwoosh account. [Learn more](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/line-configuration/) 3. **Make sure LINE Messaging is set up and billing is enabled.** > **Important:** LINE Messaging API pricing is managed directly by LINE. Plans vary by region and usage volume. [View pricing details](https://developers.line.biz/en/docs/messaging-api/pricing/) ##### Next steps * **Send messages via API** Use the Pushwoosh API to send LINE messages with template or plain-text content. [Notify ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) ### Kakao Send Kakao messages via Customer Journeys or API using approved templates to reach users on KakaoTalk. To start using Kakao messaging: 1. **Connect Kakao to Pushwoosh** Configure the Kakao platform in your Pushwoosh account. [Learn more](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/kakao-configuration/) 2. **Create and approve message templates** Use approved Kakao templates; custom templates require approval in the Kakao Business Center. [Learn more](https://docs.pushwoosh.com/product/content/kakao-presets/) ##### Next steps * **Send messages via API** Use the Pushwoosh API to send Kakao messages with approved templates. [Notify ](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/) ### Apple Wallet passes Design Apple Wallet passes, including loyalty cards, coupons, event tickets, and more, and push live updates to every device that added them. To start using Apple Wallet passes: 1. **Configure the signing certificate** Add your Apple Pass Type ID certificate to your application so Pushwoosh can sign passes. [Learn more](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/ios-configuration/ios-wallet-pass-configuration/) 2. **Design and issue a pass** Build a pass in the pass builder, then share it as an install link or QR code. [Learn more](https://docs.pushwoosh.com/product/messaging-channels/apple-wallet-passes/pass-builder/) ##### Next steps * **Learn more about Apple Wallet passes** Design, distribute, and update passes in the Control Panel. [Learn more ](https://docs.pushwoosh.com/product/messaging-channels/apple-wallet-passes/) * **Manage passes via API** Use the PassKit API to create, update, and manage passes programmatically. [Learn more ](https://docs.pushwoosh.com/developer/api-reference/apple-wallet-passkit-api/) ### Google Wallet passes Design Google Wallet passes, including loyalty cards, offers, event tickets, and more, and let Google sync updates to every device that saved them. To start using Google Wallet passes: 1. **Configure Google Wallet in Pushwoosh** Add your Issuer ID and service account key to your application. This setup is independent of Firebase. [Learn more](https://docs.pushwoosh.com/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/) 2. **Design and issue a pass** Build a pass in the pass builder, then share an “Add to Google Wallet” save link or QR code. [Learn more](https://docs.pushwoosh.com/product/messaging-channels/google-wallet-passes/pass-builder/) ##### Next steps * **Distribute, and update passes in the Control Panel** [Learn more ](https://docs.pushwoosh.com/product/messaging-channels/google-wallet-passes/) * **Message pass holders** Reach holders with pass updates, one-time push, or Customer Journey. [Learn more ](https://docs.pushwoosh.com/product/messaging-channels/google-wallet-passes/message-pass-holders/) * **Manage passes via API** Use the Google Wallet API to create passes, issue save links, and send them to users. [Learn more ](https://docs.pushwoosh.com/developer/api-reference/google-wallet-api/) ## Build omnichannel campaigns Once you’ve configured and integrated the necessary messaging channels, you can create omnichannel campaigns to coordinate communication across multiple touchpoints. To enable omnichannel functionality, ensure you register and associate user data (e.g., device ID, email, phone number) under a [unified User ID](https://docs.pushwoosh.com/developer/pushwoosh-knowledge-hub/users-userids/). This allows you to address the same user across channels from a single campaign logic. [Learn more about omnichannel campaigns ](https://docs.pushwoosh.com/product/pushwoosh-knowledge-hub/omnichannel-campaigns/) --- # Register devices in Pushwoosh and sync data with the platform **URL:** https://docs.pushwoosh.com/developer/first-steps/subscribe-users/ Comprehensive guide on registering devices and synchronizing data with Pushwoosh using SDKs, APIs, and third-party integrations. --- To effectively target and engage users through Pushwoosh, it’s crucial to ensure that user devices are properly registered and your data is synchronized. There are several methods for registering devices and synchronizing data with Pushwoosh, depending on your specific needs. ## Pushwoosh SDK ### Mobile For mobile apps, Pushwoosh SDK integration is the recommended method for seamless device registration and data synchronization between the app, Pushwoosh systems, and, optionally, third-party systems that customers may use for specific data pipelines or workflows. By integrating the SDK, you can automate the process of registering devices and handling their push tokens. The SDK internally calls the registerDevice API method, ensuring that every device is registered and synchronized with Pushwoosh without requiring any manual intervention. Additionally, the Pushwoosh SDK allows registering phone numbers for SMS and WhatsApp notifications. You can use the following methods: #### Register an SMS number ##### iOS ```plaintext - (void)registerSmsNumber:(NSString * _Nonnull)number; ``` **Example** ```plaintext Pushwoosh.sharedInstance().registerSmsNumber(@"+0000000000"); ``` Replace `+0000000000` with the actual phone number in **E.164 format** (including the “+” sign and country code). ##### Android ```plaintext Pushwoosh.getInstance().registerSmsNumber(String number); ``` **Example** ```plaintext Pushwoosh.getInstance().registerSmsNumber("+0000000000"); ``` Replace `+0000000000` with the user’s actual phone number in E.164 format, including the “+” and country code. #### Register a WhatsApp number ##### iOS ```plaintext - (void)registerWhatsappNumber:(NSString * _Nonnull)number; ``` **Example** ```plaintext Pushwoosh.sharedInstance().registerWhatsappNumber(@"+0000000000"); ``` Replace `+0000000000` with the actual phone number in **E.164 format** (including the “+” sign and country code). ##### Android To register a user’s phone number for WhatsApp on Android, use the following method: ```plaintext Pushwoosh.getInstance().registerWhatsappNumber(String number); ``` **Example** ```plaintext Pushwoosh.getInstance().registerWhatsappNumber("+0000000000"); ``` Replace `+0000000000` with the user’s actual phone number in E.164 format, including the “+” and country code. ### Web To register devices for web pushes, use the [Web Push SDK](https://docs.pushwoosh.com/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/). Tip To allow your website visitors to opt-in for push notifications, set up either a custom or default [Subscription Prompt](https://docs.pushwoosh.com/developer/guides/messaging-channels/subscription-prompt/) on your site. This prompt triggers the browser’s native subscription request, where users can choose to enable or block web push notifications for your site. [](https://docs.pushwoosh.com/start-with-your-project-subscribe-users-1.webm "Web push subscription prompt example showing browser notification permission request") [Learn more about Pushwoosh SDK](https://docs.pushwoosh.com/developer/pushwoosh-sdk/pushwoosh-sdk-overview) ## Pushwoosh API Also, you can use the **Pushwoosh API** to register devices and synchronize data. The API provides full flexibility for more advanced scenarios. ### Mobile To register mobile devices, use the [`registerDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api/#registerdevice) API method. ### Email Pushwoosh provides built-in subscription forms that you can embed on your website to collect email signups. Learn how to [create and embed a form](https://docs.pushwoosh.com/product/audience-data-and-segmentation/subscription-forms/create-subscription-forms/#how-to-build-a-form) and [customize the widget](https://docs.pushwoosh.com/product/audience-data-and-segmentation/subscription-forms/customize-widget/#customize-colors). After collecting emails, use the [`registerEmail`](https://docs.pushwoosh.com/developer/api-reference/email-api#registeremail) API method to register email devices. Alternatively, you can use [`registerDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api#registerdevice). Note Please note that the [`registerEmailUser`](https://docs.pushwoosh.com/developer/api-reference/email-api#registeremailuser) request does not register an email address in your user base; it should be used only to assign User IDs to emails already registered by the registerEmail call. To associate your app users or site visitors with their email addresses, use the [User IDs](https://docs.pushwoosh.com/developer/pushwoosh-knowledge-hub/users-userids/users-userids). That allows you to build cross-channel Customer Journeys and send emails based on user’s actions in your app or on the website. The User ID will also allow you to view the user’s message and event history in User Explorer. **1**. **Get the User ID.** Each device registered for your Pushwoosh project has its User ID; by default, it’s equal to the device hardware ID (HWID) and is retrieved by the [`registerDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api#registerdevice) API request. To set a custom User ID, call the [`registerUser`](https://docs.pushwoosh.com/developer/api-reference/user-centric-api#registeruser) method. **2. Assign the User ID to an email address.** Use the [`registerEmail`](https://docs.pushwoosh.com/developer/api-reference/email-api#registeremail) or [`registerEmailUser`](https://docs.pushwoosh.com/developer/api-reference/email-api#registeremailuser) API method to associate the User ID with an email address. [Learn more about User IDs](https://docs.pushwoosh.com/developer/pushwoosh-knowledge-hub/users-userids/users-userids) ### SMS To register SMS devices in Pushwoosh, you can use either the [`registerDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api#registerdevice) API method or the [`createSMSMessage`](https://docs.pushwoosh.com/developer/api-reference/sms#createsmsmessage) API method. When using the latter, make sure to set the `use_auto_registration` parameter to `true` in order to automatically register the phone number as an SMS device. [Learn more](https://docs.pushwoosh.com/developer/api-reference/sms#createsmsmessage) ### WhatsApp To register WhatsApp devices in Pushwoosh, you can use either the [`registerDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api#registerdevice) API method or the [`createWhatsAppMessage`](https://docs.pushwoosh.com/developer/api-reference/whatsapp) API method. When using the latter, make sure to set the `use_auto_registration` parameter to `true` in order to automatically register the phone number as a WhatsApp device. ## Importing your existing user base If you’re working with large sets of pre-existing data, you can import this data into Pushwoosh. ### Mobile To migrate your Mobile push subscribers base, please contact us via the [Contact Us form](https://help.pushwoosh.com/hc/en-us/requests/new) and provide a sample of your user base. Our team will review the data format and assess whether the migration is feasible. ### Web Web users cannot be imported due to technical limitations. Different push providers use varying payload formats and platform configurations, making importing web users ineffective. As a result, the imported user base would either be invalidated or receive incorrect or blank content. However, web users who have already given permission to receive push notifications for your website can be resubscribed. [Learn more](https://help.pushwoosh.com/hc/en-us/articles/360018326111-Migrate-your-userbase-to-Pushwoosh/?utm_content=docs&utm_term=post&utm_campaign=migrate-your-userbase-to-pushwoosh) ### Email To [import your email subscriber database](https://docs.pushwoosh.com/product/messaging-channels/emails/get-email-subscribers/#import-email-list), upload a **.csv** file with the email addresses. The emails imported will be registered as subscribers on the email platform. You can also submit additional data for each email address, such as the recipient’s name, gender, or location, to better segment and personalize your email communications. [Import emails](https://app.pushwoosh.com/applications/AEE06-2F522/import-csv/import-emails) ### SMS Import a **.csv** file with phone numbers for SMS subscribers. You can provide additional data, such as the recipient’s name, gender, or location, to further segment and personalize your SMS communications. [Import SMS contacts](https://app.pushwoosh.com/applications/AEE06-2F522/import-csv/import-sms) ### WhatsApp To import your WhatsApp contacts, upload a .csv file with WhatsApp contacts. You can also provide extra details, such as the recipient’s name, gender, or location, to customize your WhatsApp messages. [Import WhatsApp contacts](https://app.pushwoosh.com/applications/AEE06-2F522/import-csv/import-whatsapp) ### Viber To import your Viber contacts, upload a .csv file with Viber contacts. You can also provide extra details, such as the recipient’s name, gender, or location, to customize your Viber messages. [Import Viber contacts](https://app.pushwoosh.com/applications/AEE06-2F522/import-csv/import-viber) ## Using 3rd-party integrations to transfer data In addition to the SDK and API, Pushwoosh offers several third-party integrations to help you synchronize and transfer data from other platforms, making it easier to manage users and data across multiple systems. [Explore all available integrations](https://docs.pushwoosh.com/product/integrations/) --- # Test your integration **URL:** https://docs.pushwoosh.com/developer/first-steps/test-your-integration/ Send a test message to verify your setup. Preview push notifications on test devices and validate journeys with test segments. --- After you integrate the Pushwoosh SDK and connect your messaging channels, register test devices and send a test message to check that everything works. ## Register test devices Test devices let you preview how a message looks before you send it to your audience. Register a separate test device for each channel you want to check. * **Push:** Requires the app with the Pushwoosh SDK installed. Set up QR deep links once, register from the app, or add the device by HWID. [Set up push test devices](https://docs.pushwoosh.com/developer/first-steps/test-your-integration/test-devices/) * **Email:** No app-side integration. Add an email address in Control Panel and confirm it with a verification code. [Set up an email test device](https://docs.pushwoosh.com/product/first-steps/start-with-your-project/test-your-integration/test-devices/#test-email-device) * **SMS:** No app-side integration. Add a phone number in E.164 format in Control Panel and confirm it with a verification code. [Set up an SMS test device](https://docs.pushwoosh.com/product/first-steps/start-with-your-project/test-your-integration/test-devices/#test-sms-device) You can also register devices through the API: * [`createTestDevice`](https://docs.pushwoosh.com/developer/api-reference/test-devices/#createtestdevice): registers a device by push token, without the manual **Create test device** form. * [`listTestDevices`](https://docs.pushwoosh.com/developer/api-reference/test-devices/#listtestdevices): returns the devices already registered for an application. Test devices are application-specific. Configure them separately for each application. ## Send a test message After test devices are registered, send a test in one of these ways: * **Control Panel:** Use the **Test push notification** button in the [Push Preset](https://docs.pushwoosh.com/product/content/presets/#preview-and-save-push-content) form. For email and SMS, send a test from the message form after those test devices are registered. * **API:** Call [`notify`](https://docs.pushwoosh.com/developer/api-reference/messaging-api-v2/notify/#notifytransactional) with `test_devices: true` in the `transactional` block. The message goes to the application’s test devices without opening the Push Preset form. * **Journey:** Build a short [journey](https://docs.pushwoosh.com/product/customer-journey/pushwoosh-journey-overview/) that targets only your testers, then launch it. ### Test a journey with a test segment To test a journey on a limited audience, create a **Segment** of test users, use it as the journey entry, and launch the campaign. 1. Create a **Segment** that includes only test users, by either: * Uploading a CSV file with the necessary conditions. [Learn more](https://docs.pushwoosh.com/product/audience-data-and-segmentation/segmentation/segments/#import-segment) * Assigning a unique Tag value to your test devices by calling the [`/setTags`](https://docs.pushwoosh.com/developer/api-reference/device-api#settags) API method. Then [create a segment](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api/#createfilter) using this Tag value. 2. Go to **Campaigns → Create Campaign → Build a journey from scratch**, or use one of the pre-built customer journey templates. 3. Add the [Audience-based entry](https://docs.pushwoosh.com/product/customer-journey/journey-elements/#audience-based-entry) element to the canvas and select the **Segment** you created. 4. Add a message element such as [push](https://docs.pushwoosh.com/product/customer-journey/journey-elements/#push), [SMS](https://docs.pushwoosh.com/product/customer-journey/journey-elements/#sms), or [email](https://docs.pushwoosh.com/product/customer-journey/journey-elements/#email). 5. Select existing content, or create custom content. 6. Configure the remaining journey elements as needed. 7. Click **Launch Campaign** to start the test. --- # Add test push devices **URL:** https://docs.pushwoosh.com/developer/first-steps/test-your-integration/test-devices/ Learn how to register your device as a test push device in Pushwoosh to preview push notifications before sending them to users. --- You can use Test Devices to preview how push notifications look on a device before sending them to the app users. In order to do that, you need to **register your device** (with your app installed) as a **Test Device**. Note This guide covers push test devices. Email and SMS test devices don’t need any app-side integration — see [Test email device](https://docs.pushwoosh.com/product/first-steps/start-with-your-project/test-your-integration/test-devices/#test-email-device) and [Test SMS device](https://docs.pushwoosh.com/product/first-steps/start-with-your-project/test-your-integration/test-devices/#test-sms-device) in the product docs. To add a test device: 1. Navigate to the **Test devices** section in your Pushwoosh account. ![Test devices section in Pushwoosh account](https://docs.pushwoosh.com/test-your-integration-test-devices-1.webp) 2. Click the **Create test device** dropdown button in the top-right corner and select **Push**. ![Create test device dropdown button with Push option in Test Devices section](https://docs.pushwoosh.com/test-your-integration-test-devices-2.webp) You can add a push test device using one of three methods: Auto-configuration with QR code, registering from the app, or manual configuration. ## Adding test devices automatically This method is suitable only for iOS and Android devices. Before your first registration, add deep link handling for test devices to the app — a one-time setup, usually done together with the Pushwoosh SDK integration: * **For Android**: Add **DeepLinkActivity** to the `AndroidManifest.xml` file. * **For iOS**: Add the `pushwoosh-YOUR_PUSHWOOSH_APP_ID` URL scheme to the `Info.plist` file. Follow the instructions for Android and iOS in the [Implementation section.](https://docs.pushwoosh.com/developer/first-steps/test-your-integration/test-devices#implementation) Once that’s done, to register a device: 1. In the **Test Devices** section, click **Create test device** and select **Push**. 2. Scan the QR code that appears in the popup with any QR scanner app. This opens the deep link that the Pushwoosh SDK parses to register your device as a test device. ![Add Test Device dialog with Auto-configuration QR code on the left and Manual configuration fields for HWID on the right](https://docs.pushwoosh.com/test-your-integration-test-devices-6.webp) Tip for QR Readers Ensure the scanned link opens in the native browser, not the QR reader’s webview. Many QR readers have an “Open in Browser” button for this purpose. ## Registering a test device from the app Independently of the QR code method above, the Pushwoosh SDK can register the current device as a test device on its own: sending the app to the background and bringing it back to the foreground 6 times within 30 seconds. No scanning or manual entry is needed. To prevent unintentional registrations, this only works while a 1-hour registration window is open. 1. In the [Test Devices section](https://docs.pushwoosh.com/product/first-steps/start-with-your-project/test-your-integration/test-devices/#registering-a-test-device-from-the-app), turn on the **Add test devices from the app** toggle. This opens the window for 1 hour. Caution Turning the toggle on requires permission to modify the application; without it, the request fails with a “user cannot modify application” error. The window stays open for 1 hour and then closes automatically; while it’s closed, the app’s registration call still returns success, but no device is registered. ![Test Devices page header with the Add test devices from the app toggle and the Create test device button](https://docs.pushwoosh.com/test-your-integration-test-devices-5.webp) 2. While the window is open, background and foreground the app 6 times within 30 seconds. The device is added to the **Test Devices** list. ## Adding test devices manually If you prefer to register a test device manually, follow these steps: 1. Obtain the **Hardware ID (HWID)** of the device from a successful [`/registerDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api#registerdevice) API call. 2. Fill in the required fields: * **Device Name**: A descriptive name for the test device (e.g., “John’s Android”). * **Device HWID**: The unique hardware ID of the device. * **Device Type**: Select the platform (e.g., iOS, Android, Web). * **Description (Optional)**: Add any notes or details about the device for reference. 3. Click **Save** to register the test device. Once registered, the test device will be available in the **Test Devices** section. ## Registering test devices via API To provision test devices from a script or CI pipeline instead of the manual form, call [`createTestDevice`](https://docs.pushwoosh.com/developer/api-reference/test-devices/#createtestdevice) with the device’s [push token](https://docs.pushwoosh.com/developer/api-reference/api-identifiers/#push-token) — not the HWID used in the manual form, a different identifier obtained the same way, e.g. from a successful [`/registerDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api#registerdevice) call. [`listTestDevices`](https://docs.pushwoosh.com/developer/api-reference/test-devices/#listtestdevices) returns what’s already registered for an application. ## Implementation ### Android 1. [Integrate Pushwoosh SDK](https://docs.pushwoosh.com/developer/pushwoosh-sdk/android-sdk/firebase-integration/integrate-pushwoosh-android-sdk/) with your application. 2. Add **DeepLinkActivity** to your *AndroidManifest.xml*: ```txt ``` Don’t forget to replace *YOUR_PUSHWOOSH_APP_ID* in the xml above with your Pushwoosh App ID.\ Example: ** 3. Launch the application to subscribe for push notifications. 4. Scan the QR Code in **Test Devices** form using any appropriate QR Code scanner app*. A toast message will appear indicating the status of the test device registration. * most of the QR code scanning apps handle such deep links properly, here are just a few of them: * [QR & Barcode Scanner, Gamma Play](https://play.google.com/store/apps/details?id=com.gamma.scan) * [QR & Barcode Scanner, Maker, AppSourceHub](https://play.google.com/store/apps/details?id=qrcode.scanner.qrmaker) ### iOS 1. [Integrate Pushwoosh SDK](https://docs.pushwoosh.com/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-ios-sdk/) with your application. 2. Add *pushwoosh-YOUR_PUSHWOOSH_APP_ID* URL scheme to the *Info.plist* file: ```xml CFBundleURLTypes CFBundleTypeRole Editor CFBundleURLName com.pushwoosh.scheme CFBundleURLSchemes pushwoosh-YOUR_PUSHWOOSH_APP_ID ``` Don’t forget to replace *YOUR_PUSHWOOSH_APP_ID* in the XML above with your Pushwoosh App ID.\ Example: *pushwoosh-ABCDE-EDCBA* Caution **If your project is built with SwiftUI (only), you need to add a SceneDelegate** SwiftUI manages the app lifecycle differently from UIKit. To ensure that certain system events work correctly — like registering a test device for push notifications or handling deep links — you need to explicitly add and register a SceneDelegate. Without it, these events might not be triggered properly, and push registration can fail. If you’re not using SwiftUI, you can skip this step and go directly to **step 3**. **Info.plist** Add `UIApplicationSceneManifest` to your `Info.plist`. ```xml UIApplicationSceneManifest UIApplicationSupportsMultipleScenes UISceneConfigurations UIWindowSceneSessionRoleApplication UISceneConfigurationName UISceneDelegateClassName $(PRODUCT_MODULE_NAME).SceneDelegate ``` **SceneDelegate** Add the `SceneDelegate` code as shown in the example below. ```swift import SwiftUI @main struct DemoApp: App { @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate var body: some Scene { WindowGroup { ContentView() } } } class SceneDelegate: NSObject, UIWindowSceneDelegate { var window: UIWindow? func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) { guard let _ = (scene as? UIWindowScene) else { return } } } class AppDelegate: NSObject, UIApplicationDelegate, PWMessagingDelegate { func application(_ application: UIApplication, configurationForConnecting connectingSceneSession: UISceneSession, options: UIScene.ConnectionOptions) -> UISceneConfiguration { let sceneConfig: UISceneConfiguration = UISceneConfiguration(name: nil, sessionRole: connectingSceneSession.role) sceneConfig.delegateClass = SceneDelegate.self return sceneConfig } } ``` 3. Launch the application to subscribe for push notifications. 4. Scan the QR Code in the **Test Devices** form using any appropriate QR Code scanner. --- # Pushwoosh overview **URL:** https://docs.pushwoosh.com/developer/first-steps/what-is-pushwoosh/ Learn what Pushwoosh is, how it is organized, and how you can leverage the platform to meet your needs through SDK, API, and Control Panel. --- Pushwoosh is an omnichannel customer engagement platform that empowers you to engage users through personalized push notifications, in-app messages, emails, SMS, and WhatsApp messages. The Pushwoosh platform comprises three core components: the SDK, the API, and the Pushwoosh Control Panel. Effective integration involves utilizing all three elements to unleash the platform’s full potential. ## Pushwoosh SDK The Pushwoosh SDK is a comprehensive toolkit for integrating the platform’s capabilities into your applications. When fully integrated, the Pushwoosh SDK can offer a wide range of features and capabilities to enhance your application’s communication and user engagement strategies. * Sends mobile push notifications to iOS, Android, macOS, etc. * Sends web push notifications. * Enables in-app messaging that allows engaging with users directly in the app. * Supports rich media and enhances notifications with images, videos, and interactive buttons. * Delivers important messages in the Message Inbox when push notifications can’t be received. * Uses precise targeting to send notifications based on user behavior, demographics, location, and custom attributes. * Sets up automated workflows that trigger notifications based on predefined schedules or user actions. * Personalize notifications with dynamic content placeholders for user names, preferences, and other custom data. * Send notifications based on user location using geofencing. [Learn more about Pushwoosh SDK](https://docs.pushwoosh.com/developer/pushwoosh-sdk/pushwoosh-sdk-overview) ## Pushwoosh API With Pushwoosh API, you gain access to over 100 methods, allowing you to: * Send personalized push notifications * Manage user segments for precise targeting * Use bulk APIs to handle users/devices in batches * Configure applications * Track user events and add tags for enhanced targeting and personalization * Manage Pushwoosh entities like presets, tags, events, and applications * Start and monitor Pushwoosh Customer Journeys via API * Retrieve detailed statistics on Customer Journeys and Campaigns (Push, Email, SMS) * Implement geofencing for location-based notifications * Integrate seamlessly with 3rd party services For a complete list of methods and capabilities, please refer to the [API Reference Index](https://docs.pushwoosh.com/developer/api-reference/api-methods-reference-index) ## Pushwoosh control panel The Pushwoosh Control Panel is the user interface that manages all data and interactions within the Pushwoosh platform. Marketers use it to create and schedule content, while developers manage settings for app integration, such as API keys and app codes. If you’re just getting started, please make sure you’re added as a user in Pushwoosh. [Learn more](https://docs.pushwoosh.com/product/account-management-and-security/multi-login-accounts#managing-users) --- # How to set up events **URL:** https://docs.pushwoosh.com/developer/guides/audience-and-segmentation/events/ Understand how to configure and post events in Pushwoosh using SDKs or APIs to analyze user actions and personalize messaging. --- **Events** are used to track various actions performed by users in the app. The data from events is stored historically, creating a timeline of user behavior. All the contextual information about the event can be passed as a set of attributes and their values. Once properly collected, this data can be used to: * trigger behavior-based messages; * modify the user communication flow within a Customer Journey based on their behavior; * build segments of users who perform a specific action in the app; * get insights about user flow, usage metrics, and other statistical data. ## Types of events There are two types of events in Pushwoosh: * Default events * Custom events ### Default events Default Events are basic interactions that users perform in apps or websites regardless of their industry or functionality. These key user actions form the core of customer communication and can be leveraged for any product and customer at any stage of the customer lifecycle. Default Events are available out of the box with the latest SDK versions and do not require any additional setup, except for [PW_InAppPurchase](https://docs.pushwoosh.com/product/audience-data-and-segmentation/events/default-events#pw_inapppurchase). Learn more about [Default Events](https://docs.pushwoosh.com/product/audience-data-and-segmentation/events/default-events) ### Custom events Unlike default events, which are universal across many apps and sectors, custom events are the events that you create specifically for your app. These events track specific actions unique to your needs, such as completing a workout or extending a subscription, and help you understand how users interact with your specific features. Custom Events require you to implement them on your side. ## Custom events implementation ### 1. Create events and set attributes All events sent by your app must be created in Pushwoosh first with the set of attributes and their types; otherwise, Pushwoosh will not recognize them. You can ask your marketing team to create events directly in the [Pushwoosh Control Panel](https://docs.pushwoosh.com/product/audience-data-and-segmentation/events#1-create-events-in-pushwoosh-control-panel) or use the [createEvent](https://docs.pushwoosh.com/developer/api-reference/events#createevent) API method. This involves specifying the event name and any associated data that you want to track. ### 2. Call /postEvent API When an event you’d like to track occurs in your app, call the [`/postEvent`](https://docs.pushwoosh.com/developer/api-reference/user-centric-api#postevent) API to send this event to Pushwoosh. #### iOS Call the [`postEvent`](https://docs.pushwoosh.com/developer/api-reference/user-centric-api#postevent) to send an event to Pushwoosh: * Swift ```swift PWInAppManager.shared().postEvent("eventName", withAttributes: nil) ``` * Objective-C ```objective-c [[PushNotificationManager pushManager] postEvent:@“eventName” withAttributes:@{}]; ``` To add details about the event (ref. to Attributes), use the attributes param as follows: * Swift ```swift let attributes: [String : Any] = ["AttributedString" : "someString", "AttributeInt" : 42, "AttributeList" : [123, 456, "someString"], "AttributeBool" : true, "AttributeDate" : NSDate()] PWInAppManager.shared().postEvent("eventName", withAttributes: attributes) ``` * Objective-C ```objective-c NSDictionary *attributes = @{ @"AttributeString" : @"someString", @"AttributeInt" : @(42), @"AttributeList" : @[ @(123), @(456), @"someString" ], @"AttributeBool" : @YES, @"AttributeDate" : [NSDate date] }; [[PushNotificationManager pushManager] postEvent:@“eventName” withAttributes:attributes]; ``` #### Android When an event occurs in your Android app, use the following instructions to send this event to Pushwoosh. Call the [`postEvent`](https://docs.pushwoosh.com/developer/api-reference/user-centric-api#postevent) to send an event to Pushwoosh: ```java PushwooshInApp.getInstance().postEvent("eventName"); ``` To add details about the event (ref. to Attributes), use the attributes param as follows: ```java TagsBundle attributes = new TagsBundle.Builder() .putInt("AttributeInt", 17) .putString("AttributeString", "str") .putDate("AttributeDate", new Date()) .putBoolean("AttributeBool", true) .putList("AttributeList", Arrays.asList("item1", "item2", "item3")) .build(); PushwooshInApp.getInstance().postEvent("eventName", attributes); ``` Note You can also send events from [**In-App Javascript**](https://docs.pushwoosh.com/developer/guides/messaging-channels/inapp-with-javascript/). --- # Custom events examples **URL:** https://docs.pushwoosh.com/developer/guides/audience-and-segmentation/events/custom-events-examples/ Access a comprehensive list of suggested in-app events across multiple app categories, complete with attributes and code samples. --- Below, you’ll find a bunch of in-app events recommended for different app categories. To implement any of these or other events: * [create an Event](https://docs.pushwoosh.com/product/audience-data-and-segmentation/events/#1-create-events-in-pushwoosh-control-panel) in your Pushwoosh Control Panel and add attributes if needed; * integrate the [postEvent](https://docs.pushwoosh.com/developer/api-reference/user-centric-api#postevent) method into your mobile project, providing the name of the event and its attributes exactly as they are in the Control Panel. - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Event name", { // event name exactly as in Control Panel "attribute 1": "string value", // attribute name and type exactly as in Control Panel "attribute 2": "string value" // attribute name and type exactly as in Control Panel }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "attribute 1" : "string value", // attribute name and type exactly as in Control Panel "attribute 2" : "string value" // attribute name and type exactly as in Control Panel ] PWInAppManager.shared().postEvent("Event name", withAttributes: attributes) // event name exactly as in Control Panel ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"attribute 1" : @"string value", // attribute name and type exactly as in Control Panel @"attribute 2" : @"string value" // attribute name and type exactly as in Control Panel }; [[PushNotificationManager pushManager] postEvent:@“eventName” withAttributes:attributes]; // event name exactly as in Control Panel ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("attribute 1", "string value") // attribute name and type exactly as in Control Panel .putString("attribute 2", "string value") // attribute name and type exactly as in Control Panel .build() PushwooshInApp.getInstance().postEvent("Event name", attributes); // event name exactly as in Control Panel ``` Note The samples below can be simply pasted into your app, provided there is a corresponding Event and its attributes are created in your Control Panel. Once integrated, the event data will be collected and become available in Audience -> Events -> Event statistics, and you will be able to use the event in campaign planning. ## Mobile apps ### Log out Trigger this event when users log out of their accounts in your app. Recommended attributes: * user_id: String * date: Date - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Log out", { "user_id": "string value", "date": "date value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "user_id" : "string value", "date" : "date value" ] PWInAppManager.shared().postEvent("Log out", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"user_id" : @"string value", @"date" : @"date value" }; [[PushNotificationManager pushManager] postEvent:@"Log out" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("user_id", "string value") .putString("date", "date value") .build() PushwooshInApp.getInstance().postEvent("Log out", attributes); ``` ### Payment method added Fire this event when a user adds a payment method to their account in your app, e.g. provides card credentials or links the account to a payment system. Recommended attributes: * payment_method: String, * user_id: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Payment method added", { "user_id": "string value", "payment_method": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "user_id" : "string value", "payment_method" : "string value" ] PWInAppManager.shared().postEvent("Payment method added", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"payment_method" : @"string value", @"user_id" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"Payment method added" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("payment_method", "string value") .putString("user_id", "string value") .build() PushwooshInApp.getInstance().postEvent("Payment method added", attributes); ``` ### Payment method changed Send this event when a user updates their payment method in the app. Recommended attributes: * user_id: String, * payment_method: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Payment method changed", { "user_id": "string value", "payment_method": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "user_id" : "string value", "payment_method" : "string value" ] PWInAppManager.shared().postEvent("Payment method changed", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"user_id" : @"string value", @"payment_method" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"Payment method changed" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("user_id", "string value") .putString("payment_method", "string value") .build() PushwooshInApp.getInstance().postEvent("Payment method changed", attributes); ``` ### Button clicked Track button clicks within the app with this event to improve your analytics, test various communication strategies, and increase relevance of your messages based on customer behavior. Recommended event attributes: * user_id: String * button_link: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Button clicked", { "user_id": "string value", "button_link": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "user_id" : "string value", "button_link" : "string value" ] PWInAppManager.shared().postEvent("Button clicked", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"user_id" : @"string value", @"button_link" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"Button clicked" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("user_id", "string value") .putString("button_link", "string value") .build() PushwooshInApp.getInstance().postEvent("Button clicked", attributes); ``` ### Application updated Trigger this event every time a user installs an updated version of your app. Recommended attributes: * previous_app_version: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Application updated", { "previous_app_version": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "previous_app_version" : "string value" ] PWInAppManager.shared().postEvent("Application updated", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"previous_app_version" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"Application updated" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("previous_app_version", "string value") .build() PushwooshInApp.getInstance().postEvent("Application updated", attributes); ``` ### OS updated Fire this event when a user updates their device’s OS version to ensure your app is fully compliant. Recommended attributes: * previous_OS_version: String * new_OS_version: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("OS updated", { "previous_OS_version": "string value", "new_OS_version": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "previous_OS_version" : "string value", "new_OS_version": "string value" ] PWInAppManager.shared().postEvent("OS updated", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"previous_OS_version" : @"string value", @"new_OS_version" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"OS updated" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("previous_OS_version", "string value") .putString("new_OS_version", "string value") .build() PushwooshInApp.getInstance().postEvent("OS updated", attributes); ``` ## E-Commerce ### Product added to cart Fire this event once a user adds product to their cart to build Abandoned Cart campaigns, set user tags, or analyze the efficiency of your promotions. Recommended attributes: * product_id: String * price: Integer * source: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Product added to cart", { "product_id": "string value", "price": 1, "source": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "price" : 1, "product_id" : "string value", "source" : "string value" ] PWInAppManager.shared().postEvent("Product added to cart", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"price" : @(1), @"product_id" : @"string value", @"source" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"Product added to cart" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putInt("price", 1) .putString("product_id", "string value") .putString("source", "string value") .build() PushwooshInApp.getInstance().postEvent("Product added to cart", attributes); ``` ### Discounted purchase Trigger this event once a user purchases any product using a discount coupon. Recommended attributes: * product_id: String * coupon_id: String * price: Integer * discount: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Discounted purchase", { "product_id": "string value", "coupon_id": "string value", "price": 1, "discount": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "product_id" : "string value", "coupon_id" : "string value", "price" : 1, "discount" : "string value" ] PWInAppManager.shared().postEvent("Discounted purchase", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"product_id" : @"string value", @"coupon_id" : @"string value", @"price" : @(1), @"discount" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"Discounted purchase" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("product_id", "string value") .putString("coupon_id", "string value") .putInt("price", 1) .putString("discount", "string value") .build() PushwooshInApp.getInstance().postEvent("Discounted purchase", attributes); ``` ### Product page abandoned Fire this event when a user leaves a product page without a conversion action. Recommended attributes: * product_id: String * price: Integer * source: String * product_page_id: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Product Page abandoned", { "product_id": "string value", "price": 1, "source": "string value", "product_page_id": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "product_id" : "string value", "price" : 1, "source" : "string value", "product_page_id" : "string value" ] PWInAppManager.shared().postEvent("Product Page abandoned", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"product_id" : @"string value", @"price" : @(1), @"source" : @"string value", @"product_page_id" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"Product Page abandoned" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("product_id", "string value") .putInt("price", 1) .putString("source", "string value") .putString("product_page_id", "string value") .build() PushwooshInApp.getInstance().postEvent("Product Page abandoned", attributes); ``` ### Product added to wishlist Stay informed of the products that users have saved to their wishlists and create personal offers and promo campaigns. Recommended attributes: * product_id: String * wishlist_id: String * product_price: Integer * source: String * user_id: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Product added to wishlist", { "product_id": "string value", "currency": "string value", "price": 1, "source": "string value", "user_id": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "product_id" : "string value", "wishlist_id" : "string value", "product_price" : 1, "source" : "string value", "user_id" : "string value" ] PWInAppManager.shared().postEvent("Product added to wishlist", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"product_id" : @"string value", @"wishlist_id" : @"string value", @"product_price" : @(1), @"source" : @"string value", @"user_id" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"Product added to wishlist" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("product_id", "string value") .putString("wishlist_id", "string value") .putInt("product_price", 1) .putString("source", "string value") .putString("user_id", "string value") .build() PushwooshInApp.getInstance().postEvent("Product added to wishlist", attributes); ``` ### Product removed from wishlist Fire this event when a user deletes a product from their wishlist. Recommended attributes: * user_id: String * wishlist_id: String * product_id: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Product removed from wishlist", { "wishlist_id": "string value", "user_id": "string value", "product_id": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "wishlist_id" : "string value", "user_id" : "string value", "product_id" : "string value" ] PWInAppManager.shared().postEvent("Product removed from wishlist", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"wishlist_id" : @"string value", @"user_id" : @"string value", @"product_id" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"Product removed from wishlist" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("wishlist_id", "string value") .putString("user_id", "string value") .putString("product_id", "string value") .build() PushwooshInApp.getInstance().postEvent("Product removed from wishlist", attributes); ``` ### Product category Send this event when a user purchases a product of a specific category. Recommended attributes: * product_id: String * product_category: String * currency: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Product category", { "product_id": "string value", "product_category": "string value", "currency": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "product_id" : "string value", "product_category" : "string value", "currency" : "string value" ] PWInAppManager.shared().postEvent("Product category", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"product_id" : @"string value", @"product_category" : @"string value", @"currency" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"Product category" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("product_id", "string value") .putString("product_category", "string value") .putString("currency", "string value") .build() PushwooshInApp.getInstance().postEvent("Product category", attributes); ``` ### First purchase Trigger this event once a user makes their first purchase. Recommended attributes: * product_id: String, * category: String * date: Date - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("First purchase", { "product_id": "string value", "category": "string value", "date": "date value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "product_id" : "string value", "category" : "string value", "date" : "date value" ] PWInAppManager.shared().postEvent("First purchase", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"product_id" : @"string value", @"category" : @"string value", @"date" : @"date value" }; [[PushNotificationManager pushManager] postEvent:@"First purchase" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("product_id", "string value") .putString("category", "string value") .putBoolean("date", "date value") .build() PushwooshInApp.getInstance().postEvent("First purchase", attributes); ``` ## Gaming Apps ### New level When a user reaches a new game level, trigger the New level event. Recommended attributes: * level_id: String * user_id: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("New level", { "level_id": "string value", "user_id": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "level_id" : "string value", "user_id" : "string value" ] PWInAppManager.shared().postEvent("New level", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"level_id" : @"string value", @"user_id" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"New level" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("level_id", "string value") .putString("user_id", "string value") .build() PushwooshInApp.getInstance().postEvent("New level", attributes); ``` ### Level completed Send this event when a user completes a particular game level. Recommended attributes: * level_id: String * user_id: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Level completed", { "level_id": "string value", "user_id": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "level_id" : "string value", "user_id" : "string value" ] PWInAppManager.shared().postEvent("Level completed", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"level_id" : @"string value", @"user_id" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"Level completed" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("level_id", "string value") .putString("user_id", "string value") .build() PushwooshInApp.getInstance().postEvent("Level completed", attributes); ``` ### Virtual currency earned Fire this event when a user’s virtual currency balance tops up. Recommended attributes: * currency_name: String * quantity: Integer * user_id: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Virtual currency earned", { "currency_name": "string value", "quantity": 1, "user_id": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "currency_name" : "string value", "quantity" : 1, "user_id" : "string value" ] PWInAppManager.shared().postEvent("Virtual currency earned", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"currency_name" : @"string value", @"quantity" : @(1), @"user_id" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"Virtual currency earned" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("currency_name", "string value") .putInt("quantity", 1) .putString("user_id", "string value") .build() PushwooshInApp.getInstance().postEvent("Virtual currency earned", attributes); ``` ### Tutorial completed Trigger this event when a user completes the in-game tutorial. Recommended attributes: * tutorial_name: String * completion: Boolean - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Tutorial completed", { "tutorial_name": "string value", "completion": true }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "tutorial_name" : "string value", "completion" : true ] PWInAppManager.shared().postEvent("Tutorial completed", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"tutorial_name" : @"string value", @"completion" : @YES }; [[PushNotificationManager pushManager] postEvent:@"Tutorial completed" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("tutorial_name", "string value") .putBoolean("completion", true) .build() PushwooshInApp.getInstance().postEvent("Tutorial completed", attributes); ``` ### Achievement unlocked Monitor user engagement with the event fired when a user unlocks a specific achievement. Recommended attributes: * achievement_name: String * level: Integer * user_id: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Achievement unlocked", { "achievement_name": "string value", "level": 5, "user_id": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "achievement_name" : "string value", "level" : 5, "user_id": "string value" ] PWInAppManager.shared().postEvent("Achievement unlocked", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"achievement_name" : @"string value", @"level" : @1, @"user_id" : "string value" }; [[PushNotificationManager pushManager] postEvent:@"Achievement unlocked" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("achievemnt_name", "string value") .putString("level", 1) .putString("user_id", "string value) .build() PushwooshInApp.getInstance().postEvent("Achievement unlocked", attributes); ``` ## Subscription Management ### Paid subscription purchase Send this event when a user has bought a paid subscription plan. Recommended attributes: * subscription_plan_name: String * price: Integer * currency:String * expiry_date:Date - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Paid subscription purchase", { "subscription_plan_name": "string value", "price": 1, "currency": "string value", "expiry_date": "new Date()" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "subscription_plan_name" : "string value", "price" : 1, "currency" : "string value", "expiry_date" : NSDate() ] PWInAppManager.shared().postEvent("Paid subscription purchase", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"subscription_plan_name" : @"string value", @"price" : @(1), @"currency" : @"string value", @"expiry_date" : [NSDate date] }; [[PushNotificationManager pushManager] postEvent:@"Paid subscription purchase" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("subscription_plan_name", "string value") .putInt("price", 1) .putString("currency", "string value") .putDate("expiry_date", new Date()) .build() PushwooshInApp.getInstance().postEvent("Paid subscription purchase", attributes); ``` ### Subscription renewal Trigger this event once a user renews their subscription plan. Recommended attributes: * subscription_plan_name: String * price: Integer * currency: String * renewal_count: Integer - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Subscription renewal", { "subscription_plan_name": "string value", "price": 1, "currency": "string value", "renewal_count": 1 }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "subscription_plan_name" : "string value", "price" : 1, "currency" : "string value", "renewal_count" : 1 ] PWInAppManager.shared().postEvent("Subscription renewal", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"subscription_plan_name" : @"string value", @"price" : @(1), @"currency" : @"string value", @"renewal_count" : @(1) }; [[PushNotificationManager pushManager] postEvent:@"Subscription renewal" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("subscription_plan_name", "string value") .putInt("price", 1) .putString("currency", "string value") .putInt("renewal_count", 1) .build() PushwooshInApp.getInstance().postEvent("Subscription renewal", attributes); ``` ### Free trial started Trigger this event when a user chooses to start a free trial before getting a subscription. Recommended attributes: * free_trial_name: String * expiry_date: Date - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Free trial started", { "free_trial_name": "string value", "expiry_date": "new Date()" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "free_trial_name" : "string value", "expiry_date" : NSDate() ] PWInAppManager.shared().postEvent("Free trial started", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"free_trial_name" : @"string value", @"expiry_date" : [NSDate date] }; [[PushNotificationManager pushManager] postEvent:@"Free trial started" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("free_trial_name", "string value") .putDate("expiry_date", new Date()) .build() PushwooshInApp.getInstance().postEvent("Free trial started", attributes); ``` ### Subscription canceled Use this event to track in-app subscription cancelations. * JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Subscription cancelled"); }); ``` * Swift ```swift // To use with iOS SDK, you can integrate this code: PWInAppManager.shared().postEvent("Subscription cancelled", withAttributes: nil) ``` * Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: [[PushNotificationManager pushManager] postEvent:@"Subscription canceled" withAttributes:@{}]; ``` * Java ```java // To use with Android SDK, you can integrate this code: PushwooshInApp.getInstance().postEvent("Subscription cancelled"); ``` ### Conversion from Free to Paid Trigger this event once a user converts from using your app for free to a paid subscription plan. Recommended attributes: * subscription_plan_name: String * price: Integer * currency: String * date: Date - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Conversion from Free to Paid", { "subscription_plan_name": "string value", "price": 1, "currency": "string value", "date": "new Date()" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "plan_name" : "string value", "price" : 1, "currency" : "string value", "date" : NSDate() ] PWInAppManager.shared().postEvent("Conversion from Free to Paid", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"subscription_plan_name" : @"string value", @"price" : @(1), @"currency" : @"string value", @"date" : [NSDate date] }; [[PushNotificationManager pushManager] postEvent:@"Conversion from Free to Paid" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("subscription_plan_name", "string value") .putInt("price", 1) .putString("currency", "string value") .putDate("date", new Date()) .build() PushwooshInApp.getInstance().postEvent("Conversion from Free to Paid", attributes); ``` ## Media ### Search Send this event when a user searches for any content in your app. Recommended attributes: * search_query: String * category: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Search", { "search_query": "string value", "category": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "search_query" : "string value", "category" : "string value" ] PWInAppManager.shared().postEvent("Search", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"search_query" : @"string value", @"category" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"Search" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("search_query", "string value") .putString("category", "string value") .build() PushwooshInApp.getInstance().postEvent("Search", attributes); ``` ### Content read Trigger this event when a user has read a specific piece of content. Recommended attributes: * category: String * article_id: String * author: String * published_date: Date - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Content read", { "category": "string value", "article_id": "string value", "author": "string value", "published_date": "new Date()" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "category" : "string value", "article_id" : "string value", "author" : "string value", "published_date" : NSDate() ] PWInAppManager.shared().postEvent("Content read", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"category" : @"string value", @"article_id" : @"string value", @"author" : @"string value", @"published_date" : [NSDate date] }; [[PushNotificationManager pushManager] postEvent:@"Content read" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("category", "string value") .putString("article_id", "string value") .putString("author", "string value") .putDate("published_date", new Date()) .build() PushwooshInApp.getInstance().postEvent("Content read", attributes); ``` ### Form submission Track submissions of your in-app forms (for example, Net Promoter Score), the choice of content preferences, and other surveys. Recommended attributes: * form_name: String * url: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Form submission", { "form_name": "string value", "url": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "form_name" : "string value", "url" : "string value" ] PWInAppManager.shared().postEvent("Form submission", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"form_name" : @"string value", @"url" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"Form submission" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("form_name", "string value") .putString("url", "string value") .build() PushwooshInApp.getInstance().postEvent("Form submission", attributes); ``` ### Content shared Trigger this event when a user has shared a piece of content via social networks, email or other channels. Recommended attributes: * category: String * article_id: String * author: String * published_date: Date * button_id: String * social_media: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Content shared", { "category": "string value", "article_id": "string value", "author": "string value", "published_date": "new Date()", "button_id": "string value", "social_media": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "category" : "string value", "article_id" : "string value", "author" : "string value", "published_date" : NSDate(), "button_id" : "string value", "social_media" : "string value" ] PWInAppManager.shared().postEvent("Content shared", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"category" : @"string value", @"article_id" : @"string value", @"author" : @"string value", @"published_date" : [NSDate date], @"button_id" : @"string value", @"social_media" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"Content shared" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("category", "string value") .putString("article_id", "string value") .putString("author", "string value") .putDate("published_date", new Date()) .putString("button_id", "string value") .putString("social_media", "string value") .build() PushwooshInApp.getInstance().postEvent("Content shared", attributes); ``` ### Content preferences Fire this event when a user chooses a specific topic they are interested in. Recommended attributes: * topic: String - JavaScript ```javascript // To use with Web Push SDK, you can integrate this code: const Pushwoosh = window.Pushwoosh || []; Pushwoosh.push(function(api) { api.postEvent("Content preferences", { "topic": "string value" }); }); ``` - Swift ```swift // To use with iOS SDK, you can integrate this code: let attributes: [String : Any] = [ "topic" : "string value" ] PWInAppManager.shared().postEvent("Content preferences", withAttributes: attributes) ``` - Objective-C ```objective-c // To use with iOS SDK, you can integrate this code: NSDictionary *attributes = @{ @"topic" : @"string value" }; [[PushNotificationManager pushManager] postEvent:@"Content preferences" withAttributes:attributes]; ``` - Java ```java // To use with Android SDK, you can integrate this code: TagsBundle attributes = new TagsBundle.Builder() .putString("topic", "string value") .build() PushwooshInApp.getInstance().postEvent("Content preferences", attributes); ``` --- # Tags **URL:** https://docs.pushwoosh.com/developer/guides/audience-and-segmentation/tags/ Learn how to use tags in Pushwoosh to segment your audience and send targeted push notifications to specific users based on their attributes and behavior. --- Tags are one of the most useful tools Pushwoosh offers, enabling a range of sophisticated functionality. By using tags, you can segment your audience and send targeted push notifications to specific users based on their attributes. Tags can contain any arbitrary data associated with a particular user or device. This data might include usernames, IDs, cities, favorite football teams, preferred news categories, or any other relevant information about your users. ## Deciding which tags to use Start by identifying your business needs and determining how you want to segment your audience. Consider factors such as age, location, in-app purchase history, or any other relevant criteria for targeting users. Tip The marketing team may need to be involved in this process to help decide which tags best align with your marketing goals and audience segmentation strategies. ## Tag values Tag values can help you make your push campaigns smarter. Each tag is capable of storing *nearly limitless number of values*. Basically, this means that one tag would be enough to record a specific type of information about each end-user in your database. There are only a few tags available for each account, but considering the nearly-infinite space for each tag, just a couple of tags are enough to gather an enormous amount of information about your users and set up very complex targeting patterns. ## Types of tags * **Integer** — used for the integer data (amount of in-game cash acquired, level achieved, age). * **String** — used for string values (username, e-mail, identifiers). * **List** — the same as String type, but each user may have multiple values set simultaneously (music preferences, news categories, cuisine preferences). * **Boolean** — true / false type of Tag. * **Date** — used for calendar dates. Basically, this is an integer type tag which stores Unix Epoch timestamps (automatically converted from/into Gregorian date). * **Price** — allows to set values according to specified currency in the “*.XX” format [Learn more](https://en.wikipedia.org/wiki/ISO_4217). * **Version** — used for versioning. The example of allowed format is w.x.y.z (Major.Minor.Patch.Build). Max value for each version part is 9999, so the max version number cannot be greater than 9999.9999.9999.9999. ### Tag operators Each Tag type has a specific set of **operators** applicable. Tag operators define the relationship between the Tag and its values for segmentation purposes. * Integer Tag operators: `is`, `is not`, `are`, `not in`, `not set`, `any` * String Tag operators: `is`, `is not`, `are`, `not in`, `not set`, `any` * List Tag operators: `in`, `not in`, `not set`, `any` * Boolean Tag operators: `is` (true/false), `not set`, `any` * Date Tag operators: `exactly on`, `on or after`, `on or before`, `between`, `not set`, `any` * Price Tag operators: `is`, `is not`, `greater or equals`, `less or equals`, `between`, `in`, `not in`, `not set`, `any` * Version Tag operators: `is`, `is not`, `greater or equals`, `less or equals`, `between`, `in`, `not in`, `not set`, `any` Note “Not set” and “any” operators are available for all types of Tags. ## Tag scope: General vs User-specific When creating a tag, you choose how its values are stored: * **General** (default, `user_specific: false`): the tag value is stored per device (HWID). Each device of the same user can hold a different value independently. * **User-specific** (`user_specific: true`): the tag value is stored per user (UserID). When set via UserID, the value is applied to all of the user’s devices at once. Useful for attributes that belong to the person, not a particular device: subscription tier, loyalty points, preferred language. ### Example A user has both the iOS and Android versions of your app installed. Setting a `subscription_tier` tag to `"premium"` via their UserID applies it to both devices immediately. With a General tag you would need to set it per device separately. Example: set a user-specific tag via UserID ```javascript { "request":{ "application": "XXXXX-XXXXX", "userId": "the id of a specific user", "tags": { "subscription_tier": "premium", "loyalty_points": 350 } } } ``` ## Default tags These tags are available by Pushwoosh out-of-the-box, so you don’t have to (and, in fact, should not) set them manually. Most of them are set from the application and sent over to our server via [`registerDevice`](https://docs.pushwoosh.com/developer/api-reference/device-api/) and other API calls, and some are set by the server itself. | Name | Type | Where it’s set | Description | | ----------------------------- | ------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Application Version | Version | SDK | Current version of the app installed on a device | | Browser Type | String | SDK | When a device is registered for your web project, its type – mobile or desktop – is tracked automatically | | City | String | Server | Latest registered geographical location of a device | | Country | String | Server | Latest registered geographical location of a device | | Device Model | String | SDK | Indicates the device model whereon the app is installed | | First Install | Date | Server | Indicates the time when a device was registered for notifications for the first time | | In-App Product | List | SDK | The in-app products purchased by a user of the app | | Last In-App Purchase Date | Date | SDK | The date of the latest in-app purchase made on a device | | Language | String | SDK | Two-letter lowercase abbreviation of a device’s locale according to ISO-639-1; taken from device settings | | Last Application Open | Date | Server | The time of the most recent app launch on a device | | Last Email Open | Date | Server | The date when the device’s email address most recently registered an email open event | | Last Email Open Message Code | String | Server | [Message code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers#message-code) of the most recently opened email (format `XXXX-XXXXXXXX-XXXXXXXX`). Updated on each [`PW_EmailOpen`](https://docs.pushwoosh.com/product/audience-data-and-segmentation/events/default-events/#pw_emailopen) event. Use it to segment recipients of a specific email campaign by who opened it | | Last Email Click | Date | Server | The date when the device’s email address most recently registered an email link click | | Last Email Click Message Code | String | Server | [Message code](https://docs.pushwoosh.com/developer/api-reference/api-identifiers#message-code) of the most recent email in which a link was clicked (format `XXXX-XXXXXXXX-XXXXXXXX`). Updated on each [`PW_EmailLinkClicked`](https://docs.pushwoosh.com/product/audience-data-and-segmentation/events/default-events/#pw_emaillinkclicked) event. Use it to segment recipients of a specific email campaign by who clicked | | Last Email Confirm | Date | Server | The date of the most recent Double Opt-In subscription confirmation for the device’s email address | | Bounced Email | Date | Server | The date when a hard bounce occurred for this email address. Stored as Date to enable time-based segmentation, for example, to exclude users with recent bounces | | Unsubscribed Emails | Boolean | SDK | Indicates whether a user has unsubscribed from receiving emails from your app | | OS Version | Version | SDK | The version of an operating system running on a device | | Platform | String | SDK | The platform on which the user is using your project. | | Push Alerts Enabled | Boolean | SDK | Indicates whether push alerts are allowed in device settings | | SDK Version | Version | SDK | The version of the Pushwoosh SDK implemented on a device | ## Custom tags This is where your creativity comes in to achieve your specific business goals. Custom tags can be created based on the segmentation logic or targeting pattern that is appropriate for your unique business needs. Collaborate with your marketing team to define the additional custom tags necessary for your campaigns. ### How to set up a custom tag You can add a new tag in the [Pushwoosh Control Panel](https://docs.pushwoosh.com/product/audience-data-and-segmentation/user-data-tags/tags) or use the [`/addTag`](https://docs.pushwoosh.com/developer/api-reference/tags#addtag) method. #### addTag `POST` `https://api.pushwoosh.com/json/1.3/addTag` Creates a tag in your account. #### Request Body | Name | Type | Description | | ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | auth* | string | API access token from Pushwoosh Control Panel. | | tag* | object | Tag parameters. | | tag.name* | string | Tag name. | | tag.type* | integer | Tag type. See possible values below. | | tag.user_specific | boolean | When `true`, the tag value is stored at the user level and shared across all of a user’s devices when set by UserID. When `false` (default), the tag is device-level and set per HWID. | * 200 ```javascript { "status_code": 200, "status_message": "OK", "response": { "result": true } } ``` Example ```javascript { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // required, API access token from Pushwoosh Control Panel "tag": { "name": "TAG_NAME", // required "type": 1, // required, see possible values below "user_specific": false // optional. true = user-level; false = device-level (default) } } } ``` **Possible tag value types:** * 1 - Integer * 2 - String * 3 - List * 4 - Date * 5 - Boolean * 6 - Decimal. Ex: 19.95 * 7 - Version. Ex: “1.0.0.0” ### How to collect information from users Once you’ve added and configured a tag, it’s ready to start collecting information from your users. Follow these steps to implement it: 1. Integrate the [Pushwoosh SDK](https://docs.pushwoosh.com/developer/pushwoosh-sdk/pushwoosh-sdk-overview/) into your project by following the relevant integration guide. 2. Use the [`setTags`](https://docs.pushwoosh.com/developer/api-reference/device-api/#settags) function to assign tags and collect user data. Below are implementation examples for different frameworks using the [`setTags`](https://docs.pushwoosh.com/developer/api-reference/device-api/#settags) function. * iOS Native iOS Native ```objective-c NSDictionary *tags = @{ @"Alias" : aliasField.text, @"FavNumber" : @([favNumField.text intValue]), @"price" : [PWTags incrementalTagWithInteger:5], @"List" : @[ @"Item1", @"Item2", @"Item3" ] }; [[PushNotificationManager pushManager] setTags:tags]; ``` [Documentation](https://pushwoosh.github.io/pushwoosh-ios-sdk/PushwooshiOS/documentation/pushwooshframework/pushwoosh/settags(_:)/) * Android Native Android Native ```java pushwoosh.setTags(Tags.intTag("intTag", 42)); ``` [Documentation](https://pushwoosh.github.io/pushwoosh-android-sdk/pushwoosh/com.pushwoosh/-pushwoosh/set-tags.html) * Cordova Cordova ```plaintext PushNotification.prototype.setTags = function( config, success, fail ) ``` [Documentation](https://docs.pushwoosh.com/developer/pushwoosh-sdk/cross-platform-frameworks/cordova/cordova-plugin-api-reference/#settags) * Flutter Flutter ```dart Future setTags(Map tags) async { await _channel.invokeMethod("setTags", {"tags" : tags}); } ``` [Documentation](https://pub.dev/documentation/pushwoosh_flutter/latest/pushwoosh_flutter/Pushwoosh/setTags.html) * React Native React Native ```javascript pushNotification.setTags({ "string_tag" : "Hello world", "int_tag" : 42, "list_tag":["hello", "world"] }); ``` [Documentation](https://github.com/Pushwoosh/pushwoosh-react-native-plugin/blob/master/docs/README.md#settags) - Unity Unity ##### **SetIntTag** Sets an Integer Tag for the device. ```csharp public virtual void SetIntTag(string tagName, int tagValue) ``` ##### **SetStringTag** Sets a String Tag for the device. ```csharp public virtual void SetStringTag(string tagName, string tagValue) ``` ##### **SetListTag** Sets a List Tag for the device. ```csharp public virtual void SetListTag(string tagName, List tagValues) ``` [Documentation](https://github.com/Pushwoosh/pushwoosh-unity/blob/master/Documentation/README.md#pushwoosh) - Unreal Engine Unreal Engine ```cpp FPushwooshModule& pushwoosh = FPushwooshModule::Get(); pushwoosh.SetTags("{ \"intTag\" : 1, \"stringTag\" : \"example\", \"listTag\" : [ \"a\", \"b\", \"c\" ] }"); ``` [Documentation](https://github.com/Pushwoosh/pushwoosh-unreal-engine/blob/master/Plugins/Pushwoosh/Documentation/README.md#settags) - Expo Expo ```javascript Pushwoosh.setTags({ "key": keyValue, "value": inputValue }); ``` [Documentation](https://github.com/Pushwoosh/pushwoosh-expo-plugin-sample/blob/main/app/_layout.tsx#L296C17-L296C76) - .NET MAUI .NET MAUI ```objective-c NSDictionary *tags = @{ @"Alias" : aliasField.text, @"FavNumber" : @([favNumField.text intValue]), @"price" : [PWTags incrementalTagWithInteger:5], @"List" : @[ @"Item1", @"Item2", @"Item3" ] }; [[PushNotificationManager pushManager] setTags:tags]; ``` [Documentation](https://github.com/Pushwoosh/pushwoosh-dotnet/blob/c40c0fd60cb5fe5c5016c46d677a779a5600f45f/PushwooshSDK.DotNet.iOS.Bindings/PushwooshFramework.xcframework/ios-arm64/PushwooshFramework.framework/Headers/PushNotificationManager.h#L380) - Outsystems Outsystems **Input parameters** **Tags** – A list of tag records containing `TagName` and `TagValue`. * `TagName` must always be of type **Text**. * `TagValue` can be **Text, Integer, Boolean, Date**, etc. [Learn more](https://docs.pushwoosh.com/developer/pushwoosh-sdk/cross-platform-frameworks/outsystems/pushwoosh-outsystems-plugin-client-actions#settags) ### Setting tags via API While in most cases (99%), tags are set from the application, you can also set tags via Pushwoosh API. Below is an example of a typical request to the [`/setTags`](https://docs.pushwoosh.com/developer/api-reference/device-api#settags) endpoint: POST `https://api.pushwoosh.com/json/1.3/setTags` ```json { "request": { "application": "XXXXX-XXXXX", // required, Pushwoosh application code "hwid": "8f65bXXXf378eXXXbeceXXX4e153XXX2", // required, hardware device ID used in /registerDevice API "tags": { // required "StringTag": "string value", // Example of a string tag "IntegerTag": 42, // Example of an integer tag "ListTag": ["string1", "string2"], // Example of a list tag "DateTag": "2024-10-02 22:11", // Note: time must be in UTC "BooleanTag": true // Valid values: true, false } } } ``` [For further details, refer to the setTags API documentation](https://docs.pushwoosh.com/developer/api-reference/device-api/#settags) ## Using the default **City** tag Device’s location is determined based on its IP address at the moment your app was launched on that device for the last time. GeoIP submits the location data to Pushwoosh, and Pushwoosh saves the location received from GeoIP as a City tag value for a particular device. In some cases, the location submitted by the GeoIP differs from the city name — for example, when it refers to an area of a city or other administrative unit. Please be careful when using the default City tag for segmentation purposes: make sure to select the proper values. For example, if you’re going to target users from Munich, you have to cover it with a bunch of City tag values, including “Munich” itself (with all the corresponding values, such as different variants of spelling which could be returned by GeoIP and saved as tag values) and several nearby areas. Tip Before [creating a Segment](https://docs.pushwoosh.com/developer/api-reference/segmentation-filters-api/) via the API, check the values your users have on their devices via [/getTagStats](https://docs.pushwoosh.com/developer/api-reference/statistics-api/events-and-tags-statistics/#gettagstats) request. --- # Customizing rich media appearance **URL:** https://docs.pushwoosh.com/developer/guides/content/customizing-rich-media-appearance/ This guide refers to customizing rich media appearance and animation styles --- ## Overview Customize the appearance of rich media pages to make them fit your app’s style perfectly. Change the background color of your in-app messages, add some animation, or adjust the loading view to the app layout. Improve user experience with in-apps looking like a native component of the app. ## Implementation First, get an instance of the **RichMediaStyle** class: #### iOS ```objective-c PWRichMediaStyle *style = [PWRichMediaManager sharedManager].richMediaStyle; ``` #### Android ```java RichMediaStyle style = RichMediaManager.getRichMediaStyle(); ``` ### Background color Make in-app messages look like an inherent part of your app by **changing the background color** of rich media pages displayed to the app’s users. ![Rich media in-app message with customized background color matching the app design](https://docs.pushwoosh.com/content-customizing-rich-media-appearance-1.webp) #### iOS ```objective-c style.backgroundColor = [[UIColor blackColor] colorWithAlphaComponent:0.2f]; ``` #### Android ```java style.setBackgroundColor(ContextCompat.getColor(getApplication(), R.color.black)); ``` That’s it! ### Animation Enhance the effect of your in-app messages by **animating rich media appearance**. [](https://docs.pushwoosh.com/content-customizing-rich-media-appearance-2.webm) #### iOS Set the animation delegate to one of the default classes: * `PWRichMediaStyleSlideLeftAnimation`, * `PWRichMediaStyleSlideRightAnimation`, * `PWRichMediaStyleSlideTopAnimation`, * `PWRichMediaStyleSlideBottomAnimation`, * `PWRichMediaStyleCrossFadeAnimation`. ```objective-c style.animationDelegate = [PWRichMediaStyleCrossFadeAnimation new]; ``` Note By default, animation type value for iOS is `PWRichMediaStyleAnimationTypeSlideBottom`. #### Android Set the animation delegate to one of the default classes: * `RichMediaAnimationSlideTop`, * `RichMediaAnimationSlideBottom`, * `RichMediaAnimationSlideRight`, * `RichMediaAnimationSlideLeft`, * `RichMediaAnimationCrossFade`. ```java richMediaStyle.setRichMediaAnimationType(new RichMediaAnimationSlideTop()); ``` Note By default, animation type value for Android is `RichMediaAnimationSlideBottom`. To set a **custom animation**, implement `PWRichMediaStyleAnimationDelegate` method for iOS or `RichMediaAnimation` for Android as follows: #### iOS 1. Set the animation delegate: ```objective-c style.animationDelegate = self; ``` 2. Implement `PWRichMediaStyleAnimationDelegate` methods (don’t forget to call a **completion block**): ```objective-c - (void)runPresentingAnimationWithContentView:(UIView *)contentView parentView:(UIView *)parentView completion:(dispatch_block_t)completion { contentView.transform = CGAffineTransformMakeTranslation(0, parentView.bounds.size.height); [UIView animateWithDuration:0.6 delay:0 usingSpringWithDamping:0.4 initialSpringVelocity:0 options:0 animations:^{ contentView.transform = CGAffineTransformIdentity; } completion:^(BOOL finished) { completion(); }]; } - (void)runDismissingAnimationWithContentView:(UIView *)contentView parentView:(UIView *)parentView completion:(dispatch_block_t)completion { [UIView animateWithDuration:0.3 animations:^{ contentView.alpha = 0.0f; contentView.transform = CGAffineTransformMakeScale(2, 2); } completion:^(BOOL finished) { completion(); }]; } ``` #### Android Implement `RichMediaAnimation` interface and set it for custom Rich Media close and open animation: ```java richMediaStyle.setRichMediaAnimation(new RichMediaAnimation() { //Allows to set rules and behavior for custom Rich Media open animation @Override public void openAnimation(View contentView, View parentView) { AnimationSet fadeInAnimation = new AnimationSet(true); fadeInAnimation.addAnimation(new TranslateAnimation(0.15f * parentView.getWidth(), 0, parentView.getHeight() / 2.5f, 0)); fadeInAnimation.addAnimation(new AlphaAnimation(0, 1)); fadeInAnimation.addAnimation(new ScaleAnimation(0.7f, 1.0f, 0.7f, 1.0f)); fadeInAnimation.setDuration(2000); fadeInAnimation.setInterpolator(new DecelerateInterpolator(1f)); contentView.startAnimation(fadeInAnimation); } //Allows to set rules and behavior for custom Rich Media close animation @Override public void closeAnimation(View contentView, View parentView, Animation.AnimationListener endAnimationListener) { // !IMPORTANT! // endAnimationListener has to be added to your custom animation to let Pushwoosh SDK handle animation end event AlphaAnimation alphaAnimation = new AlphaAnimation(1, 0); alphaAnimation.setDuration(2000); alphaAnimation.setAnimationListener(endAnimationListener); alphaAnimation.setFillEnabled(true); alphaAnimation.setFillAfter(true); contentView.animate().translationY(parentView.getHeight() / 5).setDuration(250).start(); parentView.startAnimation(alphaAnimation); } }); ``` ### Custom loading view Catch user attention from the first seconds with **customized loading view** of your In-App Messages. [](https://docs.pushwoosh.com/content-customizing-rich-media-appearance-3.webm) #### iOS 1. Use `loadingViewBlock` as follows: ```objective-c style.loadingViewBlock = ^PWLoadingView *{ return [[[NSBundle mainBundle] loadNibNamed:@"LoadingView" owner:self options:nil] lastObject]; }; ``` 2. “LoadingView” here must inherit from PWLoadingView (defined in PWRichMediaStyle.h): ![Xcode interface showing LoadingView class inheriting from PWLoadingView in the class hierarchy](https://docs.pushwoosh.com/content-customizing-rich-media-appearance-4.webp) 3. Set outlets: ![Xcode interface showing outlet connections for LoadingView custom properties](https://docs.pushwoosh.com/content-customizing-rich-media-appearance-5.webp) #### Android `RichMediaStyle.LoadingViewCreatorInterface` implements a method that returns a View to be used as a loading screen for Rich Media: ```java richMediaStyle.setLoadingViewCreator(() -> { View screenView = createYourScreenView(); return screenView; }); ``` ### Close button enabling delay Make sure the In-App Message is shown to users by **disabling close button** until the Rich Media is loaded. [](https://docs.pushwoosh.com/content-customizing-rich-media-appearance-6.webm) #### iOS ```objective-c style.closeButtonPresentingDelay = 3; ``` #### Android ```java // set a value in milliseconds richMediaStyle.setTimeOutBackButtonEnable(3000); ``` --- # Native in-app templates syntax **URL:** https://docs.pushwoosh.com/developer/guides/content/native-in-app-templates-syntax/ Schema and examples for native-config.json, the JSON format used for native in-app messages rendered directly by the SDK. --- Native in-apps are rendered directly by the SDK. No WebView is involved. Instead of an `index.html` page, the ZIP resource carries a `native-config.json` file that describes the message as structured data (layout type, texts, colors, images, buttons). The SDK reads this file and draws the matching native view, which gives smoother animations and better performance than an embedded web page. This guide documents the `native-config.json` schema: fields, types, and examples for each display type. For the classic HTML-based format, see [Rich media templates syntax](https://docs.pushwoosh.com/developer/guides/content/rich-media-templates-syntax/). ## Prerequisites Native in-apps require: * **iOS:** SDK 7.2.0 or later (7.2.1+ for banner, carousel, and sheet) * **Android:** SDK 6.10.0 or later (6.10.1+ for banner, carousel, and sheet) Not every display type is available on both platforms yet. Check [Platform support](https://docs.pushwoosh.com/developer/guides/content/native-in-app-templates-syntax/#platform-support) before you rely on a specific format. ## Platform support | Display type | iOS | Android | | ------------ | -------- | ----------------- | | modal | ✅ 7.2.0+ | ✅ 6.10.0+ | | fullscreen | ✅ 7.2.0+ | ✅ 6.10.0+ | | stories | ✅ 7.2.0+ | ✅ 6.10.0+ | | banner | ✅ 7.2.1+ | ✅ 6.10.1+ | | carousel | ✅ 7.2.1+ | ✅ 6.10.1+ | | sheet | ✅ 7.2.1+ | ✅ 6.10.1+ | | video | ✅ | Not yet available | | pip | ✅ | Not yet available | | scratchcard | ✅ | Not yet available | | spinwheel | ✅ | Not yet available | Caution A `native-config.json` with a `displayType` your app’s current SDK version doesn’t implement is treated the same as an invalid config. The SDK skips it rather than showing a broken layout. Target campaigns to the right app version if you rely on a type that isn’t available everywhere yet. ## Template structure A native in-app template is a ZIP archive, same as a regular Rich Media template, except the root contains a **native-config.json** file instead of **index.html**: ```plaintext