Segments API

Δημιουργήστε και διαχειριστείτε δυναμικά τμήματα χρηστών προγραμματιστικά.

Όλα τα endpoints αυτής της σελίδας είναι σχετικά ως προς το βασικό URL: https://api-eu1.joryio.com/api - δείτε Επισκόπηση API.

Έλεγχος ταυτότητας

Όλα τα αιτήματα απαιτούν έλεγχο ταυτότητας με κλειδί API:

Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json

Δημιουργία τμήματος

Δημιουργήστε ένα νέο τμήμα χρηστών με φίλτρα.

Endpoint

POST /segments

Σώμα αιτήματος

Πεδίο	Τύπος	Απαιτείται	Περιγραφή
`name`	string	Ναι	Όνομα τμήματος (μέγιστο 255 χαρακτήρες)
`description`	string	Όχι	Περιγραφή τμήματος (μέγιστο 1000 χαρακτήρες)
`filterGroups`	array	Ναι	Πίνακας ομάδων φίλτρων (μέγιστο 20)
`excludeFilterGroups`	array	Όχι	Οι χρήστες που ταιριάζουν σε οποιαδήποτε από αυτές τις ομάδες αφαιρούνται (μέγιστο 20)
`groupOperator`	string	Ναι	Πώς συνδυάζονται οι ομάδες: `AND` ή `OR`
`includeCrawlers`	boolean	Όχι	Να μετρούνται τα προφίλ crawler (bot) ως μέλη. Προεπιλογή `false` - η σελίδα Κοινό τα κρύβει επίσης.
`tags`	array	Όχι	Ονόματα ετικετών για την οργάνωση τμημάτων

Δομή φίλτρων

Κάθε ομάδα φίλτρων περιέχει έως 50 φίλτρα:

{
  filters: [
    {
      type: 'attribute' | 'default_attribute' | 'event' | 'ecommerce'
          | 'behavioral' | 'segment' | 'canvas_execution'
          | 'list_membership' | 'channel_subscription' | 'app'
          | 'entity' | 'bounce_status' | 'wallet_pass'
          | 'warehouse_sync' | 'device' | 'random_bucket'
          | 'contact_import' | 'message_activity',
      field?: string,           // For attribute filters
      operator: string,         // See Filter Operators below
      value?: any,              // Comparison value (also carries N for count operators)
      eventName?: string,       // For event filters
      withinDays?: number,      // Time window for event filters
      startDate?: string,       // Absolute window start (ISO 8601, event filters)
      endDate?: string,         // Absolute window end (ISO 8601, event filters)
      segmentId?: string,       // For segment filters
      listId?: string,          // For list_membership filters
      channel?: string          // For channel_subscription filters
    }
  ],
  operator: 'AND' | 'OR'
}

Ένα φίλτρο random_bucket συγκρίνει τον σταθερό αριθμό τυχαίου κάδου της επαφής (0-9999, δεν αλλάζει ποτέ για ένα άτομο): το operator είναι ένα από τα equals, not_equals, less_than, less_than_or_equal, greater_than, greater_than_or_equal, between· το value είναι ακέραιος από 0 έως 9999, ή [from, to] για το between (περιλαμβάνονται και τα δύο άκρα). Κάθε άλλη τιμή απορρίπτεται με 400. Δείτε Αριθμός τυχαίου κάδου.

Ένα φίλτρο contact_import ("Προήλθε από εισαγωγή") ταιριάζει επαφές με βάση τις εισαγωγές επαφών που τις δημιούργησαν ή τις ενημέρωσαν: το operator είναι any_of ή none_of και το value είναι λίστα 1 έως 100 αναγνωριστικών εισαγωγής από το GET /users/import/sources. Το none_of περιλαμβάνει επαφές που δεν άγγιξε καμία εισαγωγή. Μια κενή λίστα απορρίπτεται με 400. Οι επαφές που εισήχθησαν πριν κυκλοφορήσει αυτή η δυνατότητα δεν είναι σημαδεμένες, οπότε ταιριάζουν μόνο με το none_of. Δείτε Προήλθε από εισαγωγή.

Ένα φίλτρο message_activity ("Δραστηριότητα μηνυμάτων") ταιριάζει άτομα με βάση το τι συνέβη στα μηνύματα που τους στάλθηκαν. Το operator είναι η ενέργεια: received (το συμβάν message.sent), delivered, opened, clicked, bounced, unsubscribed ή failed. Το messageSource είναι campaign (με campaignId), campaign_tag (με tagIds), any_campaign, journey (με canvasId), journey_step (με canvasId και nodeId), journey_tag (με tagIds) ή any. Το messageChannel είναι any ή ένα από τα email, sms, push, whatsapp, in_app, webhook, viber - μόνο κανάλι που αναφέρει την ενέργεια (όχι opened για sms, push ή webhook· το bounced μόνο για email). Το messageWindow είναι ever, in_last_days ή not_in_last_days (value = ημέρες, 1 έως 3650), between_dates (startDate και endDate), at_least (value = φορές, τουλάχιστον 1) ή at_most (value = φορές, 0 ή περισσότερες). Το tagIds είναι λίστα αναγνωριστικών ετικετών (από το GET /tags), όπου πολλά σημαίνουν οποιαδήποτε από αυτές τις ετικέτες· ταιριάζει στις καμπάνιες ή στα ταξίδια που φέρουν την ετικέτα τη στιγμή που υπολογίζεται το κοινό, και η μετονομασία της ετικέτας δεν το αλλάζει. Ένα φίλτρο που αποθηκεύτηκε με όνομα ετικέτας στο tag λειτουργεί ακόμα και αποθηκεύεται με αναγνωριστικό στην επόμενη αποθήκευση· ένα όνομα που δεν φέρει καμία ετικέτα απορρίπτεται με 400. Οτιδήποτε άλλο απορρίπτεται με 400. Παράδειγμα: { "type": "message_activity", "operator": "opened", "messageSource": "any_campaign", "messageChannel": "email", "messageWindow": "in_last_days", "value": 30 }. Δείτε Δραστηριότητα μηνυμάτων.

