Guides
LoginSignupGithub

Manage Users

This document will cover 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 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.


Create User

To fetch the user instance, or to update the profile of an existing user, you'll have to first instantiate the user object. Call supr_client.users.get_edit_instance to instantiate user object.

import suprsend
supr_client = suprsend.Suprsend("Workspace_Key", "Workspace_Secret")

user = supr_client.users.get_edit_instance("__distinct_id__")

Edit User

You can use the following basic request method for any instance to happen:

user = supr_client.users.get_edit_instance("__distinct_id__")
user.set_timezone("America/Los_Angeles")
user.set("name", "John Doe")
res = supr_client.users.async_edit(user)
print(res)

Sample Response:

📘

To save the changes made by executing the helper methods, use the statement:res = supr_client.users.async_edit(u)in order to save your changes, before running your defined function.

For a better hint, you might find the #Save changes and run the funtioncomment written below for the statement to be used.

Sanple response for this...

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

📘

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.

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

# Add Email
user.add_email("[email protected]")

# Add SMS
user.add_sms("+9987654321")

# Add WhatsApp
user.add_whatsapp("+91987654321")

# Add Android push token (with vendor)
user.add_androidpush("androidpush_token__2", "fcm")

# Add iOS push token
user.add_iospush("iospush_token__2", "ios")

# Add Slack using email
user.add_slack({"email": "[email protected]", "access_token": "xoxc-2054145879603-38XXXXXXX9856-Les61fkeOXXXXXXXXYOR3p"})

# Add Slack using user_id
slack_ident_user_id = {"access_token": "xoxc-XXXXXXXX", "user_id": "U06XXXXXXXX"}
user.add_slack(slack_ident_user_id)

# Add Slack using channel_id
slack_ident_channel = {"access_token": "xoxc-XXXXXXXX", "channel_id": "C06XXXXXXXX"}
user.add_slack(slack_ident_channel)

# Add Slack incoming webhook
slack_webhook = {"incoming_webhook": {"url": "https://hooks.slack.com/services/TXXXXXXXXX/BXXXXXXXX/XXXXXXXXXXXXXXXXXXX"}}
user.add_slack(slack_webhook)

# Add Webpush token (VAPID)
user.add_webpush(webpush_token, "vapid")

Sample Response

When you call supr_client.user.get_edit_instance(distinct_id), the response will immediately indicate whether the request was successful or if the user was not found. If successful, the response will contain the user's current attributes.

{'success': True, 'status': 'success', 'status_code': 202, 'message': 'OK'}

Remove Channels

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

# Remove Email
user.remove_email("[email protected]")

# Remove SMS
user.remove_sms("+91987654321")

# Remove WhatsApp
user.remove_whatsapp("+91987654321")

# Remove Android Push token (pass vendor as second param)
user.remove_androidpush("androidpush_fcm_token__", "fcm")

# Remove iOS Push token
user.remove_iospush("__iospush_apns_token__")

# Remove Slack using user email ID
user.remove_slack({"email": "[email protected]", "access_token": "xoxb-2054145879603-3805442439856-Les61fkeOLmbuFwqshPYOR3p"})

# Remove Slack using member_id
slack_ident_user = {"access_token": "xoxb-XXXXXXXX", "user_id": "U03XXXXXXXX"}
user.remove_slack(slack_ident_user)

# Remove Slack channel_id
slack_ident_channel = {"access_token": "xoxb-XXXXXXXX", "channel_id": "C04XXXXXXXX"}
user.remove_slack(slack_ident_channel)

# Remove Slack incoming webhook
slack_ident_webhook = {"incoming_webhook": {"url": "https://hooks.slack.com/services/TXXXXXXXXX/BXXXXXXXX/XXXXXXXXXXXXXXXXXXX"}}
user.remove_slack(slack_ident_webhook)

# Remove WebPush token JSON (VAPID)
webpush = {
  "endpoint": "__end_point__",
  "expirationTime": "",
  "keys": {
    "p256dh": "__p256dh__",
    "auth": "__auth_key__"
  }
}
user.remove_webpush(webpush, "vapid")

Sample Response

When you call supr_client.user.get_edit_instance(distinct_id), the response will immediately indicate whether the request was successful or if the user was not found. If successful, the response will contain the user's current attributes.

{'success': True, 'status': 'success', 'status_code': 202, 'message': 'OK'}

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)

