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.
Please note: you cannot change a user’s id once it has been set, so we recommend you use a non-transient id like a primary key rather than a phone number or email address.

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.
import org.json.JSONObject;
import suprsend.Suprsend;
import suprsend.Subscriber;

public class UserEdit {
  public static void main(String[] args) throws Exception {
    getInstance();
  }

  private static Subscriber getSuprClient() throws SuprsendException {
    Suprsend suprsendClient = new Suprsend("_workspace_key_", "_workspace_secret_");
    return suprsendClient;
  }

  private static Subscriber getInstance() throws SuprsendException {
    Suprsend suprsendClient = getSuprClient();
    // Instiantiate user
    String distinctId = "_distinct_id_";

    Subscriber user = suprClient.user.getInstance(distinctId);
    return user;
  }
}

Edit User

To Edit user, you need to first fetch user instance, call all the update methods and save changes using user.save method.
import org.json.JSONObject;
import suprsend.Suprsend;
import suprsend.Subscriber;

public class UserEdit {

  public static void updateProfile() throws Exception {
    Suprsend suprsendClient = getSuprClient();
    // User Edit Instance
    String distinctID = "_distinct_id_";
    Subscriber user = suprsendClient.user.getInstance(distinctID);

    // Edit Helper methods
    user.addEmail("example@example.com");
    user.setTimezone("America/New_York");

    // Save
    JSONObject response = user.save();
    System.out.println(response);
  }
}
Here’s a list of all edit methods:
Add communication channels on which you want to notify user. Push sand Inbox tokens are automatically tracked on user identification when the corresponding frontend SDK is integrated. Other channels (Email, SMS, Slack, MS teams, Whatsapp) need to be explicitly set in user profile.Use user.add_* method(s) to add user channels.
// User Edit Instance
String distinctID = "_distinct_id_";
Subscriber user = suprsendClient.user.getInstance(distinctID);

// Add Email
user.addEmail("example@example.com");

//Add SMS
user.addSms("+919999999999");

//Add Whatsapp
user.addWhatsapp("+919999999999");

// Add Androidpush token.Pass the vendor as 2nd param.
user.addAndroidpush("androidpush_fcm_token__", "fcm");

// Add iospush token
user.addIospush("__iospush_apns_token__");

// Add Slack using user email id
JSONObject slackIdent = new JSONObject()
  .put("access_token", "xoxb-XXXXXXXX")
  .put("email", "user@example.com");
user.addSlack(slackIdent);

// Add Slack using member_id of the user if known
JSONObject slackIdent = new JSONObject()
  .put("access_token", "xoxb-XXXXXXXX")
  .put("user_id", "U03XXXXXXXX");
user.addSlack(slackIdent);

// Add Slack channel_id
JSONObject slackIdent = new JSONObject()
  .put("access_token", "xoxb-XXXXXXXX")
  .put("channel_id", "C04XXXXXXXX");
user.addSlack(slackIdent);

// Add Slack incoming webhook
JSONObject slackIdent = new JSONObject()
  .put("incoming_webhook", new JSONObject().put("url", "https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX"))
user.addSlack(slackIdent);

// Add Webpush token json (VAPID)
JSONObject webpush = new JSONObject()
  .put("endpoint", "__end_point__")
  .put("expirationTime", "")
  .put("keys", new JSONObject()
    .put("p256dh", "__p256dh__")
    .put("auth", "__auth_key__"));
user.addWebpush(webpush, "vapid");
Use user.remove_* method(s) to remove channels.
// Remove Email
user.removeEmail("example@example.com");

//Remove SMS
user.removeSms("+919999999999");

//Remove Whatsapp
user.removeWhatsapp("+919999999999");

// Remove Androidpush token.Pass the vendor as 2nd param.
user.removeAndroidpush("androidpush_fcm_token__", "fcm");

// Remove iospush token
user.removeIospush("__iospush_apns_token__");

// Remove Slack using user email id
JSONObject slackIdent = new JSONObject()
  .put("access_token", "xoxb-XXXXXXXX")
  .put("email", "user@example.com");
user.removeSlack(slackIdent);

// Remove Slack using member_id of the user if known
JSONObject slackIdent = new JSONObject()
  .put("access_token", "xoxb-XXXXXXXX")
  .put("user_id", "U03XXXXXXXX");
user.removeSlack(slackIdent);

// Remove Slack channel_id
JSONObject slackIdent = new JSONObject()
  .put("access_token", "xoxb-XXXXXXXX")
  .put("channel_id", "C04XXXXXXXX");
