Skip to main content

User preferences API

The user preferences API can be used to manage if and when customers receive native mobile (also known as push) notifications:

  • notifications. This preference specifies the time period(s) when the customer may receive native mobile notifications.
  • timezone. This preference specifies the time zone the customer is in.
  • notificationsEnabled. This preference specifies whether push notifications are enabled.

Read more about how to enable notifications in your apps in the workbench configuration guide.

A credential role of events is required to utilize the User preferences API.

You can interact with the User preferences API using Insomnia (follow the Insomnia instructions) or curl. When using curl, you'll need to set up your Authentication first.

Detailed specs and examples can be found in the Atomic API spec for the Users endpoint.

Get user preferences (token: events)​

To retrieve preferences for a user by id, you can send the following request to the User API:

USER_ID="user-id-you-want-to-query"

curl -X GET "https://$ORG_ID.customer-api.atomic.io/v1/$ENVIRONMENT_ID/user?id=$USER_ID" \
    --header "Authorization: Bearer $TOKEN"

The response will look similar to the example below:

{
  "data": {
    {
      "id": "123",
      "preferences": {
        "timezone": "Pacific/Auckland",
        "notificationsEnabled": true
      },
      "preferencesUpdated": "2022-04-10T23:28:43.060Z",
      "created": "2022-01-20T01:55:58.643Z",
      "profile": {
        ...
      },
      "segments": {
      ...
      },
      ...
    }
  }
}

Update user preferences​

To update preferences for one or more customers:

PAYLOAD='{
  data: {
    "userId1": {
      "timezone": "Pacific/Auckland",
      "notifications": {
        "default": [
          {
          "from": "09:00",
          "to": "12:00"
          },
          {
          "from": "14:00",
          "to": "17:00"
          }
        ],
        "sat": [
          {
            "from": "09:00",
            "to": "12:00"
          }
        ],
        "sun": []
      },
      "notificationsEnabled": true
    },
    "userId2": {...},
    ...
  }
'

curl -X PUT "https://$ORG_ID.customer-api.atomic.io/v1/$ENVIRONMENT_ID/userPreferences \
    --header "Content-Type:application/json" \
    --header "Authorization: Bearer $TOKEN" \
    --data $CUSTOM_FIELDS_PAYLOAD
PUT /v1/:environmentId/userPreferences
{
  "data": {
    "userId1": { ... },
    "userId2": { ... },
    ...
  }
}

Each user preference object should be any subset of the allowed preferences. Existing preferences will be maintained if not provided.

Time zone​

Note timezone is set automatically by the Atomic SDK, so doesn't need to be kept up-to-date by your system. Example:

{
  "timezone": "Pacific/Auckland",
  "notifications": {
    "default": [{ "from": "09:00", "to": "12:00" }]
  },
  "notificationsEnabled": true
}

It is possible to set another time zone, but this will:

  • be updated by the Atomic SDK when the customer logs in again;
  • possibly result in unwanted behavior if notifications are specified for time periods (as set in the notifications user preference)

Notifications​

For more granular control, notifications may be specified as one or more periods per day, and may be specified as an array of time periods. The following example specifies notifications are allowed:

  • from 9am-noon and 2pm-5pm on weekdays
  • from 9am-noon on Saturdays
  • not at all on Sundays

If a notification is sent outside of these specified time periods, it will be queued and sent at the start of the next specified time period. The analytics events notification-sent and notification-received show the timestamps of each of these events. You can find more details in the Analytics Reference Guide.

Note: Changing this setting only changes the push notification behavior; card and stream behavior remains the same regardless of this setting.

{
  "notifications": {
    "default": [
      { "from": "09:00", "to": "12:00" },
      { "from": "14:00", "to": "17:00" }
    ],
    "sat": [{ "from": "09:00", "to": "12:00" }],
    "sun": []
  }
}

NotificationsEnabled​

Notifications are enabled by default.

Notifications for a user can be disabled by setting the notificationsEnabled property to false.

Note: Changing this setting only changes the push notification behavior; card and stream behavior remains the same, regardless of this setting.

{
  "notificationsEnabled": false
}
Last updated on