Create User Profile

You can follow the steps mentioned in the documentation below or refer to our quick code recipe

🦉

Create User using node SDK

Open Recipe

Pre-requisites

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 Subscribers 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 in your DB rather than a phone number or email address.

Step 1 : Create a new user

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.get_instance to instantiate user object.

const distinct_id = "__uniq_user_id__"  // Unique id of user in your application
const user = supr_client.user.get_instance(distinct_id) // Instantiate User profile

const response = user.save() //save() returns promise
response.then((res) => console.log("response", res));

Step 2: Set Communication Channel preferences

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).

Especially for event based workflow triggers, where you just pass the user's distinct_id and the communication channels are picked from user profile

📘
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 first before making the call.

1. Add User Channels

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

// Add channel details to user-instance. Call relevant add_* methods

user.add_email("[email protected]") // - To add Email

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

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

user.add_androidpush("__android_push_fcm_token__") // - by default, token is assumed to be fcm-token

// You can 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__")

// - To add Slack using email
user.add_slack(
  {
    "email": "[email protected]",
    "access_token": "xoxb-XXXXXXXX"
  })  

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

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

// - To add Slack incoming webhook
user.add_slack(
  {
    "incoming_webhook": {
      "url": "https://hooks.slack.com/services/TXXXXXXXXX/BXXXXXXXX/XXXXXXXXXXXXXXXXXXX"
    }
  })

// After setting the channel details on user-instance, call save()
const response = user.save() //save() returns promise
response.then((res) => console.log("response", res));

2. Remove User Channels

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

// Remove channel details from user-instance. Call relevant remove_* methods

user.remove_email("[email protected]") // - To remove Email

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

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

user.remove_androidpush("__android_push_fcm_token__") // - by default, token is assumed to be fcm-token

// You can set the optional provider value [fcm/xiaomi/oppo] if its not a fcm-token
user.remove_androidpush("__android_push_xiaomi_token__", provider="xiaomi")

user.remove_iospush("__iospush_token__")

// - To remove Slack email
user.remove_slack(
  {
    "email": "[email protected]",
    "access_token": "xoxb-XXXXXXXX"
  })  

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

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

// - To remove Slack incoming webhook
user.remove_slack(
  {
    "incoming_webhook": {
      "url": "https://hooks.slack.com/services/TXXXXXXXXX/BXXXXXXXX/XXXXXXXXXXXXXXXXXXX"
    }
  })

// After setting the channel details on user-instance, call save()
const response = user.save()
response.then((res) => console.log("response", res));

3. Remove User Channels in bulk

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)

// --- To delete all emails associated with user
user.unset("$email")
const response = user.save()
response.then((res) => console.log("response", res));

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

// --- multiple channels can also be deleted in one call by passing argument as a list
user.unset(["$email", "$sms", "$whatsapp"])
const response = user.save()
response.then((res) => console.log("response", res));

🚧
Note
After calling add_*/remove_*/unset methods, don't forget to call user.save(). On call of save(), SDK sends the request to SuprSend platform to update the User Profile.

Add Preferences in User Profile

You can also set custom properties in user profile that is used to set user preferences

Set Preferred language

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

// Add language preference to user-instance.

user.set_preferred_language("en")

// After setting the language on user-instance, call save()
const response = user.save()
response.then((res) => console.log("response", res));

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",
}

Bulk API for handling multiple user profiles

To update user profiles in bulk, use Bulk users 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 bulk_ins = supr_client.bulk_users.new_instance()
// Prepare multiple users
const u1 = supr_client.user.get_instance("distinct_id_1") // User 1
u1.add_email("[email protected]")

const u2 = supr_client.user.get_instance("distinct_id_2") // User 2
u2.add_email("[email protected]")

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

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

🚧
Bulk API supported in SDK version 1.0.0 and above
Bulk API is supported in SuprSend node-sdk version 1.0.0 and above. If you are using an older version, please upgrade to the latest SDK version.

How SuprSend Processes the bulk API request

On calling bulk_ins.save(), the SDK internally makes one-or-more Callable-chunks.
Each callable-chunk contains a subset of records, the subset calculation is based on each record's bytes-size and max allowed chunk-size, chunk-length etc.
For each callable-chunk SDK makes an HTTP call to SuprSend to register the request.

Response

// Response structure
{
  status: "success",
  total: 10, // number of records sent in bulk
  success: 10, // number of records succeeded
  failure: 0, // number of records failed
  failed_records: []
  warnings: []
}

{
  status: "fail",
  total: 10, // number of records sent in bulk
  success: 0, // number of records succeeded
  failure: 10, // number of records failed
  failed_records: [{"record": {...}, "error": "error_str", "code": 500}],
  warnings: []
}

{
  status: "partial",
  total: 10, // number of records sent in bulk
  success: 6, // number of records succeeded
  failure: 4, // number of records failed
  failed_records: [{"record": {...}, "error": "error_str", "code": 500}],
  warnings: []
}