Το opened σε email ή any ακολουθεί τον κανόνα ανοίγματος: ταιριάζει και με το κλικ ενός ατόμου στο email, επειδή ένα κλικ αποδεικνύει ότι το email ανοίχτηκε, και με at_least / at_most συγκρίνει τη μεγαλύτερη από τις μετρήσεις ανοιγμάτων και κλικ στο email. Ανοίγματα από bots και κλικ από σαρωτές συνδέσμων δεν μετράνε ποτέ.

Ένα φίλτρο canvas_execution δέχεται επίσης nodeId μαζί με ένα canvasId - η εκτέλεση του ατόμου έφτασε σε αυτό το βήμα του ταξιδιού (οποιοσδήποτε τύπος κόμβου) - και τους τελεστές in_tagged_canvas / not_in_tagged_canvas με tagIds αντί για canvasId: σε (ή όχι σε) οποιοδήποτε ταξίδι φέρει την ετικέτα. Με nodeId, το stepWindow το περιορίζει στο πότε η εκτέλεση μπήκε τελευταία φορά στο βήμα: ever (προεπιλογή), in_last_days (withinDays, 1 έως 3650) ή between_dates (startDate και endDate). Ένας τελεστής ενός ταξιδιού (in_canvas, not_in_canvas, completed_canvas, exited_canvas) αποθηκευμένος χωρίς canvasId δεν ταιριάζει σε κανέναν. Δείτε Εκτέλεση Canvas.

Παράδειγμα αιτήματος - Απλό φίλτρο γνωρίσματος

curl -X POST https://api-eu1.joryio.com/api/segments \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Users",
    "description": "Users on premium plan",
    "filterGroups": [
      {
        "filters": [
          {
            "type": "attribute",
            "field": "plan",
            "operator": "equals",
            "value": "premium"
          }
        ],
        "operator": "AND"
      }
    ],
    "groupOperator": "AND"
  }'

Παράδειγμα αιτήματος - Τμήμα συμπεριφοράς

curl -X POST https://api-eu1.joryio.com/api/segments \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active Trial Users",
    "description": "Trial users active in last 7 days",
    "filterGroups": [
      {
        "filters": [
          {
            "type": "attribute",
            "field": "plan",
            "operator": "equals",
            "value": "trial"
          },
          {
            "type": "event",
            "eventName": "Session Started",
            "operator": "performed",
            "withinDays": 7
          }
        ],
        "operator": "AND"
      }
    ],
    "groupOperator": "AND"
  }'

Παράδειγμα αιτήματος - Σύνθετο τμήμα

curl -X POST https://api-eu1.joryio.com/api/segments \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-Value At-Risk Users",
    "description": "Paid users with high LTV who haven'\''t logged in recently",
    "filterGroups": [
      {
        "filters": [
          {
            "type": "attribute",
            "field": "plan",
            "operator": "in",
            "value": ["premium", "enterprise"]
          },
          {
            "type": "attribute",
            "field": "lifetimeValue",
            "operator": "gte",
            "value": 500
          }
        ],
        "operator": "AND"
      },
      {
        "filters": [
          {
            "type": "event",
            "eventName": "Login",
            "operator": "not_performed",
            "withinDays": 14
          }
        ],
        "operator": "AND"
      }
    ],
    "groupOperator": "AND"
  }'

Απόκριση

Το αντικείμενο του τμήματος επιστρέφεται απευθείας (χωρίς περιτύλιγμα-φάκελο). Τα IDs τμημάτων είναι UUID. Το πλήθος μελών δεν αποθηκεύεται στο τμήμα - χρησιμοποιήστε το GET /segments/:id/size:

{
  "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
  "name": "Premium Users",
  "description": "Users on premium plan",
  "filterGroups": [
    {
      "filters": [
        {
          "type": "attribute",
          "field": "plan",
          "operator": "equals",
          "value": "premium"
        }
      ],
      "operator": "AND"
    }
  ],
  "excludeFilterGroups": [],
  "groupOperator": "AND",
  "tags": [],
  "status": "active",
  "createdAt": "2024-01-20T10:30:00.000Z",
  "updatedAt": "2024-01-20T10:30:00.000Z"
}

Λήψη τμήματος

Ανάκτηση των λεπτομερειών ενός τμήματος.

Endpoint

GET /segments/:id

Παράμετροι διαδρομής

Παράμετρος	Τύπος	Περιγραφή
`id`	string	ID τμήματος

