Skip to main content

​
How SuprSend identifies a User

SuprSend identifies users with immutable distinct_id. It’s best to map the same identifier in your DB with distinct_id in SuprSend. Do not use identifiers that can be changed like email or phone number. You can view synced users by searching distinct_id on Users page.

​
Create User

To create a new user or to update an existing user, you’ll have to fetch user instance. Call supr_client.user.get_instance to instantiate user object. 
const user = supr_client.user.get_instance("_distinct_id_"); // create user instance

// user methods mentioned in this docs can be attached to user instance if needed

const response = user.save() // IMP: trigger request
response.then((res) => console.log("response", res));

​
Edit User

To Edit user, you need to first fetch user instance, call all the update methods and save changes using user.save() method. 
// Fetch user instance
const user = supr_client.users.get_edit_instance("_distinct_id_");

// Call user update methods
user.set_timezone("America/Los_Angeles");
user.set("name", "John Doe");

// Save Changes
const response = user.save(); // IMP: trigger request
response.then((res) => console.log("response", res));
Here’s a list of all edit methods:
Use user.add_* method to add user channels.

// add Email
user.add_email("user@example.com")

// add SMS
user.add_sms("+15555555555")

// add Whatsapp
user.add_whatsapp("+15555555555")

// add fcm push token
user.add_androidpush("__android_push_fcm_token__")

// add apns push token
user.add_iospush("__iospush_token__")

// add Slack using email
user.add_slack({
  email: "user@example.com",
  access_token: "xoxb-XXXXXXXX"
});

// add Slack if slack member_id is known
user.add_slack({
  user_id: "U03XXXXXXXX",
  access_token: "xoxb-XXXXXXXX"
});

// add Slack channel
user.add_slack({
  channel_id: "CXXXXXXXX",
  access_token: "xoxb-XXXXXXXX"
});

// add Slack incoming webhook
user.add_slack({
  incoming_webhook: {
    url: "https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX"
  }
});

// add MS teams user or channel using conversation_id
user.add_ms_teams({
  tenant_id: "c19xxxx2-9aaf-xxxx-xxxx",
  service_url: "https://smba.trafficmanager.net/amer",
  conversation_id: "19:c1524d7c-a06f-456f-8abe-xxxx"
});

// add MS teams user using user_id
user.add_ms_teams({
  tenant_id: "c19xxxx2-9aaf-xxxx-xxxx",
  service_url: "https://smba.trafficmanager.net/amer",
  user_id: "29:1nsLcmJ2RKtYH6Cxxxx-xxxx"
});

// add MS teams using incoming webhook
user.add_ms_teams({
  incoming_webhook: {
    url: "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"
  }
});
Use user.remove_* method(s) to remove user channels. These methods will detach provided value from the user profile in specified channel.

// remove Email
user.remove_email("user@example.com")

// remove SMS
user.remove_sms("+15555555555")

// remove Whatsapp
user.remove_whatsapp("+15555555555")

// remove fcm push token
user.remove_androidpush("__android_push_fcm_token__")

// remove apns push token
user.remove_iospush("__iospush_token__")

// remove Slack email
user.remove_slack({
  email: "user@example.com",
  access_token: "xoxb-XXXXXXXX"
});

// remove Slack if slack member_id is known
user.remove_slack({
  user_id: "U03XXXXXXXX",
  access_token: "xoxb-XXXXXXXX"
});

// remove Slack channel
user.remove_slack({
  channel_id: "CXXXXXXXX",
  access_token: "xoxb-XXXXXXXX"
});

// remove Slack incoming webhook
user.remove_slack({
  incoming_webhook: {
    url: "https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX"
  }
});

// remove MS teams user or channel using conversation_id
user.remove_ms_teams({
  tenant_id: "c19xxxx2-9aaf-xxxx-xxxx",
  service_url: "https://smba.trafficmanager.net/amer",
  conversation_id: "19:c1524d7c-a06f-456f-8abe-xxxx"
});

// remove MS teams user using user_id
user.remove_ms_teams({
  tenant_id: "c19xxxx2-9aaf-xxxx-xxxx",
  service_url: "https://smba.trafficmanager.net/amer",
  user_id: "29:1nsLcmJ2RKtYH6Cxxxx-xxxx"
});

