Communities

Create a community, add subgroups, link groups, list participants, get the invite link.

  • POST/v1/sessions/<CHANNEL_ID>/communities

    Create a community.

  • GET/v1/sessions/<CHANNEL_ID>/communities/<COMMUNITY_JID>

    Get one community.

  • GET/v1/sessions/<CHANNEL_ID>/communities/<COMMUNITY_JID>/invite-link

    Get its invite link.

  • GET/v1/sessions/<CHANNEL_ID>/communities/<COMMUNITY_JID>/participants

    List its participants.

  • GET/v1/sessions/<CHANNEL_ID>/communities/<COMMUNITY_JID>/subgroups

    List its subgroups.

  • POST/v1/sessions/<CHANNEL_ID>/communities/<COMMUNITY_JID>/subgroups

    Create a subgroup.

  • POST/v1/sessions/<CHANNEL_ID>/communities/<COMMUNITY_JID>/links

    Link an existing group.

  • DELETE/v1/sessions/<CHANNEL_ID>/communities/<COMMUNITY_JID>/links/<GROUP_JID>

    Unlink a group.

A community is a group with is_community: true.

Group adds are counted. Creating a community is one add, linking a group is one add, and creating a subgroup is one add for the subgroup, one for its link and one for each participant you create it with. The count only matters on a sandbox channel (5 group adds a day) and on a channel with warm-up protection on. See Limits.

Create a community

bash
curl -X POST "https://api-wagate.socialground.co/v1/sessions/<CHANNEL_ID>/communities" \
  -H "Authorization: Bearer <CHANNEL_TOKEN>" -H "Content-Type: application/json" \
  -d '{"subject": "My community"}'

Answers 201 with a group object where is_community is true. subject is 1 to 25 characters. WhatsApp also creates the community's announcement group, so a new community already has one subgroup.

Get a community

GET communities/<COMMUNITY_JID> returns the same fields as a group. See Groups.

The invite link comes from GET communities/<COMMUNITY_JID>/invite-link and answers {"invite_link": "..."}. If the JID is a group and not a community, it answers 400. Use the group invite link route for groups.

Subgroups

bash
curl "https://api-wagate.socialground.co/v1/sessions/<CHANNEL_ID>/communities/[email protected]/subgroups" \
  -H "Authorization: Bearer <CHANNEL_TOKEN>"
json
{ "subgroups": [ { "jid": "[email protected]", "name": "Announcements", "is_default_subgroup": true } ] }

is_incognito is not returned by this API.

Create one:

bash
curl -X POST "https://api-wagate.socialground.co/v1/sessions/<CHANNEL_ID>/communities/[email protected]/subgroups" \
  -H "Authorization: Bearer <CHANNEL_TOKEN>" -H "Content-Type: application/json" \
  -d '{"subject": "Support", "participants": ["66XXXXXXXXX"], "hidden": true}'
  • subject is required, 1 to 25 characters. participants is optional, at most 50. hidden is optional.
  • Answers 201 with the group. With hidden: true, a 201 does not prove the subgroup is hidden, because WhatsApp gives no readable signal for that. Check on a phone if it matters.
  • With hidden: true, the new group is read back to check it is linked to the community. If it is not, you get 409 verification_failed with group_jid, verification: "failed", definitive: true and retry_as_ambiguous: false. The subgroup WAS created. Do not create it again. Link the group_jid from the error with the links route instead.

Link and unlink a group

bash
curl -X POST "https://api-wagate.socialground.co/v1/sessions/<CHANNEL_ID>/communities/[email protected]/links" \
  -H "Authorization: Bearer <CHANNEL_TOKEN>" -H "Content-Type: application/json" \
  -d '{"group_jid": "[email protected]", "hidden": false}'

curl -X DELETE "https://api-wagate.socialground.co/v1/sessions/<CHANNEL_ID>/communities/[email protected]/links/[email protected]" \
  -H "Authorization: Bearer <CHANNEL_TOKEN>"

Both answer 200 with the group object, after reading the group back to confirm the change took.

WhatsApp fixes whether a linked group is hidden at the moment it is linked. To change it, unlink the group and link it again with the new hidden value.

Participants

bash
curl "https://api-wagate.socialground.co/v1/sessions/<CHANNEL_ID>/communities/[email protected]/participants" \
  -H "Authorization: Bearer <CHANNEL_TOKEN>"
json
{
  "participants": [
    { "jid": "[email protected]", "phone_number": "[email protected]", "phone_resolved": true }
  ],
  "count": 1
}

This is everyone across the community's linked groups. WhatsApp may identify a person by LID. Then jid and lid hold the LID, and phone_number is present only when the phone number is known. phone_resolved says which case you have.

Errors on these routes

  • 409 not_linked: the number is not linked. 409 stood_down: WhatsApp restricted the number and WAgate stopped using it.
  • 409 verification_failed: subgroup create only, see above.
  • 403 blocked: the channel is blocked.
  • 429 daily_cap_group_add: warm-up protection is on and today's group-add allowance is used up.
  • 429 sandbox_allowance_exceeded: a sandbox channel used its 5 group adds for the day.

See Errors.

Communities · WAgate docs