Fetch Active Groups

Fetch List of Active WhatsApp Groups API

This API retrieves a list of WhatsApp groups created under a specific app on Gupshup. It supports pagination using limit, after, and before query parameters.

Endpoint

GET {{API_FRONT_URL}}/app/{APP_ID}/group?limit={limit}&after={after}&before={before}

Headers

Key	Description	Required
`apikey`	API key of the account where the app exists. Must be a valid Gupshup.io API key.	✅ Yes
`Content-Type`	Must be `application/json`.	✅ Yes

Query parameters

Parameter	Description	Required	Constraints
`limit`	Number of groups to return per page	❌ No	Min: 1, Max: 1024, Default: 25
`after`	Cursor to paginate forward	❌ No	String cursor
`before`	Cursor to paginate backward	❌ No	String cursor

Path parameters

Parameter	Description	Required	Constraints
`APP_ID`	ID of your WhatsApp app	✅ Yes	Must be a valid Gupshup App ID

Request Body

Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "participants": [
    { "user": "<PHONE_NUMBER> or <WA_ID>" },
    { "user": "<PHONE_NUMBER> or <WA_ID>" }
  ]
}

Body Parameters

Key	Description	Required	Constraints
`messaging_product`	Must be `"whatsapp"`	✅ Yes	Fixed value
`participants`	Array of objects with a `user` field (phone number or WhatsApp ID to remove)	✅ Yes	Max 8 participants, not empty

Response

Success (HTTP 200)

{
  "data": [
    {
      "creation_timestamp": TS,
      "id": "GROUP ID",
      "subject": "GROUP SUBJECT"
    }
  ],
  "paging": {
    "cursors": {
      "after": "AFTER",
      "before": "BEFORE"
    },
    "next": "https://graph.facebook.com/v20.0/105406242200849/groups?limit=25&after=..."
  },
  "status": "success"
}

Error

If the request fails, the server will return a corresponding HTTP error status and message. Common causes include:

Invalid APP_ID
Missing or invalid API key
Improper query parameter formatting

Response Parameters

Key	Description
`data`	Array of group objects containing `id`, `subject`, and `creation_timestamp`
`paging.cursors.after`	Cursor for fetching the next page
`paging.cursors.before`	Cursor for fetching the previous page
`paging.next`	Full URL to retrieve the next page
`status`	API request status (e.g., `"success"`)

Example cURL

curl --location --globoff '{{API_FRONT_URL}}/app/{{APP_ID}}/group?limit=25&after=null&before=null' \
--header 'Content-Type: application/json' \
--header 'apikey: {{API_KEY}}'

Notes

Pagination is cursor-based. Use the after and before cursors from the response to navigate pages.
If no limit is specified, the API defaults to 25 groups per page.
You can fetch up to a maximum of 1024 groups in a single request.

Updated about 9 hours ago