What's a segment?

Octy defines a segment as a group of profiles based on common characteristics and behaviors. Once recorded, you can use these segments to analyze customer characteristics and predict behaviors. Segments allow you to hyper-target your outreach, content and messaging. Reducing unnecessary advertisement costs, as well as increasing your rapport with existing customers. There are two primary-segment-types. Both primary-types have a set of sub-types that define the structure of the criteria of the segment.
You can specify a sequence of events (actions) that must occur or not occur (inactions) with specified time frames between each and in some cases required profile characteristics. Together this sequence of events and profile characteristics is recorded as a segment.
Basic example of a segments rule set:
  • Action - customer visits the checkout page.
  • Inaction - customer does not buy within 2 minutes.
A single action or a combination of a single action followed by a single inaction, in real time as they occur. You can specify a sequence of events that must have occurred (action) or not occurred (inaction) with specified time frames between each.
Example: ‘viewed the checkout page’ (action) and ‘did NOT create a charged event WITHIN 5 minutes time frame’ (inaction).
In the event of a profile meeting a live-segment's criteria, a web hook request will be made to your accounts specified webhook_url (in your account configurations), allowing your system to initiate any desired action immediately.
2 Live-segment sub-types:
notion image
A series of actions or a combination of actions and a single inaction that have occurred in the past with or without specified profile properties. You can specify a sequence of events that must have occurred (actions) or not occurred (inactions) within an overall time frame, example: within the last 30 days.
4 Past-segment sub-types:
notion image
Note: The specified property within past-segment sub-types 3 and 4 should be an existing key-value pair within one or more profiles profile_data attribute.

Create segment definitions

Segment definitions can be created by making a request to the /v1/retention/segments/create ↗️  endpoint.
A maximum of 1 segment definition can be created with any single request to the /v1/retention/segments/create ↗️  endpoint.
When creating a segment definition, a primary-type and sub-type must be specified.
You can specify the primary-type by setting the segment_type parameter to "live" or "past".
You can specify the segment sub-type by setting the sub_type parameter to a relative integer identifier, as defined above.
notion image
Rules when creating past and live-segment-types:
  • When creating a live-segment definition, the segment_timeframe parameter must have an integer value of "0".
  • The profile_property_name and profile_property_value parameters only need to be provided when creating a past-segment with a sub_type of 3 or 4.
  • The exp_timeframe parameter within an event_sequenceevent object MUST be set to an integer value of "0" if there are no subsequent events, or the segment_type parameter is set to "past"
  • The exp_timeframe parameter within an event_sequenceevent object MUST be set to an integer value equal to or greater than “5” (minutes) if there ARE subsequent events and the segment_type parameter is set to "live"
When defining a segment, there are a set of rules/guidelines to consider relative to the event_sequence parameter:
  • This is not mandatory, however, it is advised to only add existing event-types with event_properties, keys and desired values into the event_sequence parameter.
  • When providing event properties, you do not have to specify all the key : value pairs associated with the relevant event-type. However any provided keys must exist within the system event-type or custom event-type event_properties attribute. For example: the charged system event-type has two keys defined in its event_properties attribute, item_id and payment_method. Let’s say you wish to add an event to the event sequence, specifying that a customer must perform a charged event with any payment method, but for a specific item only. In this case, you would only need to provide the key-value pair item_id : "id of specific item". Optionally, you can provide a 'null' value for the event_properties parameter, signifying that all events of the specified event-type would meet this events criteria within the event sequence.
  • There is a maximum of 10 event objects allowed within the event_sequence parameter of each segment definition.
  • With each event object, it should be specified as to whether the event is required to happen (action) or not (inaction) by setting the action_inaction parameter to either "action" or "inaction".
  • Duplicate event-types with matching event_properties parameters cannot be supplied within the event_sequence parameter.
  • The first index of the event sequence array MUST always be an action, regardless of segment-type or sub-type.
  • Segments with a sub-type 2 or 4 (irrespective of primary-segment-type) MUST contain one inaction event in their event sequence. This inaction event must also always be the last index of the event sequence.
  • Segments with a sub-type 1 or 3 (irrespective of primary-segment-type) must NOT contain an 'inaction' event in their event sequence.
  • Live-segments with a sub-type 1, can only contain a singular 'action' event in their event sequence.
🖥️ CLI
octy-cli apply --filepath {path/to/segment-definitions.yml}
Example segment-definitions.yml :
kind: segments segmentDefinitions: # Customers who login and make a purchase within 5 minutes - segmentName: fast paying customers segmentType: live segmentSubtype: 2 segmentTimeframe: 0 eventSequence: - eventType: login expTimeframe: 5 actionInaction: action - eventType: charged expTimeframe: 0 actionInaction: inaction eventProperties: item_id : ios payment_method : visa profilePropertyName: profilePropertyValue: # Customers that have accessed your systems but made no purchase in the past 60 days - segmentName: worst customers segmentType: past segmentSubtype: 2 segmentTimeframe: 60 eventSequence: - eventType: login expTimeframe: 0 actionInaction: action - eventType: charged expTimeframe: 0 actionInaction: inaction profilePropertyName: profilePropertyValue:

Segment tags

If a profile's behaviours and properties meet the criteria for a defined segment, a segment tag will be added to the profiles segment_tags attribute, representing said segment.
  • A profile meets the criteria for a segment named best_customers.
  • A segment tag would be added to the existing array of segment_tags attribute for this profile.
Example of updated a profiles segment_tags attribute:
{ (Other profile attributes) ..., "segment_tags" : [ { "segment_tag" : "existing_segment_tag1", "created_at" : "Tue, 18 May 2021 17:26:45 GMT" }, { "segment_tag" : "existing_segment_tag2", "created_at" : "Wed, 19 May 2021 22:46:23 GMT" }, { "segment_tag" : "best_customers", "created_at" : "Thur, 20 May 2021 09:37:12 GMT" } ] }
Past-segment tags are removed from profiles automatically, once the profile no longer fits the segment criteria.
Live-segment tags are removed and or updated in profiles automatically, based on each profile's continued recorded event instances that conflict with existing live-segment tags.
Therefore the segment tags for each profile are always up-to-date and relevant.
Segment tags are used in model-training datasets and play a pivotal role in the accuracy of certain models.
Note: Segment tags can only be removed from a profile manually by deleting the segment definition for which they belong. Once a request is made to delete a segment definition, it can take up to 72 hours to delete the specified segment and all associated tags from the relevant profiles. The 'pending deletion' segment and tags will be deleted once a new model has been trained using a dataset with the updated attributes.

Next steps

Now that you have created segment definitions, it's time to generate some engaging personalized content at scale.
Go to the Messaging 🔗  section of this documentation to learn how messaging works with Octy.