Objects

Objects in SuprSend represent non-user entities such as organizations, teams, roles, and projects. You can leverage objects to:

Send Group Notifications: Direct notifications to group channels like team emails, Slack channels, or a shared Inbox feed.
Notify Object Subscribers: Send notifications to all users subscribed to an object without passing individual users in the trigger. For instance, if you need to send invoicing alerts to all finance team members, you can create a “Finance” object and add team members as subscribers. Triggering the notification for the finance object then automatically sends it to all subscribed finance team members.

Each object can have unique channels, preferences, and properties, which are used to send notification to object as a recipient. Every notification trigger is sent to individually to object + its susbscribers.

📘
Objects are advanced way of modelling user triggers in SuprSend. If you are new to SuprSend, we recommend you to try out basic workflow trigger with user first before jumping into object implementation.

How object trigger works?

When you trigger notification on an object, It fans out and send notifications to object and all its subscribers. The object acts as an independent recipient of the notification, so if it has two subscribers, the notification will be sent to:

The object as a recipient (channels, properties and preferences defined at object are used in this workflow).
Its 2 subscribers.

Importantly, object settings (properties, channels, and preferences) apply when sending to object as a recipient; these settings are not applied when sending to individual object subscribers.

Creating Objects in SuprSend

Each object in SuprSend is organized by a type, grouping similar objects together. Objects are uniquely identified by an {id, object_type} pair in all API calls. Follow these conventions when defining object types and IDs:

Object Type: Use plural names where possible to reflect a collection of similar objects, such as teams, projects, or customers.
Object ID: Choose a stable, unique identifier, ideally the primary key from your system. This ensures easy reference, as object IDs are immutable once created.

Objects largely follows the same schema and profile update methods as user. You can create objects in a separate API call or inline within workflow trigger.

Object creation API ->

Creating objects in a separate API call before trigger: This is an ideal approach for updating objects especially if you are using object to send notification to its subscribers.

curl --request POST \
--url https://hub.suprsend.com/v1/object/:object_type/:id/ \
--header 'Authorization: Bearer <API_KEY>' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
  "name": "__Object_name__",
  "prop1": "value1",
  "nested_props": {
    "prop2": "value2",
  },
  "$email": ["[email protected]"],
  "$timezone": "UTC",
  "$preferred_language": "en"
}'

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

// Initialize SDK
const supr_client = new Suprsend("__workspace_uid__", "__worksapce_secret__")
// upsert object
const object_properties = {
  "name": "__Object_name__",
  "prop1": "value1",
  "nested_props": {
    "prop2": "value2",
  },
  "$email": ["[email protected]"],
  "$timezone": "UTC",
  "$preferred_language": "en"
}
res = supr_client.objects.upsert("__object_type__", "__object_id__", object_properties);
res.then((res) => console.log(res)).catch((err) => console.log(err));

from suprsend import Suprsend

# Initialize SDK
supr_client = Suprsend("<WORKSPACE_KEY>", "<WORKSPACE_SECRET>>")

properties = {
    "name": "__Object_name__",
    "prop1": "value1",
    "nested_props": {
        "prop2": "value2",
    },
    "$email": ["[email protected]"],
    "$timezone": "UTC",
    "$preferred_language": "en"
}
obj = supr_client.objects.upsert("_object_type_", "__object_id__", properties)
print(obj)

Adding objects inline in workflow trigger: Objects are generally defined inline if you are sending notification to object as a recipient and need to add its channels or properties in the trigger.

curl --request POST \
--url https://hub.suprsend.com/trigger/ \
--header 'Authorization: Bearer <API_KEY>' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
    "workflow": "_workflow_slug_",
    "recipients": [
        {
            "object_type": "teams",
            "id": "product",
            "total_members": 4
        },
        {
           "object_type": "teams",
            "id": "devs",
            "total_members": 20
        }
    ],
    "data": {
        "key": {
            "k1": "v1",
            "k2": "v2"
        }
    }
}
'

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

// Initialize SDK
const supr_client = new Suprsend("__workspace_uid__", "__worksapce_secret__")

wf_trigger_req = new WorkflowTriggerRequest(
    body = {
        "workflow": "_workflow_slug_",
        "recipients": [
            {
                "object_type": "teams",
                "id": "product",
                "total_members": 4
            },
            {
                "object_type": "teams",
                "id": "devs",
                "total_members": 20
            }
        ],
        "data": {
            "key": {
                "k1": "v1",
                "k2": "v2"
            }
        }
    }
)

res = supr_client.workflows.trigger(wf_trigger_req);
res.then((res) => console.log(res)).catch((err) => console.log(err));

from suprsend import Workflow, WorkflowTriggerRequest, Suprsend
supr_client = suprsend.Suprsend("<WORKSPACE_KEY>", "<WORKSPACE_SECRET>", debug=True)

w = WorkflowTriggerRequest(
    body={
        "workflow": "_workflow_slug_",
        "recipients": [
            {
                "object_type": "teams",
                "id": "product",
                "total_members": 4
            },
            {
               "object_type": "teams",
                "id": "devs",
                "total_members": 20
            }
        ],
        "data": {
            "key": {
                "k1": "v1",
                "k2": "v2"
            }
        }
    }
)
res = supr_client.workflows.trigger(w)
print(res)

