Groups and group membership

What groups are for

• Organization scope — set organizationId on the group so it belongs to one org.
• Membership — attach users (authenticated BoomTower users) and/or members (org members who receive messaging via consent).
• Nudge activation — list nudges on the group with status: "active". Scheduled delivery only runs for nudges that are active on the group.
• Group chat — each group gets a chat (created automatically if omitted). Inbound SMS replies can be correlated to the group when the latest send included a group id. Fetch standardized reply history with GET /v1/nudges/{key}/replies (Nudge replies).

Users vs members

Both lists use the same shape: { "id": "…", "status": "active" | "inactive" }. Only active entries receive scheduled or fan-out sends.

Sharing personalized results (sendToGroup)

Some nudges generate unique content per recipient (for example AI text, images, or audio with aiGeneratePerUser). By default each person only receives their own result. When sendToGroup is true on the nudge, BoomTower also delivers that person's generated result to every other active member on shared org groups where:

• the group's organizationId matches the member's org,
• the subject is an active group member,
• the nudge is active on the group, and
• each recipient has messaging consent and at least one enabled channel.

Each teammate still gets their own scheduled primary send; fan-out copies are separate outbox rows keyed by recipient + subject so the same personalized asset is reused, not regenerated.

Scheduling flow

1. POST /v1/consider (system) evaluates org-member nudges and enqueues one primary send per due member per channel.
2. If sendToGroup is enabled, consider enqueues additional sends for other active group members (with subjectUserId pointing at the person whose content was generated).
3. POST /v1/send drains the outbox and delivers via each recipient's enabled channels (SMS or email).

Inviting org members to a group

Use member invites when people sign up in your app (not BoomTower login). Your server creates the invite, sends the invitee to your onboarding URL, creates their org member record, then redeems the invite to add them to group.members.

1. POST /v1/invites with recipientType: "member", the target groupId, and at least one of phone, email, or externalApp + externalId. Optional returnUrl sets where inviteUrl sends the user (with inviteId appended).
2. Send the invitee to inviteUrl (email/SMS from your app).
3. After signup, create or upsert the org member (embed consent or POST …/members/consent) using the same phone/email/external identity as the invite.
4. POST /v1/invites/{inviteId}/redeem-member with memberId or externalApp + externalId. BoomTower adds the member to the group and organization.

POST https://api.boomtower.com/v1/invites
X-API-Key: YOUR_ORG_API_KEY
Content-Type: application/json

{
  "data": {
    "groupId": "GROUP_KSUID_OR_BOOM_ID",
    "recipientType": "member",
    "email": "teammate@example.com",
    "externalApp": "your-app",
    "externalId": "USER_123",
    "returnUrl": "https://your-app.com/join"
  }
}

POST https://api.boomtower.com/v1/invites/{inviteId}/redeem-member
X-API-Key: YOUR_ORG_API_KEY
Content-Type: application/json

{
  "data": {
    "externalApp": "your-app",
    "externalId": "USER_123"
  }
}

User invites (default recipientType: "user") still require phone and redeem via authenticated POST /v1/invites/{id}/redeem into group.users.

Setup (org members)

Typical server-side flow using an organization API key (X-API-Key):

1. Ensure members exist and have consent (embed consent or POST …/members/consent).
2. Activate the nudge in the organization catalog (PATCH /v1/organizations/{id}).
3. Create or update a group with organizationId, members, and the nudge in nudges.
4. Configure the nudge with sendToGroup: true (and personalization flags as needed).

POST https://api.boomtower.com/v1/groups
X-API-Key: YOUR_ORG_API_KEY
Content-Type: application/json

{
  "data": {
    "name": "Accountability team",
    "organizationId": "ORG_KSUID",
    "members": [
      { "id": "[tenant:member]-MEMBER_A_KSUID", "status": "active" },
      { "id": "[tenant:member]-MEMBER_B_KSUID", "status": "active" }
    ],
    "nudges": [
      { "id": "[tenant:nudge]-NUDGE_KSUID", "status": "active" }
    ]
  }
}

PATCH https://api.boomtower.com/v1/nudges/{nudgeKsuid}
X-API-Key: YOUR_ORG_API_KEY
Content-Type: application/json

{
  "data": {
    "aiGeneratePerUser": true,
    "sendToGroup": true,
    "aiIncludeChatHistory": true,
    "aiChatHistoryLookbackDays": 7
  }
}

API reference

Full request/response schemas live in the REST API. Relevant resources:

• Invites — POST /v1/invites with recipientType: "member"; POST …/redeem-member after member creation
• Groups — GET/POST/PATCH /v1/groups; members on APIGroup
• Nudges — sendToGroup, responseType on APINudge; GET …/replies for reply history and stats
• Member nudge settings — GET …/members/…/nudge-settings includes sendToGroup per catalog nudge