Objects

Objects in SuprSend represent non-user entities such as organizations, teams , roles, and projects. Understand more about objects from our objects documentation

Upsert (create/update) an object

Object updating is an upsert function, meaning it would always override existing key values on further updates. Object id and type is mandatory to create object. You can optionally pass object properties (to use in template or workflow condition) or channel information (send notification on object channels) in the payload.

const {Suprsend} = require("@suprsend/node-sdk");

// Initialize SDK
const supr_client = new Suprsend("Workspace_Key", "Workspace_Secret")

res = supr_client.objects.upsert("object_type", "object_id");
res.then((res) => console.log(res)).catch((err) => console.log(err));

{
   "object_type":"departments",
   "id":"engineering",
   "subscriptions_count":0,
   "properties":{
      "key1": "val1"
      },
   "created_at":"2025-01-20T19:21:42.030343+00:00",
   "updated_at":"2025-02-14T14:06:05.928675+00:00",
   "$inbox":[
      {
         "value":"H4iGeGSHyXXXXXXSeuBb_PJGXXXgWu_LsXXXXXyiw",
         "id_provider":"suprsend",
         "status":"active",
         "perma_status":"active"
      }
   ],
	"$email":[
      {
         "value":"abc@example.com",
         "status":"active",
         "perma_status":"active"
      }
   ]
}

Edit an object

There are 2 ways in which you can edit an object data.

Build edit payload yourself
Use helper methods provided by SDK (Recommended)

1. Build edit payload yourself

Use this to modify an object, typically for removing channels or unsetting properties. The payload will follow the same structure as the Object Edit API.

//for all supported operations, refer API documentation
const payload = {operations: [{$unset: ["name"]}, {$remove: {"$email": "abc@example.com"}}]}

const response = await supr_client.objects.edit(object_type, object_id, payload};

{
   "object_type":"departments",
   "id":"engineering",
   "subscriptions_count":0,
   "properties":{
      "name":"John Doe"
   },
   "created_at":"2025-03-14T15:31:59.151061+00:00",
   "updated_at":"2025-03-14T15:31:59.182616+00:00",
   "$inbox":[
      {
         "value":"75Ev_m8yln0N_i1iXXXXXXr2eNOE_4ROXXXXXX1TgTc",
         "id_provider":"suprsend",
         "status":"active",
         "perma_status":"active"
      }
   ]
}

2. Edit using helper methods [Recommended]

It is possible to use the SDK’s helper methods to perform edit operations on an object. For this, first create object instance then call any of the helper methods mentioned below and finally save the changes.

// create instance
const object_instance = supr_client.objects.get_instance(object_type, object_id);

// call any helper methods
object_instance.set(key, value);
object_instance.add_email("johndoe@gmail.com");

// save the changes
const response = await supr_client.objects.edit(object_instance);

{
   "object_type":"departments",
   "id":"engineering",
   "subscriptions_count":0,
   "properties":{
      "$preferred_language":"en",
      "$timezone":"America/Los_Angeles",
      "company_name":"ABC company"
   },
   "created_at":"2025-03-04T08:34:58.061696+00:00",
   "updated_at":"2025-03-14T14:40:21.467156+00:00",
   "$inbox":[
      {
         "value":"dHvPs6pmUXXXXXXTAsfM2yroXXXX2CXZOtjXXXXXX8",
         "id_provider":"suprsend",
         "status":"active",
         "perma_status":"active"
      }
   ]
}

Here’s a list of all edit helper methods:

Add Channels

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

// add Email
object_instance.add_email("object_ins@example.com");

// add Email
object_instance.add_sms("+15555555555");

// add Whatsapp
object_instance.add_whatsapp("+15555555555");

// add fcm push token
object_instance.add_androidpush("__android_push_fcm_token__");

// add apns push token
object_instance.add_iospush("__iospush_token__");

// add Slack using email
object_instance.add_slack(
  {
    "email": "user@example.com",
    "access_token": "xoxb-XXXXXXXX"
  });

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

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

// add Slack incoming webhook
object_instance.add_slack(
  {
    "incoming_webhook": {
      "url": "https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX"
    }
  });

// add MS teams user or channel using conversation_id
object_instance.add_ms_teams(
  {
    "tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
    "service_url": "https://smba.trafficmanager.net/amer",
    "conversation_id": "19:c1524d7c-a06f-456f-8abe-xxxx"
  });

// add MS teams user using user_id
object_instance.add_ms_teams(
  {
    "tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
    "service_url": "https://smba.trafficmanager.net/amer",
    "object_ins_id": "29:1nsLcmJ2RKtYH6Cxxxx-xxxx"
  });

// add MS teams using incoming webhook
object_instance.add_ms_teams(
  {
    "incoming_webhook": {
      "url": "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"
    }
  });

Remove Channels

Use object_ins.remove_* method(s) to remove channels from an object profile

// remove Email
object_instance.remove_email("object_ins@example.com");

// remove SMS
object_instance.remove_sms("+15555555555");

// remove Whatsapp
object_instance.remove_whatsapp("+15555555555");

// remove fcm push token
object_instance.remove_androidpush("__android_push_fcm_token__"); // - by default, token is assumed to be fcm-token

// remove apns push token
object_instance.remove_iospush("__iospush_token__");

