Create User Profile
This document will cover the methods to create a user and set channel preferences
You can follow the steps mentioned in the documentation below or refer to our quick code 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_idin 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_*/unsetmethods, don't forget to calluser.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
$orss_, 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. |
Updated 8 months ago
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