Create a Nudge Campaign

A nudge campaign is a structured approach to sending out a series of nudges, or targeted messages, to users of supported Withings devices (Body Pro 2 and BPM Pro 2). It's the primary method through which these personalized health reminders are organized, scheduled, and delivered, making it a critical element of user engagement and health promotion strategies.

Nudge Campaign Elements

A campaign is composed of several key elements:

• Nudges: The individual messages designed to encourage specific health behaviors. Each nudge within a campaign can have a unique focus, contributing to a broader health objective.
• Target Users: The specific group of users who will receive the nudges. Campaigns can be tailored to reach users based on various criteria, such as their health goals or activity levels.
• Schedule: The timing of when nudges are sent out, defined by the start and end dates of the campaign. This can vary greatly depending on the campaign's goals.

When to create Nudge Campaigns?

In most scenarios, it’s advisable to establish your nudge campaigns prior to the onboarding of patients. This preparatory step ensures that the health messaging strategy is fully operational and ready to engage users from the outset of their interaction with the device. Timely campaign setup enhances the user experience, providing immediate support and guidance that aligns with their health goals.

Setting Start and End Dates

The effectiveness of a nudge campaign often hinges on its timing:

• Open-Ended Campaigns: Ideal for continuous health reminders like hydration prompts. By setting an end date significantly into the future, these campaigns can run indefinitely.
• Time-Bound Campaigns: Best suited for nudges that correspond to specific periods or challenges, such as a month-long fitness challenge. These campaigns have clear start and end dates.

Chronological lifecycles

If you require the implementation of a series of campaigns relative to the enrollment date of your members, it will be necessary to establish a unique sequence of campaigns for each member. These will be allocated a start and end date corresponding to their enrollment period.

Handling Overlapping Campaigns

It's not uncommon for users to be enrolled in multiple campaigns simultaneously. To manage this nudges from overlapping campaigns are presented in the order based on when the user was added to each campaign. This ensures a coherent flow of messages, preventing any confusion and enhancing the user experience.

Setting Max Display Count

To further refine campaign execution you should set a max_display_count that define how many times a campaign's nudges should be shown to the user, ensuring messages are repeated a suitable number of times without becoming excessive.

Endpoint Details

• Endpoint: https://wbsapi.withings.net/v2/nudgecampaign
• Method: POST

Required Parameters

• action: Must take the value create.
• nudgeid: The ID of the nudge you wish to include in the campaign.
• startdate: The date when the campaign begins.
• enddate: The date when the campaign is scheduled to end.
• max_display_count: The maximum number of times a nudge will be displayed to users.
• Authentication parameters: signature, client_id, nonce. (similar to Nudge webservices)

Example Request

Here's how to set up a hydration reminder campaign using a previously created nudge:

{
    "action": "create",
    "signature": "generated_signature",
    "client_id": "YourClientID",
    "nonce": "UniqueNonceValue",
    "nudgeid": 103, // Assuming 103 is the ID for our hydration reminder nudge
    "startdate": "1704067200",
    "enddate": "1704067400",
    "max_display_count": 10
}

Response from the API will be:

{
    "status": 0,
    "body": {
        "nudgecampaignid": 3
    }

This request configures a campaign to run through January, aiming to show the hydration reminder up to 10 times to each targeted user.

Errors

Issue with startdate/enddate

{
    "status": 503,
    "body": {},
    "error": "Invalid Params: start date should not be in the past"
}

{
    "status": 503,
    "body": {},
    "error": "Invalid Params: wrong dates: the start date should be smaller than the end date"
}

Wrong Nudge ID

{
    "status": 503,
    "body": {},
    "error": "Invalid Params: wrong nudge id: [45]"
}