30

Group

How it works

The group method is how you’ll associate a person with a group, like the company they work for or the school they attend. It’s a bit like an identify call, but for an organization instead of a person.

When you send a group call, you’ll include a groupId with an optional userId. Sending a userId associates the user with the group. A user can belong to multiple groups, so you can send group calls associating the same person with different groups.

When you send a group call, you can also include traits about the group. For example, if you use groups to represent companies, you might include the company’s industry, the number of employees, or the company’s billing date. You can send a group call without a userId if you simply want to update the traits for the group.

A typical call

A group call contains a groupId representing the group. You can also send an optional userId of the person you want to associate with the group and a traits object, which contains information about the group.

In the example below, you’ll notice that the group call looks a lot like an identify call! That’s because our JavaScript library automatically takes care of the userId (or anonymousId, if you haven’t identified a person yet) for you, associating the current user with the group.

analytics.group("0e8c78ea9d97a7b8185e8632", {
  name: "Acme",
  industry: "Technology",
  wile_e_coyote_accidents: 329,
  plan: "enterprise",
  total_billed: 830
});

If you use one of our server-side libraries, and you want to relate a person to a group, you’ll have to provide the userId or anonymousId yourself. Here’s an example from our NodeJS server-side library:

analytics.group({
  userId: '019mr8mf4r',
  groupId: '0e8c78ea9d97a7b8185e8632',
  traits: {
    name: "Acme",
    industry: "Technology",
    wile_e_coyote_accidents: 329,
    plan: "enterprise",
    total_billed: 830
  }
});

While this is the general shape of your call, our libraries actually capture much more information. See the full payload below.

The full payload

While your requests are typically short, our libraries capture much more information. This helps us provide context, not only for the group and the person you associate with the group, but the service you send the call from.

Customer.io and our libraries typically populate integrations and timestamp values as shown in the payload below. If you use our JavaScript or mobile libraries, they’ll also populate context for you. If you use our server-side libraries, you’ll need to populate context yourself.

See common fields for more information about context, integrations, and timestamps in source payloads.

{
  "userId": "97980cfea0067",
  "groupId": "0e8c78ea9d97a7b8185e8632,",
  "traits": {
    "name": "Acme",
    "industry": "Technology",
    "wile_e_coyote_accidents": 329,
    "plan": "enterprise,",
    "total_billed": 830
  },
  "integrations": {
    "All": true
  },
  "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db,",
  "timestamp": "2015-02-23T22:28:55.111Z,",
  "context": {
    "active": true,
    "ip": "8.8.8.8",
    "locale": "string",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.115 Safari/537.36",
    "channel": "browser",
    "campaign": {
      "name": "string",
      "source": "string",
      "medium": "string",
      "term": "string",
      "content": "string"
    },
    "page": {
      "name": "string",
      "path": "string",
      "referrer": "string",
      "search": "string",
      "title": "string",
      "url": "string",
      "keywords": [
        "string"
      ]
    }
  },
  "anonymousId": "507f191e810c19729de860ea,",
  "channel": "browser,",
  "receivedAt": "2015-02-23T22:28:55.387Z,",
  "sentAt": "2015-02-23T22:28:55.111Z,",
  "type": "group",
  "version": 1.1
}

Group ID

A Group ID is a unique identifier, like a UUID or ULID, that represents the group in your database or backend.

Traits

Like people in Customer.io, groups can have traits. Group traits are things you know about a group that you pass along in any group call, like industry, employees, or website.

We’ve reserved the following traits. We handle these traits in special ways across destinations. You should only use reserved traits for their intended meanings.

Some destinations might represent these traits with slightly different names. For example, Mixpanel recognizes a $created trait when a user is first created, while Intercom recognizes the same trait as created_at. We attempt to handle all the destination-specific conversions for you automatically.

Traits are case-insensitive, so in JavaScript you can match the rest of your camel-case code by sending createdAt, and in Ruby you can match your snake-case code by sending created_at. That way the API never seems alien to your code base.

You can pass reserved traits using camelCase or snake_case. For example, in JavaScript you can match the rest of your camel-case code by sending createdAt, while in Python you can match your snake-case code by sending created_at. That way the API never seems alien to your code base.

Groups are called objects in Customer.io

In Customer.io Journeys, we refer to groups as objectsNot to be confused with a JSON object, an object in Customer.io is a non-person entity that you can associate with one or more people—like a company, account, or online course. You can use objects to message people based on changes to their company, account, or course itinerary.. The principle is the same: objects are non-people entities that people are related to, like accounts, companies, and online classes. But there are a few differences:

1. You can have different kinds of objects! In Customer.io, we differentiate between objects using the traits.objectTypeId key.
2. You can set traits for the object itself, and for the relationship between the person and the object. Items under traits are for the object, while items under traits.relationshipAttributes are for the relationship between the person and the object.

Object type

You can have different kinds of objects in Customer.io. For example, you might have objects for online classes, schools, client companies, and so on. When you create a new object type, we’ll assign it an objectTypeId. This ID is a number that represents the kind of object you’re creating.

Your first object is objectTypeId 1, your second object is objectTypeId 2, and so on. In calls representing objects, you’ll send the object type to tell us what kind of object you want to create, update, or delete.

• For group calls, object type is represented by traits.objectTypeId.
• For track calls, object type is represented by properties.objectTypeId.

If you don’t provide traits.objectTypeId in a group call, we’ll assume that the object type is 1.

Object and relationship attributes

When you send a group call, you can set traits for the object itself, and for the relationship between the person and the object. Items in the traits object are for the object, while items in the traits.relationshipAttributes object are for the relationship between the person and the object.

For example, if you have a group representing a company, you might set the company’s name, industry, and employees in the traits object. You might also set the person’s role in the company, the dateJoined, and the isPrimaryContact in the traits.relationshipAttributes object.

{
  "userId": "wileecoyote",
  "groupId": "0e8c78ea",
  "traits": {
    "objectTypeId": 2,
    // these traits apply to the object
    "name": "Acme",
    "industry": "Technology",
    "employees": 329,
    // everything under relationshipAttributes applies to the 
    // relationship between the person and the object
    "relationshipAttributes": {
      "role": "sponsor",
      "dateJoined": "2021-01-01",
      "isPrimaryContact": true
    }
  }
}

Deleting objects and relationships

You’ll use group calls to create and update objects and relationships. But what if you want to delete an object or a relationship?

We use special events to delete objects and relationships in Customer.io. These events are called semantic events. They let you send track calls with a specific event name to perform actions in Journeys. For objects, that means you’ll send Delete Object and Delete Relationship to remove objects and relationships from Customer.io respectively.

Track calls are formatted differently from group calls. In this case, you’ll provide the userId at the top of the call, and your objectId (the groupId from your group calls!) in the properties object.

{
  "userId": "wileecoyote",
  "event": "Delete Object",
  "properties": {
    "objectId": "0e8c78ea",
    "objectTypeId": 2
  }
}