Guides
LoginSignupGithub

Manage Users

This document covers the methods to manage users within SuprSend

Suggest Edits

How Suprsend identifies a user

Suprsend identifies a user by a unique identifier distinct_id. The identifier for a user is important as we use this key to create user profile and all the information related to a user, like channel preferences, is attached to that profile. You can view user profile 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 (async method)

To create a new user or to update the profile of an existing user, you'll have to first instantiate the user object. Call supr_client.user.getInstance 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;
  }
}

Response

When you call user.save(), the SDK internally makes an HTTP call to SuprSend Platform to register this request, and you'll immediately receive a response indicating the acceptance / failure status.

// Response structure
{
    "success": true, // if true, request was accepted.
    "status": "success",
    "status_code": 202, // http status code
    "message": "OK",
}

{
    "success": false, // error will be present in message
    "status": "fail",
    "status_code": 500, // http status code
    "message": "error message",
}

Edit User

Add Communication Channels

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_id in 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.

Use user.add* method(s) to add user channels in a profile

import org.json.JSONObject;
import suprsend.Suprsend;
import suprsend.Subscriber;

public class UserEdit {

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

    // Add Email
    user.addEmail("[email protected]");

    //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", "[email protected]");
    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/TXXXXXXXXX/BXXXXXXXX/XXXXXXXXXXXXXXXXXXX"))
      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");

    // Save
    JSONObject response = user.save();
    System.out.println(response);
  }
}

Remove Channels

Use user.remove* method(s) to remove channels from a user profile

import org.json.JSONObject;
import suprsend.Suprsend;
import suprsend.Subscriber;

public class UserEdit {

  public static void removeChannel() throws Exception {
    Suprsend suprsendClient = getSuprClient();

    // User Edit Instance
    String distinctID = "__distinct_id__";
    Subscriber user = suprsendClient.user.getInstance(distinctID);

    // Remove Email
    user.removeEmail("[email protected]");

    //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", "[email protected]");
    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/TXXXXXXXXX/BXXXXXXXX/XXXXXXXXXXXXXXXXXXX"))
      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");

    // Save
    JSONObject response = user.save();
    System.out.println(response);
  }
}

Bulk Remove Channels

If you need to delete/unset all emails (or any other channel) of a user, you can call user.unset() method on the user instance. The method accepts the channel key/s (a single key or list of keys)

import org.json.JSONObject;
import suprsend.Suprsend;
import suprsend.Subscriber;

public class UserEdit {

  public static void unsetChannel() throws Exception {
    Suprsend suprsendClient = getSuprClient();

    // User Edit Instance
    String distinctID = "__distinct_id__";
    Subscriber user = suprsendClient.user.getInstance(distinctID);

    // --- To unset one channel, for example 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);

    // Save
    JSONObject response = user.save();
    System.out.println(response);
  }
}

Set Preferred language

If you want to send notification in user's preferred language, you can set it by passing language code in user.setPreferredLanguage() method. This is useful especially for the applications which offer vernacular or multi-lingual support.

import org.json.JSONObject;
import suprsend.Suprsend;
import suprsend.Subscriber;

public class UserEdit {

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

    // Pass language in ISO 639-1 code
    user.setPreferredLanguage("es");

    // Save
    JSONObject response = user.save();
    System.out.println(response);
  }
}

Set Timezone

You can set timezone of user using user.setTimezone() method. Value for timezone must be from amongst the IANA timezones.

import org.json.JSONObject;
import suprsend.Suprsend;
import suprsend.Subscriber;

public class UserEdit {

  public static void setTimezone() throws Exception {
    Suprsend suprsendClient = getSuprClient();

    // User Edit Instance
    String distinctID = "__distinct_id__";
    Subscriber user = suprsendClient.user.getInstance(distinctID);

    // Pass IANA timezone
    user.setTimezone("America/New_York");

    // Save
    JSONObject response = user.save();
    System.out.println(response);
  }
}

Bulk user update

To update user profiles in bulk, use .append() on bulk_users instance to add multiple bulk requests. There isn't any limit on number-of-records that can be added to bulkIns instance.

import org.json.JSONObject;
import suprsend.Suprsend;
import suprsend.Subscriber;

public class UserBulkEdit {

  public static void bulkSubscriber() throws Exception {
    Suprsend suprsendClient = getSuprClient();

    //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("[email protected]");

    String distinctID2 = "__distinct_id2__"; // User 2
    User u2 = suprsendClient.user.getInstance(distinctID2);
    u2.addEmail("[email protected]");

    // --- 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 update Response

Response is an instance of suprsend.BulkResponse class

// Response structure
import suprsend.BulkResponse;

BulkResponse{status: 'success' | total: 2 | success: 2 | failure: 0 | warnings: 0}

BulkResponse{status: 'fail' | total: 2 | success: 0 | failure: 2 | warnings: 0}

BulkResponse{status: 'partial' | total: 2 | success: 1 | failure: 1 | warnings: 0}

Get User details

Fetch User by passing distinct_id

import org.json.JSONObject;
import suprsend.Suprsend;

public class UserAPI {

  public static void get() throws Exception {
    Suprsend suprsendClient = getSuprClient();
    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.

import org.json.JSONObject;
import suprsend.Suprsend;
import suprsend.UserEdit;

public class UserAPI {

  public static void delete() throws Exception {
    Suprsend suprsendClient = getSuprClient();
    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

import org.json.JSONObject;
import suprsend.Suprsend;
import suprsend.UserEdit;
import java.util.HashMap;

public class UserAPI {

  public static void getObjectsSubscribedTo() throws Exception {
    Suprsend suprsendClient = getSuprClient();
    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 -limit,before,after

import org.json.JSONObject;
import suprsend.Suprsend;
import suprsend.UserEdit;
import java.util.HashMap;

public class UserAPI {

  public static void getListsSubscribedTo() throws Exception {
    Suprsend suprsendClient = getSuprClient();
    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);
  }
}

Updated about 2 months ago

What’s Next

Once channels are set in user profile, just add user's distinct_id in send event or workflow trigger call and all the user channels will automatically be fetched from user profile