Group Call

Overview

The Group Call allows you to link a user (user_id) to a specific account (group_id) and optionally define account-level traits. These traits provide descriptive information about the account, such as its name, subscription status, or plan type.

Group Calls are essential for tracking account health, segmentation, and team-level engagement, giving you a comprehensive view of your user base at both the individual and organizational levels.

Required Fields

Here are the fields required in every Group Call:

group_id: (String) A unique identifier for the account or group. This is mandatory to link users to specific accounts.
- Tip: Use the same ID as you use in tools like HubSpot or Intercom to enable seamless integration and consistent tracking across platforms.
user_id: (String) A unique identifier for the user being associated with the group.
timestamp: (String) The ISO 8601 or Unix timestamp of when the Group Call was made.
- Examples:
  - ISO 8601: "2025-01-28T06:28:22.385Z"
  - Unix: 1735689600000 (12:00 AM on January 1, 2025, GMT)

Highly Recommended Fields

While not required, the following fields are highly recommended to provide better context for the account:

name: (String) The name of the account (e.g., "Acme Corp"). Without this, accounts will display as numeric IDs, making them harder to identify.
created_at: (String) The date the account was created, in ISO 8601 format (e.g., "2023-01-15T12:00:00Z"). This helps calculate account tenure.

Optional but Recommended Fields

These fields are optional but recommended to enhance account-level insights:

status: (String) The subscription status of the account (e.g., "trial", "paid", "canceled").
plan: (String) The account’s subscription plan (e.g., "starter", "pro", "enterprise").
mrr: (Integer) The monthly recurring revenue for the account, expressed in cents (e.g., 100000 for $1,000).

Including these fields can help segment accounts, monitor financial performance, and analyze trends across different subscription types or statuses.

Example Group Call

Here’s a typical Group Call with account traits:

{
  "group_id": "account_67890",
  "user_id": "user_12345",
  "traits": {
    "name": "Acme Corp",
    "status": "paid",
    "plan": "enterprise",
    "mrr": 100000,
    "created_at": "2023-01-15"
  },
  "timestamp": "2025-01-28T12:00:00Z"
}

When to Use Group Calls

You should make a Group Call:

When a new account is created: Link the user who created the account and define initial account traits.
On significant account updates:
- When the account’s subscription status changes (e.g., trial → paid).
- When the account upgrades or downgrades its plan.
- When account details like name or MRR are updated.
To track user-account relationships: Use Group Calls whenever a user is associated with or removed from an account.

Recommended Group traits

Group (or Account) traits are descriptive pieces of information about an Account that can be sent with a .group call. While the traits you send are up to you, there are some standard traits that we recommend using for each account.

TRAIT	RECOMMENDATION	SAMPLE VALUES	DESCRIPTION
`GroupID`	Required		`.group` calls require a `GroupID` as the first argument
`name`	Highly recommended		This is a trait you would use to name an account. Without providing a name of your accounts, Accoil will display your account by numeric ID - rendering them relatively useless.
`created_at`	Highly recommended	Date (ISO8601 or unix timestamp)	This trait is necessary to calculate the tenure of your accounts. *If you don't provide a `created_at` trait for an account, we will use the earliest `created_at` date for the users on that account to calculate the account tenure.
`status`	Highly recommended	{ trial , trial-expired , paid , canceled }	This describes the paid status of an account. This may be unique for your business, the basics are trial, trial expired , paid , canceled.
`plan`	Recommended	{starter , pro , enterprise , etc )	Providing the plan type for your paid accounts will help you understand engagement of your different account types.
`MRR`	Recommended	{numeric value}	Providing MRR values for your accounts will allow you to segment accounts by value, but also will allow Accoil to show you the dollar value of your different segments.

*Traits must be an object containing keys that are strings, and values that are either a number, string, boolean or nested traits object

Best Practices for Group Calls

Always Include group_id
A unique group_id is mandatory. Without it, Accoil cannot associate users with their respective accounts.
Use Descriptive Account Traits (Optional)
While traits are not required, they add valuable context for account segmentation and analysis. For example:
- Use status to track trial vs. paid accounts.
- Use mrr to understand the value of each account.
Update Traits as Needed
Make additional Group Calls whenever important account information changes, such as:
- Subscription upgrades or downgrades.
- Changes in MRR or billing status.