// remove MS teams using incoming webhook
user.remove_ms_teams({
  incoming_webhook: {
    url: "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"
  }
});
This method will delete/unset all values in specified channel for user (ex: remove all emails attached to user).
user.unset("$email")
user.unset(["$email", "$sms", "$whatsapp"])

// what value to pass to unset channels
// for email:                $email
// for whatsapp:             $whatsapp
// for SMS:                  $sms
// for androidpush tokens:   $androidpush
// for iospush tokens:       $iospush
// for webpush tokens:       $webpush
// for slack:                $slack
// for ms_teams:             $ms_teams
If you want to send notification in user’s preferred language, you can set it by passing language code in this method. This is useful especially for the applications which offer vernacular or multi-lingual support.
user.set_preferred_language("en")
You can set timezone of user using this method. Value for timezone must be from amongst the IANA timezones.
user.set_timezone("America/Los_Angeles")
Set is used to set the custom user property or properties. The given key and value will be assigned to the user, overwriting an existing property with the same key if present.
user.set(key, value)
user.set("name","John Doe")

user.set({ key1: value1, key2: value2 })
user.set({"name": "John Doe","city": "San Francisco"})
Parameterstype
keystring
valueany
Works just like user.set, except it will not override already existing property values. This is useful for properties like first_login_date.
user.set_once(key, value)
user.set_once("first_login","2021-11-02")

user.set_once({ key1: value1, key2: value2 })
user.set_once({"first_login": "2021-11-02","signup_date": "2021-11-02"})
This method will append a value to the list for a given property.
user.append(key, value)
user.append("played_games", "game_1")

user.append({ key1: value1, key2: value2 })
user.append({"played_games": "game_1", "liked_games": "game_2"})
This method will remove a value from the list for a given property.
user.remove(key, value)
user.remove("played_games", "game_1")

user.remove({ key1: value1, key2: value2 })
user.remove({"played_games": "game_1", "liked_games": "game_2"})
Add the given number to an existing property on the user. If the user does not already have the associated property, the amount will be added to zero. To reduce a property, provide a negative number for the value.
user.increment(key, value)
user.increment("login_count", 1)

user.increment({ key1: value1, key2: value2 })
user.increment({"login_count" : 1, "order_count" : 1})
Parameterstype
keystring
valuenumber (+ or -)
This will remove a property permanently from user properties.
user.unset(key)
user.unset("wishlist")

user.unset([key1, key2])
user.unset(["wishlist", "cart"])
Parameterstype
keysstring
After calling add*/remove*/unset methods, don’t forget to call the user.save() request. the changes will be sent to SuprSend only after calling this method.

​
Bulk API for updating multiple user profiles

To update multiple user profiles use Bulk API. There isn’t any limit on number-of-records that can be added to bulk_users instance. Use append() on bulk_users instance to add however-many-records to call in bulk. 
const { Suprsend } = require("@suprsend/node-sdk");

const supr_client = new Suprsend("workspace_key", "workspace_secret");

const bulk_ins = supr_client.bulk_users.new_instance()

// user1 instance
const user1 = supr_client.user.get_instance("_distinct_id_1")
user1.add_email("u1@example.com")
user1.set_preferred_language("en")

// user2 instance
const user2 = supr_client.user.get_instance("_distinct_id_2")
user2.remove_email("u2@example.com")

//append users instance to bulk instance
bulk_ins.append(user1)
bulk_ins.append(user2)
// OR
bulk_ins.append(user1, user2)

 // trigger request
const response = bulk_ins.save()
response.then((res) => console.log("response", res));

​
Get user details

const response = await supr_client.users.get(_distinct_id_);

​
Delete user

const response = await supr_client.users.delete(_distinct_id_);

​
Get list of objects subscribed by user

const response = await supr_client.users.get_objects_subscribed_to(_distinct_id_, {limit:20});
You can pass optional query parameters - limit,before,after.

​
Get lists subscribed by user

const response = await supr_client.users.get_lists_subscribed_to(_distinct_id_, {limit:20});
You can pass optional query parameters - limit,before,after.