Skip to main content

📓 Health Nudges Integration Guide

This guide will walk you through the APIs necessary to utilize the Health Nudge Feature effectively. Health Nudges are available on the Body Pro 2 scale and the BPM Pro 2 blood pressure monitor.

Warning

Completing the guide related to your specific logistic case (bulkshipment, dropshipment) prior to engaging with the Health Nudges features is recommended.

As a practical case, we'll focus on implementing a hydration reminder campaign.

sdk illustration

You'll learn how to:

  • Create a nudge that encourages users to stay hydrated.
  • Set up a campaign to schedule and deliver this nudge.
  • Manage user participation by adding or removing users from the campaign.
  • Adjust campaign settings as needed to optimize reach and impact.

Create your first nudge

Let's start by creating our first Nudge. We will use the following endpoint:

Endpoint Details

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

Run In Postman

Required Parameters
  • action: Use create to create a new nudge.
  • signature: A security measure to authenticate the request.
  • client_id: Your unique identifier provided by Withings when you register as a developer.
  • nonce: A unique, random number to prevent replay attacks. (See signature-v2.nonce)
  • iconids: The ID(s) of the icons you want to include in your nudge. Icons visually complement your message.
  • content: The text message you want to display. See 'Limitations sections'.
  • model: Specifies the device model the nudge is targeted at. Supported values are:
    • 17 for Body Pro 2
    • 47 for BPM Pro 2
  • position: (optional) Nudge position in the dynamic screen list. Allowed values are first and last.

Content Limitations

The character limit for a nudge's content is designed to fit the device screen without overwhelming the user. Each line can be a maximum of 15 characters.

template nudge

  • Content Length: The content of the nudge cannot exceed 2 lines.
  • Pixel Width: The total pixel width of the message cannot exceed 320 pixels. This limit accounts for the physical size of the device display and varies by character, with each having a predefined pixel width.

The API will return an error if the content isn't valid.

Content Parameter example
{
    "content": ["Stay hydrated!", "Drink a glass of water."]
}

Example

Let's create our first nudge: a nudge encouraging daily hydration!

Example for Body Pro 2
{
    "action": "create",
    "signature": "genarated_signature",
    "client_id": "YourClientID",
    "nonce": "UniqueNonceValue",
    "iconids": [3],
    "content": ["Stay hydrated!", "Drink a glass of water."],
    "model": 17 //Body Pro 2
}
Example for BPM Pro 2
{
    "action": "create",
    "signature": "genarated_signature",
    "client_id": "YourClientID",
    "nonce": "UniqueNonceValue",
    "iconids": [3],
    "content": ["Stay hydrated!", "Drink a glass of water."],
    "model": 47 //BPM Pro 2
}

We get the following response from the API:

{
    "status": 0,
    "body": {
        "nudgeid": 103
    }
}

Possible Errors

Invalid Icon ID
{
"status": 380,
"body": {},
"error": "Object was not found: no icon found: [[0]]"
}
Content has more than 2 lines
{
"status": 503,
"body": {},
"error": "Invalid Params: wrong content [[\"Line 1\",\"Line 2\",\"Line 3\"]]"
}
A line is too long
{
"status": 503,
"body": {},
"error": "Invalid Params: line 0 is too long"
}