Παράδειγμα αιτήματος

curl -X GET https://api-eu1.joryio.com/api/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d \
  -H "Authorization: Bearer jry_live_your_api_key"

Απόκριση

Το αντικείμενο του τμήματος, επιστρεφόμενο απευθείας (για το τρέχον πλήθος μελών, καλέστε το GET /segments/:id/size):

{
  "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
  "name": "Premium Users",
  "description": "Users on premium plan",
  "filterGroups": [...],
  "excludeFilterGroups": [],
  "groupOperator": "AND",
  "tags": [],
  "status": "active",
  "createdAt": "2024-01-20T10:30:00.000Z",
  "updatedAt": "2024-01-20T10:30:00.000Z"
}

Λίστα τμημάτων

Λήψη όλων των τμημάτων με σελιδοποίηση.

Endpoint

GET /segments

Παράμετροι query

Παράμετρος	Τύπος	Προεπιλογή	Περιγραφή
`limit`	number	100	Αποτελέσματα ανά σελίδα (μέγιστο 100)
`offset`	number	0	Πλήθος τμημάτων που παραλείπονται
`q`	string	-	Αναζήτηση ελεύθερου κειμένου στο όνομα του τμήματος
`status`	string	-	Φιλτράρισμα βάσει κατάστασης: `active` ή `archived`
`tags`	string	-	Ονόματα ετικετών χωρισμένα με κόμμα
`createdBy`	string	-	IDs χρηστών-δημιουργών χωρισμένα με κόμμα
`editedBy`	string	-	IDs χρηστών-τελευταίων συντακτών χωρισμένα με κόμμα

Παράδειγμα αιτήματος

curl -X GET "https://api-eu1.joryio.com/api/segments?limit=50&status=active" \
  -H "Authorization: Bearer jry_live_your_api_key"

Απόκριση

{
  "data": [
    {
      "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
      "name": "Premium Users",
      "status": "active",
      "createdAt": "2024-01-20T10:30:00.000Z"
    },
    {
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "name": "Trial Users",
      "status": "active",
      "createdAt": "2024-01-19T09:15:00.000Z"
    }
  ],
  "pagination": {
    "total": 23,
    "page": 1,
    "limit": 50,
    "offset": 0,
    "totalPages": 1,
    "hasMore": false
  }
}

Ενημέρωση τμήματος

Ενημερώστε το όνομα, την περιγραφή ή τα φίλτρα του τμήματος. Χρησιμοποιεί PUT (δεν υπάρχει διαδρομή PATCH)· τα πεδία που παραλείπετε μένουν αμετάβλητα.

Endpoint

PUT /segments/:id

Σώμα αιτήματος

{
  "name": "Updated Name",
  "description": "Updated description",
  "filterGroups": [...]
}

Παράδειγμα αιτήματος

curl -X PUT https://api-eu1.joryio.com/api/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Premium users who have made at least one purchase"
  }'

Απόκριση

Το ενημερωμένο αντικείμενο του τμήματος, επιστρεφόμενο απευθείας:

{
  "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
  "name": "Premium Users",
  "description": "Premium users who have made at least one purchase",
  "status": "active",
  "updatedAt": "2024-01-21T14:30:00.000Z"
}

Αρχειοθέτηση τμήματος

Τα τμήματα δεν μπορούν να διαγραφούν οριστικά - καμπάνιες και journeys διατηρούν αναφορές σε τμήματα, οπότε η αφαίρεση γίνεται μόνο με αρχειοθέτηση. Τα αρχειοθετημένα τμήματα παύουν να εμφανίζονται στις ενεργές λίστες και μπορούν να επαναφερθούν οποιαδήποτε στιγμή.

Endpoints

POST /segments/:id/archive
POST /segments/:id/unarchive

Παράδειγμα αιτήματος

curl -X POST https://api-eu1.joryio.com/api/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/archive \
  -H "Authorization: Bearer jry_live_your_api_key"

Απόκριση

Το αντικείμενο του τμήματος με τη νέα του κατάσταση:

{
  "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
  "name": "Premium Users",
  "status": "archived",
  "updatedAt": "2024-01-21T14:30:00.000Z"
}

Σημειώσεις

Η αρχειοθέτηση ενός τμήματος δεν διαγράφει τους χρήστες του
Οι ενεργές καμπάνιες που χρησιμοποιούν αυτό το τμήμα θα επηρεαστούν
Χρησιμοποιήστε POST /segments/:id/unarchive για επαναφορά

Λήψη χρηστών τμήματος

Λήψη της λίστας χρηστών ενός τμήματος.

Endpoint

GET /segments/:id/users

Παράμετροι query

Παράμετρος	Τύπος	Προεπιλογή	Περιγραφή
`limit`	number	100	Πλήθος χρηστών που επιστρέφονται
`offset`	number	0	Πλήθος χρηστών που παραλείπονται

Παράδειγμα αιτήματος

curl -X GET "https://api-eu1.joryio.com/api/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/users?limit=100" \
  -H "Authorization: Bearer jry_live_your_api_key"

Απόκριση

Ένας σκέτος πίνακας JSON με έγγραφα χρηστών (χωρίς φάκελο σελιδοποίησης - σελιδοποιήστε με limit / offset):

