createGroup

Создаёт группу от имени канала: номер канала становится её владельцем. В ответе — chatId группы и ссылка-приглашение для тех, кого не удалось добавить сразу.

Параметры

Пример запроса

Группа для Марии и Олега в MAX:

curl

curl -X POST "$GRATIO_URL/waInstance$GRATIO_ID/createGroup/$GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "groupName": "3А · Робототехника",
    "chatIds": [
      "8695836",
      "1111111"
    ]
  }'

Python

import os
import requests

BASE = f"{os.environ['GRATIO_URL']}/waInstance{os.environ['GRATIO_ID']}"
TOKEN = os.environ["GRATIO_TOKEN"]

url = f"{BASE}/createGroup/{TOKEN}"
payload = {"groupName": "3А · Робототехника", "chatIds": ["8695836", "1111111"]}
response = requests.post(url, json=payload, timeout=60)
print(response.status_code, response.json())

Node.js

const { GRATIO_URL, GRATIO_ID, GRATIO_TOKEN } = process.env;
const base = `${GRATIO_URL}/waInstance${GRATIO_ID}`;

const url = `${base}/createGroup/${GRATIO_TOKEN}`;
const payload = { groupName: "3А · Робототехника", chatIds: ["8695836", "1111111"] };
const response = await fetch(url, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});
console.log(response.status, await response.json());

PHP

<?php
$base = getenv('GRATIO_URL') . '/waInstance' . getenv('GRATIO_ID');
$url = $base . '/createGroup/' . getenv('GRATIO_TOKEN');
$payload = [
    'groupName' => '3А · Робототехника',
    'chatIds' => ['8695836', '1111111'],
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
]);
$response = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($response);

Пример ответа

Ответ 200 OK:

{"created": true, "chatId": "-80040066617372", "groupInviteLink": "https://max.ru/join/JvIa7E1T…"}

Поля ответа

Ещё примеры

WhatsApp

В WhatsApp — один участник, и только тот, кому номер канала уже писал:

curl -X POST "$GRATIO_URL/waInstance$GRATIO_ID/createGroup/$GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "groupName": "3А · Робототехника",
    "chatIds": [
      "79991234567@c.us"
    ]
  }'

Ответ 200 OK:

{"created": true, "chatId": "120363012345678901@g.us", "groupInviteLink": "https://chat.whatsapp.com/…"}

Остальных добавляйте по одному через addGroupParticipant, не чаще раза в минуту.

Если площадка отказала

В отличие от остальных групповых методов, createGroup на отказ отвечает ошибкой, а не 200 с флагом false. Вторая группа раньше чем через 5 минут:

{"message": "Группы создаём не чаще раза в 5 минут", "code": "too_frequent", "retryAfter": 214}

Код ответа — 429, в заголовке Retry-After — те же секунды. Мессенджер при этом не спрашивают.

Ошибки

Общие правила — в статье Ответы и ошибки.

Особенности каналов

• Темп. Новая группа — не чаще раза в 5 минут на канал: частое создание групп мессенджеры считают поведением бота.
• Telegram. Gratio создаёт супергруппу с chatId вида -100…: обычную группу Telegram при росте переводит в супергруппу с новым id, и адрес в вашей системе сломался бы. Если настройки приватности не дали добавить кого-то из участников, группа всё равно создаётся — проверьте состав через getGroupData и отправьте остальным groupInviteLink.
• WhatsApp. Группы — частая причина блокировки номера, поэтому правила строже: один участник при создании, дальше — по одному в минуту и только те, кому номер уже писал. См. WhatsApp.
• События. Изменения группы, в том числе сделанные через API, приходят уведомлением groupEvent.

Что дальше

• addGroupParticipant — добавить участников.
• updateGroupSettings — права участников.
• groupEvent — уведомления об изменениях группы.
• Группа для клиентов — группа целиком: от создания до рассылки.