Create User Profile

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

🦉

Create User using python 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 primary key in your DB rather than 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.

distinct_id = "distinct_id"  # Unique identifier of user in your application
# Instantiate User profile
user = supr_client.user.get_instance(distinct_id=distinct_id)

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

📘
Set Channel Preference 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="xiaomi")

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

# - To 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"
  })

# - To 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"
  })

# - To add MS teams using incoming webhook
user.add_ms_teams(
  {
    "incoming_webhook": {
      "url": "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"
    }
  })

# After setting the channel details on user-instance, call save()
response = user.save()
print(response)

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

# - To add 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"
  })

# - To add 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"
  })

# - To add MS teams using incoming webhook
user.remove_ms_teams(
  {
    "incoming_webhook": {
      "url": "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"
    }
  })

# After setting the channel details on user-instance, call save()
response = user.save()
print(response)

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")
response = user.save()
print(response)

# 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

# --- multiple channels can also be deleted in one call by passing argument as a list
user.unset(["$email", "$sms", "$whatsapp"])
response = user.save()
print(response)

🚧
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()
response = user.save()
print(response)

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.

bulk_ins = supr_client.bulk_users.new_instance()
# Prepare multiple users
u1 = supr_client.user.get_instance("distinct_id_1") # User 1
u1.add_email("[email protected]")

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)

# -------
response = bulk_ins.save()
print(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.

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 is an instance of suprsend.BulkResponse class

# Response structure
from suprsend import BulkResponse

BulkResponse(
  status = "success",
  total = 10, # number of records sent in bulk
  success = 10, # number of records succeeded
  failure = 0, # number of records failed
  failed_records = []
)

BulkResponse(
  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}]
)

BulkResponse(
  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}]
)

Advanced Configuration - Set User Properties

You can use SuprSend Python SDK to set advanced user properties, which will help in creating a user profile. You can use these properties to create user cohorts on SuprSend's platform with future releases.

1. Set

Set is used to set the custom user property or properties. The given name and value will be assigned to the user, overwriting an existing property with the same name if present. It can take key as first param, value as second param for setting single user property or object for setting multiple user properties.

from suprsend import Suprsend
supr_client = Suprsend("WORKSPACE_KEY", "WORKSPACE_SECRET")

distinct_id = "__uniq_user_identifier__"
u1 = supr_client.user.get_instance(distinct_id)
u1.set("key", "value")  # for single property
u1.set(properties)      # for multiple properties where properties is a dict()

# set single property using key and value
u1.set("name", "user")
# set multiple/nested properties using dictionary
u1.set({
  "prop1": "val1", 
  "prop2": ["one", "two", "three"], 
  "number": 20
})

Parameters	Type	Description
arg1	string/dictionary	Mandatory This param will be string in case where only single property needs to be created/updated. It will be a dictionary in cases where complex objects need to be set in user properties, like multiple properties, arrays, nested properties etc. Should not start with `$` or `ss_`
arg2	any	Optional This will be value that will be attached to key property. Not required in cases where first param is a dictionary.

❗️
Naming Guidelines
When you create a key, please ensure that the Key Name does not start with $ or ss_, as we have reserved these symbols for our internal events and property names.

2. Set Once

Works just like user.set, except it will not overwrite existing property values. This is useful for properties like First login date

from suprsend import Suprsend
supr_client = Suprsend("WORKSPACE_KEY", "WORKSPACE_SECRET")

distinct_id = "__uniq_user_identifier__"
u1 = supr_client.user.get_instance(distinct_id)
u1.set_once(key, value)  # for single property
u1.set_once(properties)  # for multiple properties

# For setting once a single property:
u1.set_once("first_login", "2021-11-02")

# For setting once multiple properties
u1.set_once({"first_login" : "2021-11-02", "DOB" : "1991-10-02"})

3. Increment

Add the given amount 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.

from suprsend import Suprsend
supr_client = Suprsend("WORKSPACE_KEY", "WORKSPACE_SECRET")

distinct_id = "__uniq_user_identifier__"
u1 = supr_client.user.get_instance(distinct_id)
u1.increment(key, value)  # for single property
u1.increment(property_obj)  # for multiple properties

# For incrementing a single property:
u1.increment("login_count", 1)

# For incrementing multiple properties:
u1.increment({"login_count" : 1, "order_count" : 1})

4. Append

This method will append a value to the list for a given property.

from suprsend import Suprsend
supr_client = Suprsend("WORKSPACE_KEY", "WORKSPACE_SECRET")

distinct_id = "__uniq_user_identifier__"
u1 = supr_client.user.get_instance(distinct_id)
u1.append(key, value)  # for single property
u1.append(properties)  # for multiple properties

# For appending a single property:
u1.append("wishlist", "iphone12")

# For appending multiple properties:
u1.append({"wishlist" : "iphone12", "wishlist" : "Apple airpods"})

5. Remove

This method will remove a value from the list for a given property.

from suprsend import Suprsend
supr_client = Suprsend("WORKSPACE_KEY", "WORKSPACE_SECRET")

distinct_id = "__uniq_user_identifier__"
u1 = supr_client.user.get_instance(distinct_id)
u1.remove(key, value)  # for single property
u1.remove(properties)  # for multiple properties

# For removing a single property:
u1.remove("wishlist", "iphone12")

# For removing multiple properties:
u1.remove({"wishlist" : "iphone12", "wishlist": "Apple airpods"})

6. Unset

This will remove a property permanently from user properties.


from suprsend import Suprsend
supr_client = Suprsend("WORKSPACE_KEY", "WORKSPACE_SECRET")

distinct_id = "__uniq_user_identifier__"
u1 = supr_client.user.get_instance(distinct_id)
u1.unset(key)  # for single property
u1.unset(property_list)  # for multiple properties

# For unsetting a single property:
u1.unset("wishlist")

# For unsetting multiple properties:
u1.unset(["wishlist", "cart"])

Parameters	Type	Description
key	string	This property provided will be deleted from user properties
property_list	array[string]	If list is given all properties included in list will be removed.