[
  {
    "_id": "665f1e2a9b3c4d5e6f7a8b9c",
    "externalId": "user_123",
    "email": "[email protected]",
    "attributes": {
      "plan": "premium",
      "signupDate": "2024-01-15"
    }
  },
  {
    "_id": "665f1e2a9b3c4d5e6f7a8b9d",
    "externalId": "user_456",
    "email": "[email protected]",
    "attributes": {
      "plan": "premium",
      "signupDate": "2024-01-18"
    }
  }
]

Λήψη μεγέθους τμήματος

Λήψη του τρέχοντος πλήθους χρηστών ενός τμήματος. Από προεπιλογή είναι μια γρήγορη προσεγγιστική εκτίμηση· περάστε ?exact=true για ακριβή μέτρηση. Το μόνο που είναι ποτέ προσεγγιστικό είναι ο αριθμός του μεγέθους - η πραγματική συμμετοχή και οι αποστολές είναι πάντα ακριβείς.

Endpoint

GET /segments/:id/size

Παράμετροι query

Παράμετρος	Τύπος	Προεπιλογή	Περιγραφή
`exact`	boolean	false	Με `true` επιστρέφεται η ακριβής μέτρηση (πιο αργή σε μεγάλους χώρους εργασίας)

Παράδειγμα αιτήματος

curl -X GET https://api-eu1.joryio.com/api/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/size \
  -H "Authorization: Bearer jry_live_your_api_key"

Απόκριση

{
  "segmentId": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
  "size": 1234,
  "approximate": true
}

Τελεστές φίλτρων

Τελεστές γνωρισμάτων

Τελεστής	Περιγραφή	Παράδειγμα
`equals`	Ακριβής αντιστοίχιση	`plan equals "premium"`
`not_equals`	Διάφορο	`plan not_equals "free"`
`in`	Τιμή μέσα σε λίστα	`plan in ["premium", "enterprise"]`
`not_in`	Τιμή εκτός λίστας	`plan not_in ["free", "trial"]`
`contains`	Η συμβολοσειρά περιέχει	`email contains "@company.com"`
`not_contains`	Η συμβολοσειρά δεν περιέχει	`email not_contains "@competitor.com"`
`gt`	Μεγαλύτερο από	`lifetimeValue > 1000`
`gte`	Μεγαλύτερο ή ίσο	`age >= 18`
`lt`	Μικρότερο από	`loginCount < 5`
`lte`	Μικρότερο ή ίσο	`mrr <= 99`
`exists`	Το πεδίο υπάρχει	`phone exists`
`not_exists`	Το πεδίο δεν υπάρχει	`referralCode not_exists`
`within_next_days`	Ημερομηνία εντός των επόμενων N ημερών	`trialEndsDate within_next_days 7`

Επαφές χωρίς τιμή

Μια επαφή χωρίς τιμή στο πεδίο ταιριάζει με τους αρνητικούς τελεστές (not_equals, not_contains, not_in, not_exists) και με κανέναν από τους θετικούς (equals, contains, in, exists, gt, gte, lt, lte). Δείτε Επαφές χωρίς τιμή.

Τα αναγνωριστικά συγκρίνονται με ανοχή

Το email συγκρίνεται χωρίς διάκριση πεζών-κεφαλαίων από τα equals, not_equals, in και not_in - το [email protected] και το [email protected] είναι η ίδια διεύθυνση. Το phone συγκρίνεται με βάση τα ψηφία του από τους ίδιους τέσσερις τελεστές, οπότε τα +972501234567, 972501234567 και +972 50-123-4567 αντιστοιχούν όλα στην ίδια επαφή. Κάθε άλλο πεδίο συγκρίνεται ακριβώς όπως το δίνετε, συμπεριλαμβανομένου του externalId - τα δικά σας αναγνωριστικά παραμένουν ευαίσθητα στα πεζά-κεφαλαία.

Τελεστές συμβάντων

Τελεστής	Περιγραφή	Παράδειγμα
`performed`	Ο χρήστης εκτέλεσε το συμβάν	`Performed "Order Completed"`
`not_performed`	Ο χρήστης δεν εκτέλεσε το συμβάν	`Not performed "Onboarding Completed"`
`performed_count_gte`	Πλήθος συμβάντων μεγαλύτερο ή ίσο (το N στο `value`)	`Performed "Login" >= 10 times`
`performed_count_lte`	Πλήθος συμβάντων μικρότερο ή ίσο (το N στο `value`)	`Performed "Login" <= 5 times`
`performed_in_last_days`	Εκτελέστηκε τις τελευταίες N ημέρες (το N στο `value`)	`Performed "Login" in last 7 days`
`not_performed_in_last_days`	Δεν εκτελέστηκε τις τελευταίες N ημέρες (το N στο `value`)	`No "Login" in last 14 days`

Παραδείγματα φίλτρων

Φίλτρα γνωρισμάτων

// String matching
{
  "type": "attribute",
  "field": "email",
  "operator": "contains",
  "value": "@company.com"
}

// Numeric comparison
{
  "type": "attribute",
  "field": "lifetimeValue",
  "operator": "gte",
  "value": 500
}

// Multiple values
{
  "type": "attribute",
  "field": "plan",
  "operator": "in",
  "value": ["premium", "enterprise"]
}

