Create Group

Create a new WhatsApp group with specified participants.

POST /group/create/:instanceName

cURL

curl --request POST \
  --url https://api.example.com/group/create/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "subject": "Project Team",
    "participants": [
      "5511999999999",
      "5511888888888",
      "5511777777777"
    ],
    "description": "Team collaboration group",
    "promoteParticipants": false
  }'

const response = await fetch(
  'https://api.example.com/group/create/my-instance',
  {
    method: 'POST',
    headers: {
      'apikey': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: 'Project Team',
      participants: [
        '5511999999999',
        '5511888888888',
        '5511777777777'
      ],
      description: 'Team collaboration group',
      promoteParticipants: false
    })
  }
);

const data = await response.json();

import requests

response = requests.post(
    'https://api.example.com/group/create/my-instance',
    headers={
        'apikey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'subject': 'Project Team',
        'participants': [
            '5511999999999',
            '5511888888888',
            '5511777777777'
        ],
        'description': 'Team collaboration group',
        'promoteParticipants': False
    }
)

data = response.json()

201 Success

{
  "groupJid": "[e-mail]",
  "subject": "Project Team",
  "participants": [
    {
      "id": "[e-mail]",
      "isAdmin": false,
      "isSuperAdmin": false
    },
    {
      "id": "[e-mail]",
      "isAdmin": false,
      "isSuperAdmin": false
    },
    {
      "id": "[e-mail]",
      "isAdmin": false,
      "isSuperAdmin": false
    }
  ],
  "createdAt": 1709553600
}

{
  "error": "Invalid request",
  "message": "Subject is required and must not exceed 25 characters"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Instance not found",
  "message": "The instance 'my-instance' does not exist"
}

Overview

You can create a new WhatsApp group with a subject (name) and add initial participants. Optionally, you can set a description and automatically promote specific participants to admin status.

All phone numbers should be in international format without the ’+’ sign (e.g., 5511999999999).

Authentication

This endpoint requires authentication via the apikey header.

header.apikey · string · required

Your Evolution API key for authentication.

Path Parameters

path.instanceName · string · required

The name of your WhatsApp instance.

Request Body

subject · string · required

The name of the group (maximum 25 characters).

participants · string[] · required

Array of participant phone numbers in international format (e.g., [“5511999999999”, “5511888888888”]).

description · string

Optional group description.

promoteParticipants · boolean · default: "false"

If true, all participants will be promoted to admin status upon group creation.

Response

groupJid · string

The WhatsApp JID of the newly created group (format: [e-mail]).

subject · string

The group name.

participants · array

Array of participant objects.

Show properties

id · string

Participant’s WhatsApp JID.

isAdmin · boolean

Whether the participant is an admin.

isSuperAdmin · boolean

Whether the participant is a super admin.

createdAt · number

Unix timestamp of when the group was created.

cURL

curl --request POST \
  --url https://api.example.com/group/create/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "subject": "Project Team",
    "participants": [
      "5511999999999",
      "5511888888888",
      "5511777777777"
    ],
    "description": "Team collaboration group",
    "promoteParticipants": false
  }'

const response = await fetch(
  'https://api.example.com/group/create/my-instance',
  {
    method: 'POST',
    headers: {
      'apikey': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: 'Project Team',
      participants: [
        '5511999999999',
        '5511888888888',
        '5511777777777'
      ],
      description: 'Team collaboration group',
      promoteParticipants: false
    })
  }
);

const data = await response.json();

import requests

response = requests.post(
    'https://api.example.com/group/create/my-instance',
    headers={
        'apikey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'subject': 'Project Team',
        'participants': [
            '5511999999999',
            '5511888888888',
            '5511777777777'
        ],
        'description': 'Team collaboration group',
        'promoteParticipants': False
    }
)

data = response.json()

201 Success

{
  "groupJid": "[e-mail]",
  "subject": "Project Team",
  "participants": [
    {
      "id": "[e-mail]",
      "isAdmin": false,
      "isSuperAdmin": false
    },
    {
      "id": "[e-mail]",
      "isAdmin": false,
      "isSuperAdmin": false
    },
    {
      "id": "[e-mail]",
      "isAdmin": false,
      "isSuperAdmin": false
    }
  ],
  "createdAt": 1709553600
}

{
  "error": "Invalid request",
  "message": "Subject is required and must not exceed 25 characters"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Instance not found",
  "message": "The instance 'my-instance' does not exist"
}

Usage Notes

WhatsApp requires at least one participant (besides the creator) to create a group.

Invalid phone numbers or numbers not registered on WhatsApp will be silently skipped during group creation.

The instance owner is automatically added as the group creator and super admin.