user.removeSlack(slackIdent);

// Remove Slack incoming webhook
JSONObject slackIdent = new JSONObject()
  .put("incoming_webhook", new JSONObject().put("url", "https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX"))
user.removeSlack(slackIdent);

// Remove Webpush token json (VAPID)
JSONObject webpush = new JSONObject()
  .put("endpoint", "__end_point__")
  .put("expirationTime", "")
  .put("keys", new JSONObject()
    .put("p256dh", "__p256dh__")
    .put("auth", "__auth_key__"));
user.removeWebpush(webpush, "vapid");
This method will delete/unset all values in specified channel for user (ex: remove all emails attached to user).
// --- To unset one channel, e.g. to delete all emails associated with user
// -- Channel keys - ("$email","$whatsapp","$sms," $androidpush","$iospush","$webpush","$slack")
user.unset("$email");

// --- multiple channels can also be deleted in one call by passing argument as a list
ArrayList < String > channels = new ArrayList < > (Arrays.asList("$email", "$slack", "$androidpush", "$iospush", "$webpush", "$whatsapp"));
user.unset(channels);
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 Edit Instance
String distinctID = "_distinct_id_";
Subscriber user = suprsendClient.user.getInstance(distinctID);

// Pass language in ISO 639-1 code
user.setPreferredLanguage("es");
You can set timezone of user using this method. Value for timezone must be from amongst the IANA timezones.
// User Edit Instance
String distinctID = "_distinct_id_";
Subscriber user = suprsendClient.user.getInstance(distinctID);

// Pass IANA timezone
user.setTimezone("America/New_York");
Set is used to add custom user properties. It is an upsert function, meaning any existing property value with the same key will be overwritten on subsequent updates.
user.set(key, value)
user.set("name","John Doe")

user.set({ key1: value1, key2: value2 })
user.set({"name": "John Doe","city": "San Francisco"})
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"})
Unset is used to remove a property key.
user.unset(key)
user.unset("name")

user.unset([key1, key2])
user.unset(["name","city"])
This method will append a value to the array list.
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 array list.
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"})
Increase or decrease integer values on consecutive action, like login count. 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})
After calling add_*/remove_*/unset methods, don’t forget to call users.save() since user edit is async update and the changes will be sent to SuprSend only after calling this method.

Bulk Update Users

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.
//Creating bulk instance
BulkSubscribers bulkIns = suprClient.bulkUsers.newInstance();

// Prepare multiple users
String distinctID1 = "__distinct_id1__"; // User 1
User u1 = suprsendClient.user.getInstance(distinctID1);
u1.addEmail("u1@example.com");

String distinctID2 = "__distinct_id2__"; // User 2
User u2 = suprsendClient.user.getInstance(distinctID2);
u2.addEmail("u2@example.com");

// --- use .append on bulk instance to add one or more records
bulkIns.append(u1);
bulkIns.append(u2);
// OR
bulkIns.append(u1, u2);

// Save
JSONObject response = bulkIns.save();
System.out.println(response);
Bulk API supported in SDK version 0.2.0 and above:Bulk API is supported in SuprSend python-sdk version 0.2.0 and above. If you are using an older version, please upgrade to the latest SDK version.

Get user details

Fetch User by passing distinct_id
String distinctId = "_distinct_id_";

JSONObject res = suprClient.users.get(distinctId);
System.out.println(response);

Delete user

Delete User by passing distinct_id. Delete action will take into immediate effect.
String distinctId = "_distinct_id_";

JSONObject res = suprClient.users.delete(distinctId);
System.out.println(response);

Get list of objects subscribed by user

You can pass optional query parameters -limit,before,after
String distinctId = "_distinct_id_";

// optional params to pass limit (default=10) and cursor pointer for fetching the next set of results
HashMap < String, Object > opts = new HashMap < String, Object > () {
  {
    put("limit", 10);
    put("after", "01HFS04E4J29KHPYRK7HT3YQQ5");
  }
};

JSONObject res = suprClient.users.getObjectsSubscribedTo(distinctId, opts);
System.out.println(response);

Get lists subscribed by user

You can pass optional query parameters -limitbeforeafter
String distinctId = "_distinct_id_";

// optional params to pass limit (default=10) and cursor pointer for fetching the next set of results
HashMap < String, Object > opts = new HashMap < String, Object > () {
  {
    put("limit", 10);
    put("after", "01HFS04E4J29KHPYRK7HT3YQQ5");
  }
};

JSONObject res = suprClient.users.getListsSubscribedTo(distinctId, opts);
System.out.println(response);
I