// Field exists
{
  "type": "attribute",
  "field": "phone",
  "operator": "exists"
}

// Date within next N days (future dates)
{
  "type": "attribute",
  "field": "trialEndsDate",
  "operator": "within_next_days",
  "value": 7
}

Φίλτρα συμβάντων

// Event performed within timeframe
{
  "type": "event",
  "eventName": "Order Completed",
  "operator": "performed",
  "withinDays": 30
}

// Event not performed
{
  "type": "event",
  "eventName": "Onboarding Completed",
  "operator": "not_performed"
}

// Event count (N goes in `value`)
{
  "type": "event",
  "eventName": "Login",
  "operator": "performed_count_gte",
  "value": 10,
  "withinDays": 30
}

Φίλτρα τμημάτων

// User in another segment
{
  "type": "segment",
  "segmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "operator": "in_segment"
}

// User not in another segment
{
  "type": "segment",
  "segmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "operator": "not_in_segment"
}

Συνηθισμένα παραδείγματα τμημάτων

Ευκαιρία μετατροπής δοκιμής

{
  "name": "Trial Expiring Soon",
  "description": "Users whose trial ends in the next 3 days and haven't purchased",
  "filterGroups": [
    {
      "filters": [
        {
          "type": "attribute",
          "field": "plan",
          "operator": "equals",
          "value": "trial"
        },
        {
          "type": "attribute",
          "field": "trialEndsDate",
          "operator": "within_next_days",
          "value": 3
        },
        {
          "type": "event",
          "eventName": "Order Completed",
          "operator": "not_performed"
        }
      ],
      "operator": "AND"
    }
  ],
  "groupOperator": "AND"
}

Power users

{
  "name": "Power Users",
  "filterGroups": [
    {
      "filters": [
        {
          "type": "event",
          "eventName": "Login",
          "operator": "performed_count_gte",
          "value": 20,
          "withinDays": 30
        },
        {
          "type": "event",
          "eventName": "Feature Used",
          "operator": "performed_count_gte",
          "value": 50,
          "withinDays": 30
        }
      ],
      "operator": "AND"
    }
  ],
  "groupOperator": "AND"
}

Πελάτες σε κίνδυνο

{
  "name": "At-Risk Premium Users",
  "filterGroups": [
    {
      "filters": [
        {
          "type": "attribute",
          "field": "plan",
          "operator": "in",
          "value": ["premium", "enterprise"]
        },
        {
          "type": "attribute",
          "field": "lifetimeValue",
          "operator": "gte",
          "value": 500
        }
      ],
      "operator": "AND"
    },
    {
      "filters": [
        {
          "type": "event",
          "eventName": "Login",
          "operator": "not_performed",
          "withinDays": 14
        }
      ],
      "operator": "AND"
    }
  ],
  "groupOperator": "AND"
}

Δυναμικές ενημερώσεις

Τα τμήματα είναι δυναμικά: η συμμετοχή δεν είναι αποθηκευμένη λίστα - τα φίλτρα του τμήματος αξιολογούνται πάνω στα τρέχοντα δεδομένα προφίλ και συμβάντων κάθε φορά που το τμήμα χρησιμοποιείται (στόχευση καμπανιών, πύλες journeys, έλεγχοι συμμετοχής). Δεν υπάρχει τίποτα προς ανανέωση ή επανυπολογισμό μέσω του API.

Έλεγχος μεγέθους τμήματος

# Get current size (approximate by default; add ?exact=true for a precise count)
curl -X GET https://api-eu1.joryio.com/api/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/size \
  -H "Authorization: Bearer jry_live_your_api_key"

Αποκρίσεις σφαλμάτων

Όλα τα σφάλματα χρησιμοποιούν το τυπικό σώμα σφάλματος - δείτε Επισκόπηση API: Απόκριση σφάλματος.

400 Bad Request - Μη έγκυρο φίλτρο

{
  "statusCode": 400,
  "message": "Bad Request Exception",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/segments",
  "errors": [
    "filterGroups.0.filters.0.operator must be one of the following values: equals, not_equals, contains, ..."
  ]
}

404 Not Found

{
  "statusCode": 404,
  "message": "Segment with ID 3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d not found",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d"
}

Όρια ρυθμού

Το Segments API δεν έχει σήμερα σταθερά όρια ρυθμού ανά endpoint - δείτε Επισκόπηση API: Όρια ρυθμού.

Καλές πρακτικές

1. Κρατήστε τα τμήματα εστιασμένα

Σωστό: Συγκεκριμένα, στοχευμένα τμήματα

{
  "name": "Premium US Users - Active Last 7 Days",
  "filters": [...]
}

Λάθος: Υπερβολικά ευρεία τμήματα

{
  "name": "All Users",
  "filters": []
}

2. Χρησιμοποιείτε περιγραφικά ονόματα

Σωστό: Αυτονόητα ονόματα

«Trial Users - Expiring This Week»
«High-Value At-Risk Customers»
«New Signups - Not Onboarded»

Λάθος: Ασαφή ονόματα

«Segment 1»
«Test»
«Users ABC»

3. Συνδυάζετε τα φίλτρα λογικά

Χρησιμοποιήστε AND για στένεμα, OR για διεύρυνση:

