Skip to main content
POST
/
instances
/
{instanceId}
/
token
/
{token}
/
create-group
Creating groups
curl --request POST \
  --url https://api.z-api.io/instances/{instanceId}/token/{token}/create-group \
  --header 'Client-Token: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "autoInvite": true,
  "groupName": "<string>",
  "phones": [
    {}
  ]
}
'
{
  "phone": "<string>",
  "phonesNotAdded": [
    {}
  ],
  "invitationLink": "<string>"
}

​
Overview

This method is responsible for creating a group with its respective participants.
It is not possible to add an image during creation, but you can add one afterwards using the update group image method.
You must not pass the connected number in the participants list. At least one contact is required to create a group, just like on WhatsApp Web.
When creating a new group, you must use phone numbers exclusively. The @lid identifier is not supported for group creation — if provided, the group will be created normally, but the participant with @lid will not be included and their identifier will be returned in the phonesNotAdded field.

​
Attributes

​
instanceId
string
required
Your instance ID. Available in the Z-API panel under Instances.
​
token
string
required
Your Z-API instance token.

​
Required

​
autoInvite
boolean
required
Defines whether a private invite will be sent to participants who cannot be added directly
​
groupName
string
required
Group name
​
phones
array
required
List of participant phone numbers

​
Request Body

{
  "autoInvite": true,
  "groupName": "Z-API Group",
  "phones": ["5544999999999", "5544888888888"]
}

​
Response

​
200

​
phone
string
ID/Phone of the created group
​
phonesNotAdded
array
List of identifiers that were not added to the group. A participant may appear here for two reasons:
  • Use of @lid: identifiers in the @lid format are not supported for group creation. The group will be created normally, but the participant with @lid will be left out and their identifier will be listed here.
  • Permission issue (autoInvite): when a number cannot be added directly to the group and autoInvite is enabled, a private invite is sent to them. Until the invite is accepted, the number is returned in this field.
​
invitationLink
string
Group invitation link
{
  "phone": "120363019502650977-group",
  "phonesNotAdded": [
    "2111897971174599@lid",
    "5544777777777"
  ],
  "invitationLink": "https://chat.whatsapp.com/GONwbGGDkLe8BifUWwLgct"
}

​
405

In this case, make sure you are correctly specifying the request method — check whether you sent POST or GET as specified at the beginning of this topic.

​
415

If you receive a 415 error, make sure to add the “Content-Type” header to your request with the type of object you are sending, most commonly “application/json”.