Criar Grupo

POST

api

group

create

:instance

Criar Grupo

curl --request POST \
  --url https://api.example.com/api/group/create/:instance \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "name": "<string>",
  "participants": [
    "<string>"
  ],
  "description": "<string>",
  "image": "<string>",
  "communityJid": "<string>",
  "groupSettings": {}
}
'

const options = {
  method: 'POST',
  headers: {token: '<token>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    name: '<string>',
    participants: ['<string>'],
    description: '<string>',
    image: '<string>',
    communityJid: '<string>',
    groupSettings: {}
  })
};

fetch('https://api.example.com/api/group/create/:instance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/api/group/create/:instance"

payload = {
    "name": "<string>",
    "participants": ["<string>"],
    "description": "<string>",
    "image": "<string>",
    "communityJid": "<string>",
    "groupSettings": {}
}
headers = {
    "token": "<token>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Auth: TokenAccount ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: não

Descrição

Cria um grupo de WhatsApp e o vincula opcionalmente a uma comunidade existente (communityJid). Você pode definir nome, descrição, foto e permissões iniciais (groupSettings) na mesma chamada. A foto e a descrição são aplicadas em chamadas subsequentes após a criação do grupo.

Exemplos

Mínimo

Cria um grupo “Time de Dev” com 2 participantes iniciais (5511999999999, 5521988888888), sem descrição, foto, comunidade nem permissões customizadas.

curl -X POST "https://ryzeapi.cloud/api/group/create/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Time de Dev",
    "participants": ["5511999999999", "5521988888888"]
  }'

await fetch(`https://ryzeapi.cloud/api/group/create/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name:         "Time de Dev",
    participants: ["5511999999999", "5521988888888"]
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/group/create/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "name":         "Time de Dev",
        "participants": ["5511999999999", "5521988888888"]
    }
)

package main

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

func main() {
    body := strings.NewReader(`{
        "name": "Time de Dev",
        "participants": ["5511999999999", "5521988888888"]
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/group/create/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Com descrição e foto

Cria o grupo já com a descrição “Discussões técnicas” e foto vinda de uma URL pública. Descrição e imagem são aplicadas em chamadas subsequentes após a criação do grupo.

curl -X POST "https://ryzeapi.cloud/api/group/create/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Time de Dev",
    "description": "Discussões técnicas",
    "image": "https://exemplo.com/logo.png",
    "participants": ["5511999999999", "5521988888888"]
  }'

await fetch(`https://ryzeapi.cloud/api/group/create/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name:         "Time de Dev",
    description:  "Discussões técnicas",
    image:        "https://exemplo.com/logo.png",
    participants: ["5511999999999", "5521988888888"]
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/group/create/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "name":         "Time de Dev",
        "description":  "Discussões técnicas",
        "image":        "https://exemplo.com/logo.png",
        "participants": ["5511999999999", "5521988888888"]
    }
)

package main

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

func main() {
    body := strings.NewReader(`{
        "name": "Time de Dev",
        "description": "Discussões técnicas",
        "image": "https://exemplo.com/logo.png",
        "participants": ["5511999999999", "5521988888888"]
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/group/create/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Com permissões

Cria um grupo “Anúncios” com restrições iniciais: somente admins podem enviar mensagens (membersCanSendMessages: false) e novas entradas precisam de aprovação (requireAdminApproval: true).

curl -X POST "https://ryzeapi.cloud/api/group/create/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Anúncios",
    "participants": ["5511999999999"],
    "groupSettings": {
      "membersCanSendMessages": false,
      "requireAdminApproval": true
    }
  }'

await fetch(`https://ryzeapi.cloud/api/group/create/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name:         "Anúncios",
    participants: ["5511999999999"],
    groupSettings: {
      membersCanSendMessages: false,
      requireAdminApproval:   true
    }
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/group/create/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "name":         "Anúncios",
        "participants": ["5511999999999"],
        "groupSettings": {
            "membersCanSendMessages": False,
            "requireAdminApproval":   True
        }
    }
)

package main

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

func main() {
    body := strings.NewReader(`{
        "name": "Anúncios",
        "participants": ["5511999999999"],
        "groupSettings": {
            "membersCanSendMessages": false,
            "requireAdminApproval": true
        }
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/group/create/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Vinculado a comunidade

Cria o grupo “Subgrupo Geral” já vinculado à comunidade 120363406289005073@g.us via communityJid, evitando o passo extra de chamar /community/link após a criação.

curl -X POST "https://ryzeapi.cloud/api/group/create/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Subgrupo Geral",
    "participants": ["5511999999999"],
    "communityJid": "120363406289005073@g.us"
  }'

await fetch(`https://ryzeapi.cloud/api/group/create/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name:         "Subgrupo Geral",
    participants: ["5511999999999"],
    communityJid: "120363406289005073@g.us"
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/group/create/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "name":         "Subgrupo Geral",
        "participants": ["5511999999999"],
        "communityJid": "120363406289005073@g.us"
    }
)

package main

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

func main() {
    body := strings.NewReader(`{
        "name": "Subgrupo Geral",
        "participants": ["5511999999999"],
        "communityJid": "120363406289005073@g.us"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/group/create/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Resposta de sucesso

A resposta inclui o group.jid recém-criado (use-o como identifier nas chamadas subsequentes), o inviteCode e inviteLink prontos para compartilhar e a lista de participants já marcada com isAdmin/isSuperAdmin. O criador entra automaticamente como super-admin. Os campos groupSettings refletem as permissões iniciais (defaults ou o que foi enviado).

200 OK

{
  "success": true,
  "message": "Group created successfully",
  "group": {
    "name": "Time de Dev",
    "jid": "120363406289005073@g.us",
    "description": "Discussões técnicas",
    "inviteCode": "ABC123XYZ",
    "inviteLink": "https://chat.whatsapp.com/ABC123XYZ",
    "createdBy": "5511999999999@s.whatsapp.net",
    "participantCount": 3,
    "participants": [
      { "jid": "5511999999999@s.whatsapp.net", "isAdmin": true, "isSuperAdmin": false }
    ],
    "groupSettings": {
      "membersCanEditInfo": true,
      "membersCanSendMessages": true,
      "membersCanAddOthers": false,
      "requireAdminApproval": false
    },
    "isCommunity": false,
    "isParent": false,
    "linkedParentJid": null
  }
}

Parâmetros de rota

string

obrigatório

Nome da instância (ex.: $Instance_Name).

Headers

string

obrigatório

TokenAccount ou TokenInstance.

string

obrigatório

application/json

Request body

string

obrigatório

Nome do grupo. Máximo de 25 caracteres.

string[]

obrigatório

Lista de números (5511999999999) ou JIDs (5511999999999@s.whatsapp.net). Pelo menos 1 item.

string

Descrição (tópico) do grupo. Aplicada via SetGroupTopic após a criação.

string

URL pública ou data URI base64. A imagem é convertida para JPEG.

string

Cria o grupo já vinculado a uma comunidade (parent group).

object

Permissões iniciais. Subcampos: membersCanEditInfo, membersCanSendMessages, membersCanAddOthers, requireAdminApproval.

Notas

O criador do grupo entra automaticamente como super-admin.
Números inválidos (não registrados no WhatsApp) são rejeitados; o erro indica qual participante falhou.
Se image for passada e o upload falhar, a criação do grupo segue normalmente, o erro de imagem não é fatal nesta rota. Use PUT /update para reaplicar a foto.

Erros

HTTP	Mensagem
400	`The 'name' field is required`
400	`At least one participant is required`
400	`group name must be 25 characters or less`
400	`invalid participant <number>: <reason>`
400	`Instance is not connected to WhatsApp`
429	`rate limit exceeded (429): wait before creating again`

Envelope:

{
  "success": false,
  "error": { "message": "The 'name' field is required" }
}

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Descrição

Exemplos

Mínimo

Com descrição e foto

Com permissões

Vinculado a comunidade

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas

Erros

​Descrição

​Exemplos

​Mínimo

​Com descrição e foto

​Com permissões

​Vinculado a comunidade

​Resposta de sucesso

​Parâmetros de rota

​Headers

​Request body

​Notas

​Erros

Descrição

Exemplos

Mínimo

Com descrição e foto

Com permissões

Vinculado a comunidade

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas

Erros