Manage Participants

Auth: TokenAccount or TokenInstance • Rate-limit: Global (100/min) • Idempotent: no

Description

Single endpoint for 6 actions on participants, set the operation in the action field. Each participant gets an individual result (success: bool), so partial operations are possible: the call may return 200 with some members failing.

Examples

Add to Group

Adds 2 numbers to the group 120363406289005073@g.us in a single call (action: "add"). Failures from privacy settings or numbers without WhatsApp are isolated as success: false in the participants array.

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

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

import os, requests

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

package main

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

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

Promote to Admin

Promotes the number 5511999999999 to admin via action: "promote". Requires that you are super-admin of the group (creator or promoted by another super-admin).

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

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

import os, requests

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

package main

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

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

Demote to Member

Removes the admin role from the number 5511999999999 via action: "demote", returning them to plain member status. Also requires super-admin privilege.

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

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

import os, requests

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

package main

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

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

Approve Group Join (pending request)

Approves a pending join request by passing the LID 199789077627112@lid in participants with action: "approve". Only works in groups with requireAdminApproval=true.

curl -X POST "https://ryzeapi.cloud/api/group/participants/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "approve",
    "identifier": "120363406289005073@g.us",
    "participants": ["199789077627112@lid"]
  }'

await fetch(`https://ryzeapi.cloud/api/group/participants/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    action:       "approve",
    identifier:   "120363406289005073@g.us",
    participants: ["199789077627112@lid"]
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/group/participants/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "action":       "approve",
        "identifier":   "120363406289005073@g.us",
        "participants": ["199789077627112@lid"]
    }
)

package main

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

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

Reject Group Join (pending request)

Rejects a pending request from the number 5511999999999 via action: "reject". The service automatically resolves the equivalent LID when you pass only the phone number.

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

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

import os, requests

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

package main

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

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

Remove from Group

Removes the number 5511999999999 from the group via action: "remove". The ex-member can rejoin via the invite link unless you generate a new link with /reset-link.

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

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

import os, requests

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

package main

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

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

Success response

Each participant receives an individual result with success: true|false in the participants array. Partial operations are possible, the call may return 200 even with some members failing (number without WhatsApp, privacy blocks add, already a member, etc.). Always inspect each entry to detect isolated errors; the error field carries the reason when success=false.

200 OK (partial)

{
  "success": true,
  "message": "Successfully added 2 participant(s)",
  "groupJid": "120363406289005073@g.us",
  "action": "add",
  "participants": [
    {
      "jid": "5511999999999@s.whatsapp.net",
      "isAdmin": false,
      "isSuperAdmin": false,
      "success": true
    },
    {
      "jid": "5521988888888@s.whatsapp.net",
      "isAdmin": false,
      "isSuperAdmin": false,
      "success": false,
      "error": "user not on whatsapp"
    }
  ]
}

Individual failures (success: false) do not abort processing of the remaining participants. Always inspect each entry to detect partial errors (e.g., number without WhatsApp, already a member, privacy blocks add).

Path parameters

string

required

Instance name.

Headers

string

required

TokenAccount or TokenInstance.

string

required

application/json

Request body

string

required

One of: add, remove, promote, demote, approve, reject.

string

required

Group JID, invite code, or link.

string[]

required

Numbers or JIDs targeted by the operation. At least 1 item.

Action table

`action`	Permission	Timeout	Use
`add`	Admin	60s	Add numbers / JIDs
`remove`	Admin	60s	Remove members
`promote`	Super-admin	60s	Make admin
`demote`	Super-admin	60s	Remove admin
`approve`	Admin	90s	Approve pending request
`reject`	Admin	90s	Reject pending request

Notes

promote / demote require you to be super-admin (group creator or promoted by a super-admin).
approve / reject only work for groups with requireAdminApproval=true and have a longer timeout (90s) since they depend on responses from WhatsApp.
For approve/reject, prefer to pass the LID returned by /requests; if you only have the phone number, the service tries to resolve the equivalent LID automatically.

Errors

HTTP	Message
400	`Invalid action. Must be one of: add, remove, promote, demote, approve, reject`
400	`At least one participant is required`
400	`Identifier is required`
403	`Not authorized to perform this action (must be admin)`
404	`Group not found or you are not a member of this group`

Envelope:

{
  "success": false,
  "error": { "message": "Invalid action. Must be one of: add, remove, promote, demote, approve, reject" }
}

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Manage Participants

Description

Examples

Add to Group

Promote to Admin

Demote to Member

Approve Group Join (pending request)

Reject Group Join (pending request)

Remove from Group

Success response

Path parameters

Headers

Request body

Action table

Notes

Errors

​Description

​Examples

​Add to Group

​Promote to Admin

​Demote to Member

​Approve Group Join (pending request)

​Reject Group Join (pending request)

​Remove from Group

​Success response

​Path parameters

​Headers

​Request body

​Action table

​Notes

​Errors

Description

Examples

Add to Group

Promote to Admin

Demote to Member

Approve Group Join (pending request)

Reject Group Join (pending request)

Remove from Group

Success response

Path parameters

Headers

Request body

Action table

Notes

Errors