SPspurnow
WhatsApp Groups

Create a WhatsApp group (asynchronous)

Starts group creation at Meta and returns the pending conversation in the creating state. The group is finalized asynchronously by the group_lifecycle_update webhook (or the polling reconciler), so poll GET /v2/groups/{id} until lifecycleStatus is active before inviting anyone or reading inviteLink. Note the shape changes: this response carries lifecycleStatus at the top level, while the GET nests it as group.lifecycleStatus. Reusing the path from this response makes a poll read nothing and time out on a group that is already active.

Send an idempotencyKey to make the call repeat-safe: the first request creates the group, and any later request carrying the same key returns that same group instead of creating a second one. Without a key, two requests produce two groups, since WhatsApp itself offers no idempotency.

A repeat returns the group exactly as it already is, so the subject and description sent with the repeat are ignored, not applied. Use POST /v2/groups/{id}/settings to change either after creation.

post/v2/groups

Request

  • Base URL
    https://api.spurnow.com
  • Auth
    HTTP bearer

Request body

channelIdnumber required

WhatsApp channel to create the group on.

subjectstring required

Group subject (trimmed, 1-128 characters).

descriptionstring

Optional group description (trimmed, up to 2048 characters).

idempotencyKeystring

Your own key identifying what this group is for, unique per workspace. Repeating a request with the same key returns the group created the first time instead of creating a second one, which makes retries and duplicate form submissions safe. Use something stable and specific, such as partner:acme@example.com.

Response

The new group. When the idempotencyKey was already used, the group that key created, unchanged.

idnumber required
metaGroupIdstring nullable required
channelIdnumber required
requestIdstring nullable required
subjectstring nullable required
descriptionstring nullable required
notesstring nullable required

Internal group-level notes used as AI context. Never sent to WhatsApp.

inviteLinkstring nullable required
profilePictureUrlstring nullable required

S3 URL of the group icon Meta accepted. Rendered by the UI; Meta stores its own copy for delivery to WhatsApp. Null if never set or if a subsequent update was rejected by Meta.

lifecycleStatus'creating' | 'active' | 'suspended' | 'deleted' required
conversationStatus'OPEN' | 'CLOSED' required
assignedAgentIdnumber nullable required
assignedTeamIdnumber nullable required
lastMessageAtstring date-time nullable required
agentLastSeenAtstring date-time nullable required
createdAtstring date-time required
updatedAtstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.