How do you create a group programmatically within a community using the Create Group API?

Who is this for and why it matters

Use this API when you want to create interactive groups inside a community programmatically, instead of manually configuring them in the Brand Control Center.

This matters because:

It enables real-time group creation based on user actions or workflows
It helps you organize content into topic-driven collaborative spaces
It powers engagement loops through video-led discussions and interactions

If you're building dynamic experiences - like discussion threads, campaigns, or creator-led spaces, this API is critical.

What does the Create Group API do?

The Create Group API allows you to:

Create a group within an existing community
Attach a video (recorded or AI-generated) as the starting point
Define group structure, topics, and members
Configure access controls and discoverability

It essentially creates a content-first collaborative environment inside your Community Media Network.

API Details

URL: /api/thirdparty/group/create
Method: POST
Authentication Required: Yes (Bearer Token)
Mandatory Fields: type, community_id

Before you begin

1. Authenticate your request

Generate a gn-access-token using the Authentication API.

Pass it in the header: Authorization - Bearer <gn-access-token>

2. Ensure community exists

You must have a valid community_id where the group will be created.

Request Structure

Request Body

{
  "type": 4,
  "chat_id": "456e7890-b12c-4c23-89ef-126314214567",
  "recorded_video": {
    "message_id": "789e1234-f12d-4c67-a256-126314214555",
    "video_name": "abcd1234-5678-90ef-1112-234567890111_video.mp4",
    "thumbnail_name": "abcd1234-5678-90ef-1112-234567890111_thumb.jpg",
    "video_path": "trends_videos/2024/5/6/creative",
    "thumbnail_path": "trends_thumbnail/2024/5/6/creative",
    "is_ai_generated_video": true,
    "is_ai_generated_thumbnail": true,
    "link": "",
    "size": "5MB",
    "duration": 5,
    "aspect_ratio": "720x1280",
    "resolution": "1080p",
    "description_text": "Hello, this is @user and I love community XYZ",
    "description_data": "[\"Hello\",{\"user_id\":\"345e1234-5678-90ef-2345-678912341234\"},\"and I love community\",{\"community_id\":\"def45678-abcd-ef12-3456-1234abcdef56\"}]",
    "meta_data": {
      "topic": "Open Discussion"
    }
  },
  "community_id": "f2a05adb-93ce-4a19-b003-3523fa745667",
  "actions": [
    { "action_id": 3, "access_type_id": 5 },
    { "action_id": 5, "access_type_id": 9 }
  ],
  "group": {
    "name": "Tech Conversations",
    "description": "A platform for discussing the latest in technology and innovation.",
    "tags": "technology",
    "dp": "group_dp.png",
    "topics": [1, 2],
    "members": [
      { "phone_number": "919876543210" },
      { "user_id": "abcd1234-5678-90ef-1112-234567890111" }
    ]
  },
  "settings": {
    "discoverable": false
  },
  "template_id": 2,
  "is_ai_generated": false
}

Field-level understanding

Core Fields

type - Defines the group type (e.g., video-led discussion)
community_id - Community where the group will be created
chat_id - Unique identifier for the group session

Recorded Video (Content Layer)

Defines the starting content of the group
Includes:
- Video + thumbnail metadata
- AI-generated flags
- Description with user/community mentions
- Topic metadata

This is what drives engagement inside the group.

Actions (Access Control)

Controls what users can do inside the group
Example:
- Who can post
- Who can interact
- Access permissions

Group Object

name / description / tags - Identity and discovery
dp - Group display image
topics - Categorization
members - Initial participants (via phone or user_id)

Settings

discoverable - Whether the group is visible publicly

Other Controls

template_id - Predefined group configuration
is_ai_generated - Whether group is AI-created

What happens on success?

Success Condition

If all inputs are valid:

Group is created inside the specified community
Video is attached as the starting interaction
Members are added

Response Code

200 OK

Response Highlights

{
  "chat_id": "456e7890-b12c-4c23-89ef-126314214567",
  "share_url": "https://app.qa.begenuin.com/group/...",
  "group": {
    "group_id": "f67c89d0-9abc-4abc-bdef-56789abcf456",
    "group_name": "Tech Conversations"
  },
  "community": {
    "community_id": "f2a05adb-93ce-4a19-b003-3523fa745667",
    "name": "Tech World"
  }
}

Important

chat_id - Unique identifier for the group
share_url - Public URL to access the group

Error Handling

1. Bad Request

Condition:

Invalid payload
Missing or incorrect fields

Response Code: 400 Bad Request

Response Body: {}

2. Internal Server Error

Condition:

Video not found
Server-side failure

Response Code: 500 Internal Server Error

Response Body:

{
  "code": "5026",
  "message": "Could not find the video.",
  "data": {}
}

Best Practices

Ensure the community_id is valid before creating a group
Always attach high-quality video content to drive engagement
Validate media paths and metadata before sending the request
Use AI-generated content flags for faster setup where applicable
Carefully configure actions and access controls
Handle errors and retries in production systems

What to do next

Once the group is created:

Share the share_url with users
Drive engagement through video discussions
Add more members or content dynamically
Layer monetization or campaigns on top of active groups