Object Subscribers

You can add users or other objects as object subscribers and when a workflow is trigger on the object, SuprSend will automatically fan out and run a workflow for every subscriber on that object. Learn more about subscription here .

📘
Nested object hierarchies: Object subscriptions support hierarchical structures, allowing one object to subscribe to another. For example, if you create a customer object with associated team objects subscriber to customer object and team members are subscribed to their respective team objects. Now, when you trigger workflow on the customer object as recipient, it will propagate through this hierarchy and all teams and their team members will be notified.

SuprSend allows inline creation of users or objects when subscribing them to an object, so there's no need to pre-create them in the system. You can add subscription properties to define the relationship of subscriber to the object and can be referenced as variable in template or workflow under recipient.subscription namespace.

curl --request POST \
--url https://hub.suprsend.com/v1/object/:object_type/:object_id/subscription/ \
--header 'Authorization: Bearer <API_KEY>' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
  "recipients": [
    {
      "distinct_id": "0gxxx9f14-xxxx-23c5-1902-xxxcb6912ab09",
      "$email": ["[email protected]"],
      "role": "CEO"
    },
    {
      "object_type": "teams",
      "id": "product"
    },
    {
      "object_type": "teams",
      "id": "devs"
    }

  ],
    "properties": {
      "team_location":"Austin, Texas"
    }
}'

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

// Initialize SDK
const supr_client = new Suprsend("__workspace_uid__", "__worksapce_secret__")

res = supr_client.objects.create_subscriptions("_object_type_", "_object_id_", {
    recipients: [
        {
            "distinct_id": "0gxxx9f14-xxxx-23c5-1902-xxxcb6912ab09",
            "$email": ["[email protected]"],
            "role": "CEO"
        },
        {
            "object_type": "teams",
            "id": "product"
        },
        {
            "object_type": "teams",
            "id": "devs"
        }

    ],
    properties: {
        "team_location":"Austin, Texas"
    }
});
res.then((res) => console.log(res)).catch((err) => console.log(err));

from suprsend import Suprsend

# Initialize SDK
supr_client = Suprsend("<WORKSPACE_KEY>", "<WORKSPACE_SECRET>>")

subscription_payload = {
    "recipients": [
        {
            "distinct_id": "0gxxx9f14-xxxx-23c5-1902-xxxcb6912ab09",
            "$email": ["[email protected]"],
            "role": "CEO"
        },
        {
            "object_type": "teams",
            "id": "product"
        },
        {
            "object_type": "teams",
            "id": "devs"
        }

    ],
    "properties": {
        "team_location": "Austin, Texas"
    }
}
obj = supr_client.objects.create_subscriptions("_object_type_", "__object_id__", subscription_payload)
print(obj)

Triggering Workflow

You can trigger workflow on the created object by passing object_type and id as recipient in API based trigger. Event trigger doesn't support triggering on objects.

curl --location 'https://hub.suprsend.com/trigger/' \
--header 'Authorization: Bearer <API_KEY>' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
    "workflow": "_workflow_slug_",
    "recipients": [
        {
            "object_type": "teams",
            "id": "product",
            "total_members": 4
        }
    ],
    "actor": {
        "distinct_id": "0fxxx8f74-xxxx-41c5-8752-xxxcb6911fb08",
        "name": "actor_1"
    },
    "data": {
        "key": {
            "k1": "v1",
            "k2": "v2"
        }
    }
}'

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

// Initialize SDK
const supr_client = new Suprsend("__workspace_uid__", "__worksapce_secret__")

wf_trigger_req = new WorkflowTriggerRequest(
    body = {
        "workflow": "_workflow_slug_",
        "recipients": [
            {
                "object_type": "teams",
                "id": "product",
                "total_members": 4
            }
        ],
        "actor": {
            "distinct_id": "0fxxx8f74-xxxx-41c5-8752-xxxcb6911fb08",
            "name": "actor_1"
        },
        "data": {
            "key": {
                "k1": "v1",
                "k2": "v2"
            }
        }
    }
)

from suprsend import Workflow, WorkflowTriggerRequest, Suprsend

supr_client = Suprsend("<WORKSPACE_KEY>", "<WORKSPACE_SECRET>", debug=True)

w = WorkflowTriggerRequest(
    body={
        "workflow": "_workflow_slug_",
        "recipients": [
            {
                "object_type": "teams",
                "id": "product",
                "total_members": 4
            }
        ],
        "actor": {
            "distinct_id": "0fxxx8f74-xxxx-41c5-8752-xxxcb6911fb08",
            "name": "actor_1"
        },
        "data": {
            "key": {
                "k1": "v1",
                "k2": "v2"
            }
        }
    }
)
res = supr_client.workflows.trigger(w)
print(res)

Updating Object Profile and Preferences

You can update channels, properties, and preferences for an object in the same way as for a user. These updates apply when sending notifications to the object itself as the recipient. Object profiles can be modified in the SuprSend UI for testing purposes, or programmatically through the object upsert API or edit operations API. Updating object preferences follows the same approach as updating user preferences: in the API call, you pass the identifier as :object_type/:id instead of :distinct_id.

Refer all object APIs here ->