# Unset a single channel (e.g., removing all emails associated with the user)
user.unset(["$email"])

# Unset multiple channels in one call
channels = ["$email", "$slack", "$androidpush", "$iospush", "$webpush", "$whatsapp"]
user.unset(channels)

🚧

Note

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

Other Edit Methods

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.

Moreover, you can also set custom properties in user profile that is used to set user preferences.

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

Sample Response

When you call supr_client.users.async_edit(u), 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 for success
{
    "success": True, # if true, request was accepted.
    "status": "success",
    "status_code": 202, # http status code
    "message": "OK",
}

#Response Structure for Failure
{
    "success": False, # error will be present in message
    "status": "fail",
    "status_code": 500, # http status code
    "message": "error message",
}

2. Set Timezone

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

# Add timezone to user-instance.

user.set_timezone("America/Los_Angeles")

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

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

# set single property using key and value
user.set("name", "user")
# set multiple/nested properties using dictionary
user.set({
  "prop1": "val1", 
  "prop2": ["one", "two", "three"], 
  "number": 20
})
ParametersTypeDescription
arg1string/dictionaryMandatory
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_
arg2anyOptional
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.

4. 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.Suprsend("WORKSPACE_KEY", "WORKSPACE_SECRET")

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

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

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

5. 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.Suprsend("WORKSPACE_KEY", "WORKSPACE_SECRET")

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

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

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

6. Append

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

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

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

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

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

7. Remove

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

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

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

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

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

8. Unset

This will remove a property permanently from user properties.


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

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

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

# For unsetting multiple properties:
user.unset(["wishlist", "cart"])
ParametersTypeDescription
keystringThis property provided will be deleted from user properties
property_listarray[string]If list is given all properties included in list will be removed.

Bulk User Update

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.

# Creating bulk instance
bulk_ins = supr_client.users.get_bulk_edit_instance()

# Prepare multiple users
distinct_id1 = "__distinct_id1__"  # User 1
u1 = supr_client.users.get_edit_instance(distinct_id1)
u1.add_email("[email protected]")

distinct_id2 = "__distinct_id2__"  # User 2
u2 = supr_client.users.get_edit_instance(distinct_id2)
u2.add_email("[email protected]")

# Append users to the bulk instance
bulk_ins.append(u1, u2)

🚧

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.

Sample Response

Response is an instance of suprsend.BulkResponse class

{
  "users": [
    {
      "distinct_id": "__distinct_id1__",
      "email": ["[email protected]"]
    },
    {
      "distinct_id": "__distinct_id2__",
      "email": ["[email protected]"]
    }
  ]
}

Get User details

Fetch User by passing distinct_id

distinct_id = "__distinct_id__"

res = supr_client.users.get(distinct_id)
print(res)

Sample Response

{
  "distinct_id": "__distinct_id__",
  "properties": {
    "name": "John Doe",
    "email": ["[email protected]"],
    "phone": "+1234567890",
    "created_at": "2024-01-01T12:00:00Z"
  },
  "status": "active"
}

Delete User

Delete User by passing distinct_id. Delete action will take into immediate effect.

res = supr_client.users.delete("__distinct_id__")

print(res)

Get list of objects subscribed by user

You can pass optional query parameters -limit, before, after

res = supr_client.users.get_objects_subscribed_to("__distinct_id__", {"after": "01JJW6HXXXXPB59ARDW85G0KN", "limit": 1})
print(res)

Sample Responses

If the user has subscribed objects, the expected response could be:

{
  "objects": [
    {
      "object_id": "object_123",
      "type": "notification_topic",
      "subscribed_at": "2024-02-20T10:15:30Z"
    }
  ],
  "paging": {
    "after": "01JJW6HXXXXPB59ARDW85G0KN",
    "has_more": false
  }
}

Get lists subscribed by user

You can pass optional query parameters -limit, before, after

res = supr_client.users.get_lists_subscribed_to("__distinct_id__",
	{"after": "01JJW6HXXXXPB59ARDW85G0KN", "limit": 1})

print(res)

Sample Response

{
  "lists": [
    {
      "list_id": "marketing_updates",
      "subscribed_at": "2024-02-20T12:00:00Z",
      "status": "subscribed"
    }
  ],
  "paging": {
    "after": "01JJW6HXXXXPB59ARDW85G0KN",
    "has_more": true
  }
}

Updated 24 days 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