// AND: Premium users who are active
{
  "filters": [
    { "field": "plan", "operator": "equals", "value": "premium" },
    { "eventName": "Login", "operator": "performed", "withinDays": 7 }
  ],
  "operator": "AND"
}

// OR: Users on any paid plan
{
  "filters": [
    { "field": "plan", "operator": "equals", "value": "premium" },
    { "field": "plan", "operator": "equals", "value": "enterprise" }
  ],
  "operator": "OR"
}

4. Παρακολουθείτε το μέγεθος του τμήματος

Παρακολουθήστε το μέγεθος του τμήματος στον χρόνο:

// Poll segment size
setInterval(async () => {
  const { size, approximate } = await fetch(`/segments/${segmentId}/size`).then(r => r.json());
  console.log(`Segment size: ${approximate ? '≈' : ''}${size}`);
}, 60000); // Every minute

Διατήρηση ενός τμήματος έτοιμου για αναφορές

Οι αναφορές που φιλτράρουν κατά τμήμα πρέπει πρώτα να υπολογίσουν ποιοι ανήκουν σε αυτό και να δώσουν αυτή τη λίστα ατόμων στη βάση αναλυτικών μαζί με το ερώτημα. Η λίστα είναι ο περιορισμός: μια σύγκριση διατήρησης αναλύει το πολύ 50.000 μέλη ενός τμήματος και παίρνει τυχαίο δείγμα όταν το τμήμα είναι μεγαλύτερο.

Η υλοποίηση (materialization) ενός τμήματος αποθηκεύει τα μέλη του στη βάση αναλυτικών, ώστε η αναφορά να κάνει JOIN και να μην ταξιδεύει καμία λίστα. Ο περιορισμός εξαφανίζεται σε οποιοδήποτε μέγεθος.

Είναι απενεργοποιημένη από προεπιλογή και ενεργοποιείται ανά τμήμα, επειδή το κόστος είναι μια νυχτερινή ανακατασκευή και τα περισσότερα τμήματα δεν χρησιμοποιούνται ποτέ σε αναφορά. Κάθε οργανισμός έχει ένα όριο κοινό για όλους τους χώρους εργασίας του - είκοσι από προεπιλογή. Ζητήστε μας να το αυξήσουμε.

Το αντάλλαγμα είναι η φρεσκάδα. Ένα υλοποιημένο τμήμα ανακατασκευάζεται κάθε βράδυ και όποτε το ζητήσετε, οπότε μια αναφορά διαβάζει τα μέλη όπως ήταν στην τελευταία ανακατασκευή και όχι αυτή τη στιγμή. Οι αναφορές δηλώνουν ποια χρονική σήμανση χρησιμοποίησαν.

Λήψη κατάστασης υλοποίησης

GET /segments/:id/materialization

curl -X GET https://api-eu1.joryio.com/api/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/materialization \
  -H "Authorization: Bearer jry_live_your_api_key"

{
  "materialized": true,
  "refreshedAt": "2026-09-03T03:00:00.000Z",
  "memberCount": 482103,
  "error": null,
  "used": 4,
  "quota": 20
}

Το refreshedAt είναι null μέχρι να ολοκληρωθεί η πρώτη ανακατασκευή. Το error λέει γιατί απέτυχε η τελευταία, ώστε ένα παλιό στιγμιότυπο να μπορεί να πει γιατί είναι παλιό· στο μεταξύ εξυπηρετεί η προηγούμενη λίστα μελών αντί να αδειάσει το τμήμα. quota ίσο με -1 σημαίνει απεριόριστο.

Όλα τα υλοποιημένα τμήματα του οργανισμού

GET /segments/materialization/usage

Το όριο, τι έχει δαπανηθεί και ποια τμήματα το δαπάνησαν - σε κάθε χώρο εργασίας του οργανισμού, κάτι που καμία προβολή ανά χώρο εργασίας δεν μπορεί να δείξει.

{
  "quota": 20,
  "used": 2,
  "segments": [
    {
      "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
      "name": "Champions",
      "workspaceId": "8c1f0b2a-91d4-4a77-9a3e-2d6f7b5c1e40",
      "refreshedAt": "2026-09-03T03:00:00.000Z",
      "memberCount": 1200,
      "error": null
    }
  ]
}

Ενεργοποίηση

POST /segments/:id/materialization

Η πρώτη κατασκευή τρέχει αμέσως, χωρίς να περιμένει τη νύχτα. Επιστρέφει το ίδιο αντικείμενο κατάστασης.

Επιστρέφει 400 όταν ο οργανισμός δεν έχει ελεύθερες θέσεις, κατονομάζοντας τα τμήματα που τις χρησιμοποιούν ώστε να επιλέξετε ποιο θα απενεργοποιήσετε.

Απενεργοποίηση

DELETE /segments/:id/materialization

Διαγράφει τα αποθηκευμένα μέλη και ελευθερώνει τη θέση.

Ανακατασκευή τώρα

POST /segments/:id/materialization/refresh

Επανυπολογίζει τα μέλη αμέσως. Τα μέλη ανακατασκευάζονται εξ ολοκλήρου και δεν προστίθενται απλώς, οπότε όσοι δεν πληρούν πια τα κριτήρια αφαιρούνται όπως προστίθενται οι νέοι - κάτι που μετράει, επειδή κάποιος φεύγει από ένα τμήμα χωρίς να κάνει τίποτα: ένας αγοραστής βγαίνει από το "καμία αγορά τις τελευταίες 30 ημέρες" απλώς επειδή προχώρησε το ημερολόγιο.

