Create Group Conversation

Create a new group conversation within a space. Group conversations allow organizing messages into separate threads or topics within a single space.

Endpoint

POST /v1/workspaces/{workspaceId}/spaces/{spaceId}/group

Authentication

This endpoint requires a Bearer token obtained through the two-step authentication flow:

  1. First, generate an access token using your API key
  2. Use that access token in the Authorization header

See Authentication for the complete authentication flow.

Path Parameters

ParameterTypeRequiredDescription
workspaceIdstring (UUID)YesThe ID of your workspace
spaceIdstring (UUID)YesThe ID of the space

Headers

HeaderTypeRequiredDescription
AuthorizationstringYesBearer token with access token
organizationidstring (UUID)YesYour organization ID
Content-TypestringYesMust be application/json

Request Body

FieldTypeRequiredDescription
namestringNoName for the group conversation. Defaults to "General" if not provided

Response

Success Response

Status Code: 200 OK

Body:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Technical Support",
  "createdAt": "2025-01-15T10:30:00Z"
}

Response Fields

FieldTypeDescription
idstring (UUID)Unique identifier for the group conversation
namestringName of the group conversation
createdAtstring (ISO 8601)Creation timestamp

Examples

Basic Request

# Step 1: Generate access token (do this once, reuse for multiple requests)
ACCESS_TOKEN=$(curl -s -X POST \
  'https://api.sharely.ai/workspaces/your-workspace-id/generate-access-key-token' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: sk-sharely-your-api-key' \
  -d '{}' | jq -r '.token')
 
# Step 2: Create group conversation
curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/spaces/your-space-id/group' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'organizationid: your-organization-id' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Technical Support"
  }'

JavaScript Example

const API_KEY = 'sk-sharely-your-api-key';
const WORKSPACE_ID = 'your-workspace-id';
const ORGANIZATION_ID = 'your-organization-id';
const API_BASE_URL = 'https://api.sharely.ai';
 
// Step 1: Generate access token
async function getAccessToken() {
  const response = await fetch(
    `${API_BASE_URL}/workspaces/${WORKSPACE_ID}/generate-access-key-token`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': API_KEY
      },
      body: JSON.stringify({})
    }
  );
  const data = await response.json();
  return data.token;
}
 
// Step 2: Create group conversation
async function createGroupConversation(accessToken, spaceId, name) {
  const response = await fetch(
    `${API_BASE_URL}/v1/workspaces/${WORKSPACE_ID}/spaces/${spaceId}/group`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'organizationid': ORGANIZATION_ID,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ name })
    }
  );
 
  if (!response.ok) {
    throw new Error(`Failed to create group: ${response.statusText}`);
  }
 
  return await response.json();
}
 
// Usage
const accessToken = await getAccessToken();
const group = await createGroupConversation(
  accessToken,
  'space-id',
  'Product Questions'
);
 
console.log('Group created:', group.id);
console.log('Name:', group.name);

Create Multiple Topic Groups

async function setupSpaceGroups(accessToken, spaceId) {
  const topics = [
    'General Discussion',
    'Technical Support',
    'Feature Requests',
    'Billing Questions'
  ];
 
  const groups = [];
 
  for (const topic of topics) {
    const group = await createGroupConversation(accessToken, spaceId, topic);
    groups.push(group);
    console.log(`Created group: ${group.name} (${group.id})`);
  }
 
  return groups;
}

Use Cases

Organize Conversations by Topic

Create separate groups for different types of discussions within a customer space:

// Customer onboarding space with organized topics
const accessToken = await getAccessToken();
const spaceId = 'customer-space-id';
 
await createGroupConversation(accessToken, spaceId, 'Getting Started');
await createGroupConversation(accessToken, spaceId, 'Integration Help');
await createGroupConversation(accessToken, spaceId, 'API Questions');

Session-Based Conversations

Create a new group for each support session:

async function startSupportSession(accessToken, spaceId, sessionType) {
  const timestamp = new Date().toISOString().split('T')[0];
  const sessionName = `${sessionType} - ${timestamp}`;
 
  const group = await createGroupConversation(accessToken, spaceId, sessionName);
 
  return {
    groupId: group.id,
    sessionName: group.name,
    startedAt: group.createdAt
  };
}

Error Responses

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing access token"
}

404 Not Found

Space not found:

{
  "error": "Error",
  "message": "Space not found"
}

Related Endpoints