Criar grupo

POST/v1/instances/{id}/groupsdesde M8token da instância ou admin

Quando usar

Cria um grupo com até 10 participantes iniciais (número com DDI ou JID). Só entram pessoas que já têm conversa no log da instância ou que a consulta de números confirma no WhatsApp (gasta a cota de check-numbers); as demais voltam em results com not_on_whatsapp ou unknown_contact, sem chegar ao WhatsApp. Conta na cota settings.groups.max_creates_per_day (padrão 3) e os participantes nas cotas de adição (e no intervalo de 10s entre lotes); acima, 429 rate_limited. A cota só volta se a requisição não chegou ao WhatsApp. Com envios suspensos pelo operador, 403 sending_suspended. Com parent, o grupo nasce dentro da comunidade.

Confiabilidade e risco

Criar grupos com desconhecidos é gatilho de banimento: cota diária e participantes só conhecidos.

Autenticação

Aceita o token da instância (só a própria instância) ou o token admin. Um token de outra instância recebe 403 forbidden (ou 404 not_found em webhooks de outra instância).

Parâmetros

Caminho

Nome	Tipo	Descrição
idobrigatório	string	Id da instância (inst_...).

Corpo (JSON)

Nome	Tipo	Descrição
nameobrigatório	string	(até 100)
participants	string[]	Número com DDI ou JID. (até 10 itens)
description	string	(até 2048)
parent	string	Criar dentro desta comunidade (só em POST /groups).
settings	object
settings.announce	boolean
settings.locked	boolean
settings.approval_required	boolean
settings.admins_add_members	boolean
settings.ephemeral_seconds	0 | 86400 | 604800 | 7776000

Exemplo

cURL

curl -s -X POST "$LITEZAP_URL/v1/instances/$ID/groups" \
  -H "Authorization: Bearer $LITEZAP_TOKEN" \
  -d '{"name":"Equipe","participants":["5511999999999"],"description":"Avisos da equipe","settings":{"announce":false}}'

Node.js

const res = await fetch("http://localhost:8787/v1/instances/inst_7f3a9c2e5b1d4086/groups", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.LITEZAP_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "name": "Equipe",
    "participants": [
      "5511999999999"
    ],
    "description": "Avisos da equipe",
    "settings": {
      "announce": false
    }
  }),
});
console.log(res.status, res.status === 204 ? "" : await res.json());

Python

import os
import requests

r = requests.post(
    "http://localhost:8787/v1/instances/inst_7f3a9c2e5b1d4086/groups",
    headers={"Authorization": f"Bearer {os.environ['LITEZAP_TOKEN']}"},
    json={
        "name": "Equipe",
        "participants": ["5511999999999"],
        "description": "Avisos da equipe",
        "settings": {
            "announce": False,
        },
    },
    timeout=150,
)
print(r.status_code, r.json() if r.content else "")

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
  "strings"
)

func main() {
  req, _ := http.NewRequest("POST", "http://localhost:8787/v1/instances/inst_7f3a9c2e5b1d4086/groups", strings.NewReader(`{"name":"Equipe","participants":["5511999999999"],"description":"Avisos da equipe","settings":{"announce":false}}`))
  req.Header.Set("Authorization", "Bearer "+os.Getenv("LITEZAP_TOKEN"))
  req.Header.Set("Content-Type", "application/json")
  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  out, _ := io.ReadAll(resp.Body)
  fmt.Println(resp.Status, string(out))
}

PHP

<?php
require 'vendor/autoload.php'; // composer require guzzlehttp/guzzle

$client = new GuzzleHttp\Client(['base_uri' => 'http://localhost:8787']);
$res = $client->request('POST', '/v1/instances/inst_7f3a9c2e5b1d4086/groups', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('LITEZAP_TOKEN')],
    'json' => [
        'name' => 'Equipe',
        'participants' => ['5511999999999'],
        'description' => 'Avisos da equipe',
        'settings' => [
            'announce' => false,
        ],
    ],
    'http_errors' => false,
]);
echo $res->getStatusCode(), ' ', $res->getBody(), PHP_EOL;

Nos exemplos, LITEZAP_URL é a URL base (ex.: http://localhost:8787) e o token vem deLITEZAP_TOKEN (instância) ou LITEZAP_ADMIN_TOKEN.

Resposta

201 Grupo criado e resultado por participante.

Campos de CreateGroupResult

group	Group
group.jid	string
group.name	string
group.description	string
group.owner	string
group.created_at	string
group.community	boolean	É uma comunidade.
group.parent	string	Comunidade a que o grupo pertence.
group.announcement_group	boolean	Grupo de avisos da comunidade.
group.participant_count	integer
group.lid_addressing	boolean	O grupo endereça os membros por LID.
group.suspended	boolean
group.settings	GroupSettings	Configurações de um grupo (marco 8).
group.participants	GroupParticipant[]	Só em GET /groups/{jid} e na criação.
results	ParticipantResult[]
warning	string	Um passo depois da criação falhou (descrição); o grupo existe.

Erros

Código	HTTP	Retentável	O que fazer
validation_failed	400	não	Corrija o corpo ou os parâmetros; a message diz o campo.
unauthorized	401	não	Envie Authorization: Bearer <token> válido.
forbidden	403	não	Use o token certo (admin, ou o da própria instância).
instance_not_found	404	não	Confira o id da instância.
instance_not_connected	409	depende	Confira o estado da instância; se logged_out, pareie de novo.
instance_banned	409	não	Número banido: apague a instância.
rate_limited	429	sim	Espere e tente de novo com backoff.
worker_error	502	sim	Tente de novo com backoff; se persistir, veja o log do servidor.
worker_timeout	504	sim	Tente de novo; a instância pode estar sobrecarregada ou reconectando.

Todo erro usa o envelope {"error":{"code","message","retryable"}}. Tabela completa em Erros.

Eventos gerados

• group.updated

Equivalente na Z-API: Criar grupo. Veja Migrar da Z-API.

Outras operações de Grupos: Listar grupos · Metadados do grupo · Alterar grupo · Trocar foto do grupo · Remover foto do grupo · Gerenciar participantes · Listar pedidos de entrada · Aprovar ou rejeitar pedidos · Link de convite · Redefinir link de convite · Sair do grupo · Ver grupo pelo convite · Entrar por convite