// remove Slack email
object_instance.remove_slack(
  {
    "email": "object_ins@example.com",
    "access_token": "xoxb-XXXXXXXX"
  });

// remove Slack if slack member_id is known
object_instance.remove_slack(
  {
    "object_ins_id": "U03XXXXXXXX",
    "access_token": "xoxb-XXXXXXXX"
  });

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

// remove Slack incoming webhook
object_instance.remove_slack(
  {
    "incoming_webhook": {
      "url": "https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX"
    }
  });

// add MS teams user or channel using conversation_id
object_instance.remove_ms_teams(
  {
    "tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
    "service_url": "https://smba.trafficmanager.net/amer",
    "conversation_id": "19:c1524d7c-a06f-456f-8abe-xxxx"
  });

// add MS teams user using user_id
object_instance.remove_ms_teams(
  {
    "tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
    "service_url": "https://smba.trafficmanager.net/amer",
    "object_ins_id": "29:1nsLcmJ2RKtYH6Cxxxx-xxxx"
  });

// add MS teams using incoming webhook
object_instance.remove_ms_teams(
  {
    "incoming_webhook": {
      "url": "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"
    }
  });

Remove Channels in bulk

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

object_instance.unset("$email");
object_instance.unset(["$email", "$sms", "$whatsapp"]);

// available channel keys -
//["$email","$whatsapp","$sms","$androidpush","$iospush","$webpush","$slack","$ms_teams"]

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

Set Preferred language

object_instance.set_preferred_language("en");

Set Preferred Timezone

object_instance.set_timezone("America/Belize");

Set

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

//For setting single property
object_instance.set("key", "value");

//For multiple Properties
object_instance.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 object 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.

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

Set Once

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

// For setting once a single property:
object_instance.set_once(key, value);
object_instance.set_once("first_login", "2021-11-02");

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

Increment

Add the given amount to an existing property on the object. If the object 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.

// For incrementing a single property:
object_instance.increment(key, value);
object_instance.increment("login_count", 1);

// For incrementing multiple properties:
object_instance.increment(property_obj);
object_instance.increment({"login_count" : 1, "remaining_credits" : -1});

Append

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

// For appending a single property:
object_instance.append.append(key, value);
object_instance.append.append("wishlist", "iphone12");

// For appending multiple properties:
object_instance.append.append(properties);
object_instance.append.append({"wishlist" : "iphone12", "cart" : "Apple airpods"});

Remove

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

// For removing a single property:
object_instance.remove(key, value);
object_instance.remove("wishlist", "iphone12");

// For removing multiple properties:
object_instance.remove(properties);
object_instance.remove({"wishlist" : "iphone12", "wishlist": "Apple airpods"});

Unset

This will remove a property permanently from properties.

// For unsetting a single property:
object_instance.unset(key);
object_instance.unset("wishlist");

// For unsetting multiple properties:
object_instance.unset(property_list);
object_instance.unset(["wishlist", "cart"]);

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

After calling add_*/remove_*/unset methods, don’t forget to call object_ins.save(). On call of save(), SDK sends the request to SuprSend platform to update the Object Profile.

List objects

List objects for an object_type. You can also pass listing options in the payload which includes limit,before,after

const response = await supr_client.objects.list(object_type,{"limit":10, "after:"cursor"});

Get object details

const response = await supr_client.objects.get(object_type, object_id);

Create subscriptions

const payload = {
  "recipients": ["recipient1", "recipient2"],
  "properties": {"role":"manager"}
}

const response = await supr_client.objects.create_subscriptions(object_type, object_id, payload);

List subscriptions

const response = await supr_client.objects.get_subscriptions(object_type, object_id,{"limit":10})

Remove object subscription

const payload = {"recipients": ["recipient1", "recipient2"]}

const response = await supr_client.objects.delete_subscriptions(object_type, object_id, payload)

Get list of objects subscribed by object

An object can subscribe to other objects. Use this method to get the list of all objects that the current object has subscribed to.

const response = await supr_client.objects.get_objects_subscribed_to(object_type, object_id);

Delete object

const response = await supr_client.objects.delete(object_type, object_id);

Bulk Delete object

const response = await supr_client.objects.bulk_delete(object_type, {object_ids: ["object_id1", "object_id2"]});

Developer Resources

Updates and Versioning

Authentication

Security

SDKs and APIs

Features

Testing

Monitoring and Logging

Upsert (create/update) an object

Edit an object

1. Build edit payload yourself

2. Edit using helper methods [Recommended]

List objects

Get object details

Create subscriptions

List subscriptions

Remove object subscription

Get list of objects subscribed by object

Delete object

Bulk Delete object

​Upsert (create/update) an object

​Edit an object

​1. Build edit payload yourself

​2. Edit using helper methods [Recommended]

​List objects

​Get object details

​Create subscriptions

​List subscriptions

​Remove object subscription

​Get list of objects subscribed by object

​Delete object

​Bulk Delete object

Upsert (create/update) an object

Edit an object

1. Build edit payload yourself

2. Edit using helper methods [Recommended]

List objects

Get object details

Create subscriptions

List subscriptions

Remove object subscription

Get list of objects subscribed by object

Delete object

Bulk Delete object