Manage Users
This document will cover the methods to manage users in SuprSend
Create user
distinct_id is needed to create/update user profile in SuprSend. This ID will be unique throughout workspace.
const user = supr_client.user.get_instance("__uniq_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));
Response
When you call user.save(), on any of user methods, SDK internally makes an API call to SuprSend, and you'll receive a response indicating the acceptance / failure status.
{
"success": boolean,
"status": "success"/"fail",
"status_code": http_status_code,
"message": "response_message"/"error_message",
}
Get user details
const response = await supr_client.users.get(distinct_id);
Communication channel methods
Communication Channel Preference decides whether a user will receive communication on a particular channel or not. Setting Channel preferences means that whenever you are triggering a workflow, the communication will be sent on the channels set in user profile (given that the template for that channel is present in the template group).
Mandatory step for event based workflows
In event based workflows, since you only pass user's
distinct_idin your track event call, you'll have to add channel preference first in user profile before making the call, as channels info is picked from user profile.
Add User Channels
Use user.add_* method(s) to add user channels.
user.add_email("[email protected]") // add Email
user.add_sms("+15555555555") // add SMS
user.add_whatsapp("+15555555555") // add Whatsapp
user.add_androidpush("__android_push_fcm_token__") // add fcm push token
// // set the optional provider value [fcm/xiaomi/oppo] if its not a fcm-token
user.add_androidpush("__android_push_xiaomi_token__", provider)
user.add_iospush("__iospush_token__") // add apns push token
// add Slack using email
user.add_slack({
email: "[email protected]",
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/TXXXXXXXXX/BXXXXXXXX/XXXXXXXXXXXXXXXXXXX"
}
});
// add MS teams user or channel using conversation_id
user.add_ms_teams({
tenant_id: "c1981ab2-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: "c1981ab2-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"
}
});
Remove User Channels
Use user.remove_* method(s) to remove user channels. These methods will detach provided value from the user profile in specified channel.
user.remove_email("[email protected]") // remove Email
user.remove_sms("+15555555555") // remove SMS
user.remove_whatsapp("+15555555555") // remove Whatsapp
user.remove_androidpush("__android_push_fcm_token__") // remove fcm push token
// set the optional provider value [fcm/xiaomi/oppo] if its not a fcm-token
user.remove_androidpush("__android_push_token__", provider)
user.remove_iospush("__iospush_token__") // remove apns push token
// remove Slack email
user.remove_slack({
email: "[email protected]",
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/TXXXXXXXXX/BXXXXXXXX/XXXXXXXXXXXXXXXXXXX"
}
});
// remove MS teams user or channel using conversation_id
user.remove_ms_teams({
tenant_id: "c1981ab2-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: "c1981ab2-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"
}
});
Remove User Channels in bulk
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
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()
const user1 = supr_client.user.get_instance("distinct_id_1") // user1 instance
user1.add_email("[email protected]")
user1.set_preferred_language("en")
const user2 = supr_client.user.get_instance("distinct_id_2") // user2 instance
user2.remove_email("[email protected]")
//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));
Bulk Response
{
status: "success/fail/partial",
total: 10,
success: 10,
failure: 0,
failed_records: [{"record": {...}, "error": "error_str", "code": "<status_code>"}],
warnings: []
}
Other user methods
Set preferred language
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")
Set preferred timezone
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
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({ key1: value1, key2: value2 });
user.set("name", "user")
user.set({
"prop1": "val1",
"prop2": ["one", "two", "three"],
"number": 20
})
| Parameters | type |
|---|---|
| key | string (shouldn't start with ss_ or $) |
| value | any |
Set Once
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({ key1: value1, key2: value2 });
user.set_once("first_login", "2021-11-02")
user.set_once({"first_login" : "2021-11-02", "DOB" : "1991-10-02"})
Append
This method will append a value to the list for a given property.
user.append(key, value);
user.append({ key1: value1, key2: value2 });
user.append("wishlist", "iphone12")
user.append({"wishlist" : "iphone12"})
Remove
This method will remove a value from the list for a given property.
user.remove(key, value);
user.remove({ key1: value1, key2: value2 });
user.remove("wishlist", "iphone12")
user.remove({"wishlist" : "iphone12"})
Increment
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({ key1: value1, key2: value2 })
user.increment("login_count", 1)
user.increment({"login_count" : 1, "order_count" : 1})
| Parameters | type |
|---|---|
| key | string (shouldn't start with ss_ or $) |
| value | number (+ or -) |
Unset
This will remove a property permanently from user properties.
user.unset(key);
user.unset([key1, key2]);
user.unset("wishlist")
user.unset(["wishlist", "cart"])
| Parameters | type |
|---|---|
| keys | string or array of strings (shouldn't start with ss_ or $) |
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.
Updated about 2 months ago
After setting user channels send events which trigger workflow to get notifications