Έλεγχος φίλτρων πριν τα χρησιμοποιήσετε

Ένα σύνολο φίλτρων εύκολα βγαίνει διακριτικά λάθος, και το λάθος είναι σιωπηλό: επιστρέφει μικρότερο κοινό, όχι σφάλμα. Αυτές οι διαδρομές επιτρέπουν σε μια ενσωμάτωση να ελέγξει τη δουλειά της πριν εξαρτηθεί από αυτήν μια αποστολή.

Προεπισκόπηση κοινού

POST /segments/preview

Πόσες επαφές ταιριάζουν σε ένα σύνολο φίλτρων, χωρίς αποθήκευση τμήματος.

{ "count": 4820 }

Δείγμα χρηστών που ταιριάζουν

POST /segments/preview-users

Το ίδιο ερώτημα, επιστρέφοντας δείγμα των πραγματικών επαφών ώστε να δείτε αν είναι όντως τα άτομα που εννοούσατε.

Έλεγχος ενός χρήστη

POST /segments/check-user

Ταιριάζει αυτή η επαφή σε αυτό το σύνολο φίλτρων; Η ανά άτομο πύλη που χρειάζεται μια ενσωμάτωση όταν αποφασίζει για ένα πρόσωπο και όχι για ένα κοινό.

Απόκριση:

{ "userId": "user_123", "matches": true }

Ανάλυση ανά κανάλι

POST /segments/channel-breakdown

Πόσες από τις επαφές που ταιριάζουν είναι όντως προσβάσιμες σε κάθε κανάλι. Ένα τμήμα 10.000 με 400 τηλέφωνα δεν είναι κοινό SMS 10.000, και εδώ αυτό γίνεται ορατό πριν προγραμματίσετε την αποστολή.

Απόκριση:

{
  "email": 9210,
  "sms": 400,
  "push": 3110,
  "whatsapp": 280,
  "viber": 95,
  "matched": 10000,
  "capped": false
}

Το matched είναι ο πληθυσμός του οποίου τα ανά κανάλι πλήθη είναι υποσύνολο, και το capped είναι true όταν το τμήμα ήταν πολύ μεγάλο για ακριβή επίλυση (τα πλήθη αφορούν τότε το δείγμα που επιλύθηκε). Το πλήθος ενός καναλιού είναι ό,τι μπορεί πραγματικά να προσεγγίσει η διαδρομή αποστολής: μια εγγεγραμμένη επαφή χωρίς διεύθυνση, χωρίς τηλέφωνο ή χωρίς καταχωρημένη συσκευή δεν μετράει. Το μητρώο STOP και οι λίστες αποκλεισμού διευθύνσεων ελέγχονται ξανά κατά την αποστολή, οπότε μια πραγματική αποστολή μπορεί μόνο να είναι μικρότερη.

Μαζική δημιουργία και εξαγωγές

POST /segments/bulk
GET /segments/exports

Το POST /segments/bulk δημιουργεί πολλά τμήματα με μία κλήση - για να στήσετε έναν χώρο εργασίας από τη δική σας διαμόρφωση αντί για κλικ στο UI. Το GET /segments/exports δείχνει τις εργασίες εξαγωγής με την κατάστασή τους και το προϋπογεγραμμένο URL λήψης όταν τελειώσουν.

Επόμενα βήματα

Διαγραφή έναντι αρχειοθέτησης

POST   /segments/{segmentId}/archive
DELETE /segments/{segmentId}

Η αρχειοθέτηση είναι η προεπιλογή. Ένα αρχειοθετημένο τμήμα παύει να εμφανίζεται στους επιλογείς και στους ελέγχους συμμετοχής, ενώ κάθε καμπάνια ή ταξίδι που ήδη το χρησιμοποιεί συνεχίζει να λειτουργεί. Αντιστροφή: POST /segments/{segmentId}/unarchive.

Η διαγραφή το αφαιρεί οριστικά, και μόνο όταν τίποτα δεν το αναφέρει. Αν μια καμπάνια, ένα ταξίδι, μια καμπάνια εντός εφαρμογής ή άλλο τμήμα το χρησιμοποιεί ακόμη, το αίτημα επιστρέφει 409 και τα κατονομάζει.

Το GET /users/{userId}/segments αξιολογεί κάθε ΕΝΕΡΓΟ τμήμα έναντι της επαφής, οπότε ένας χώρος εργασίας που συσσωρεύει τμήματα τα πληρώνει σε κάθε έλεγχο συμμετοχής. Η αρχειοθέτηση ή η διαγραφή όσων δεν χρησιμοποιείτε είναι η λύση.

Έλεγχος ταυτότητας​

Δημιουργία τμήματος​

Endpoint​

Σώμα αιτήματος​

Δομή φίλτρων​

Παράδειγμα αιτήματος - Απλό φίλτρο γνωρίσματος​

Παράδειγμα αιτήματος - Τμήμα συμπεριφοράς​

Παράδειγμα αιτήματος - Σύνθετο τμήμα​

Απόκριση​

Λήψη τμήματος​

Endpoint​

Παράμετροι διαδρομής​

Παράδειγμα αιτήματος​

Απόκριση​

Λίστα τμημάτων​

Endpoint​

Παράμετροι query​

Παράδειγμα αιτήματος​

Απόκριση​

Ενημέρωση τμήματος​

Endpoint​

Σώμα αιτήματος​

Παράδειγμα αιτήματος​

Απόκριση​

Αρχειοθέτηση τμήματος​

Endpoints​

Παράδειγμα αιτήματος​

Απόκριση​

Σημειώσεις​

Λήψη χρηστών τμήματος​

Endpoint​

Παράμετροι query​

Παράδειγμα αιτήματος​

Απόκριση​

Λήψη μεγέθους τμήματος​

Endpoint​

Παράμετροι query​

Παράδειγμα αιτήματος​

Απόκριση​

Τελεστές φίλτρων​

Τελεστές γνωρισμάτων​

Τελεστές συμβάντων​

Παραδείγματα φίλτρων​

Φίλτρα γνωρισμάτων​

Φίλτρα συμβάντων​

Φίλτρα τμημάτων​

Συνηθισμένα παραδείγματα τμημάτων​

Ευκαιρία μετατροπής δοκιμής​

Power users​

Πελάτες σε κίνδυνο​

Δυναμικές ενημερώσεις​

Έλεγχος μεγέθους τμήματος​

Αποκρίσεις σφαλμάτων​

400 Bad Request - Μη έγκυρο φίλτρο​

404 Not Found​

Όρια ρυθμού​

Καλές πρακτικές​

1. Κρατήστε τα τμήματα εστιασμένα​

2. Χρησιμοποιείτε περιγραφικά ονόματα​

3. Συνδυάζετε τα φίλτρα λογικά​

4. Παρακολουθείτε το μέγεθος του τμήματος​

Διατήρηση ενός τμήματος έτοιμου για αναφορές​

Λήψη κατάστασης υλοποίησης​

Όλα τα υλοποιημένα τμήματα του οργανισμού​

Ενεργοποίηση​

Απενεργοποίηση​

Ανακατασκευή τώρα​

Έλεγχος φίλτρων πριν τα χρησιμοποιήσετε​

Προεπισκόπηση κοινού​

Δείγμα χρηστών που ταιριάζουν​

Έλεγχος ενός χρήστη​

Ανάλυση ανά κανάλι​

Μαζική δημιουργία και εξαγωγές​

Επόμενα βήματα​

Διαγραφή έναντι αρχειοθέτησης​

Έλεγχος ταυτότητας

Δημιουργία τμήματος

Endpoint

Σώμα αιτήματος

Δομή φίλτρων

Παράδειγμα αιτήματος - Απλό φίλτρο γνωρίσματος

Παράδειγμα αιτήματος - Τμήμα συμπεριφοράς

Παράδειγμα αιτήματος - Σύνθετο τμήμα

Απόκριση

Λήψη τμήματος

Endpoint

Παράμετροι διαδρομής

Παράδειγμα αιτήματος

Απόκριση

Λίστα τμημάτων

Endpoint

Παράμετροι query

Παράδειγμα αιτήματος

Απόκριση

Ενημέρωση τμήματος

Endpoint

Σώμα αιτήματος

Παράδειγμα αιτήματος

Απόκριση

Αρχειοθέτηση τμήματος

Endpoints

Παράδειγμα αιτήματος

Απόκριση

Σημειώσεις

Λήψη χρηστών τμήματος

Endpoint

Παράμετροι query

Παράδειγμα αιτήματος

Απόκριση

Λήψη μεγέθους τμήματος

Endpoint

Παράμετροι query

Παράδειγμα αιτήματος

Απόκριση

Τελεστές φίλτρων

Τελεστές γνωρισμάτων

Τελεστές συμβάντων

Παραδείγματα φίλτρων

Φίλτρα γνωρισμάτων

Φίλτρα συμβάντων

Φίλτρα τμημάτων

Συνηθισμένα παραδείγματα τμημάτων

Ευκαιρία μετατροπής δοκιμής

Power users

Πελάτες σε κίνδυνο

Δυναμικές ενημερώσεις

Έλεγχος μεγέθους τμήματος

Αποκρίσεις σφαλμάτων

400 Bad Request - Μη έγκυρο φίλτρο

404 Not Found

Όρια ρυθμού

Καλές πρακτικές

1. Κρατήστε τα τμήματα εστιασμένα

2. Χρησιμοποιείτε περιγραφικά ονόματα

3. Συνδυάζετε τα φίλτρα λογικά

4. Παρακολουθείτε το μέγεθος του τμήματος

Διατήρηση ενός τμήματος έτοιμου για αναφορές

Λήψη κατάστασης υλοποίησης

Όλα τα υλοποιημένα τμήματα του οργανισμού

Ενεργοποίηση

Απενεργοποίηση

Ανακατασκευή τώρα

Έλεγχος φίλτρων πριν τα χρησιμοποιήσετε

Προεπισκόπηση κοινού

Δείγμα χρηστών που ταιριάζουν

Έλεγχος ενός χρήστη

Ανάλυση ανά κανάλι

Μαζική δημιουργία και εξαγωγές

Επόμενα βήματα

Διαγραφή έναντι αρχειοθέτησης