WhatsApp Business groups

Read WhatsApp Business groups are not personal WhatsApp groups before designing around groups: it compares the two features and answers common requests, such as connecting existing groups or adding people by phone number. Create and manage WhatsApp Business groups walks one group through these routes and its events, sandbox first.

Read eligibility

Query params

Response

Requires groups:read. phone_number_id is the Tyxter phone number id (the id on GET /v1/phone-numbers), not Meta's. The answer comes from Tyxter's own records; the call never reaches Meta.

• It serves the answer of the latest completed eligibility check (see below), with its checked_at and check_requested_at.
• With no completed check, a sandbox number answers eligible and a production number answers not_checked, with reasons empty and checked_at null. not_checked says nothing about whether Meta would accept the number.

The full status vocabulary is eligible, not_eligible, unknown, not_checked and read_failed; reasons is non-empty only for not_eligible. Branch on every value.

A missing or blank phone_number_id, or an unknown query parameter, returns 400 invalid_groups_query with param naming it. A phone number that does not exist and one that belongs to another organization, project or environment both return the same 404 phone_number_not_found.

curl "https://api.tyxter.com/v1/groups/eligibility?phone_number_id=$PHONE_NUMBER_ID" \
  -H "authorization: Bearer $TYXTER_API_KEY"

Check eligibility

Request body

Requires groups:write and honors Idempotency-Key: a replay with the same key and body returns the first response and runs no second check. Returns 202 with a GroupEligibilityResponse holding the answer stored at that moment (the previous answer, or the no-check answer) and the new check_requested_at. The call itself never reaches Meta: a Tyxter worker reads the facts afterwards. Poll GET /v1/groups/eligibility until checked_at is later than check_requested_at. A check normally completes shortly after it is accepted, but Tyxter does not promise a completion time: if checked_at has not passed check_requested_at within your own timeout, that check did not complete. You can request a new check at any time, with a new Idempotency-Key.

• A sandbox number answers eligible without any call to Meta.
• A production number answers eligible only when Meta reports a Cloud API number (platform_type CLOUD_API) that is not on the WhatsApp Business app (is_on_biz_app false) and is an Official Business Account, and the connection's token holds whatsapp_business_messaging.
• not_eligible lists each disqualifier Meta reported in reasons: not_cloud_api, whatsapp_business_app_number(assumed to include a number using the WhatsApp Business app and the Cloud API together, from Meta's "not the WhatsApp Business app" requirement), not_official_business_account or missing_messaging_permission.
• unknown means Meta answered without every fact needed and nothing it reported disqualifies the number. Meta documents no field for Official Business Account status, so Tyxter reads a field whose name is assumed. When Meta omits or refuses it, that missing field never by itself makes the answer eligible or not_eligible: with no other disqualifier the answer is unknown, and a disqualifier Meta did report still answers not_eligible.
• read_failed means the check could not read Meta or did not finish — a failed Graph call, an invalid token, a stored Meta credential Tyxter could not open, no connected Meta provider for the environment, or a check that kept failing inside Tyxter. It is never turned into a yes or a no; run the check again later.
• The answer is about the number, whatever its lifecycle status; whether a number can host a group is decided when the group is created.

A body that is not a JSON object, a missing or blank phone_number_id, or an unknown field returns 400 invalid_group_request with param naming it. A foreign or absent phone number returns 404 phone_number_not_found. When an organization owner or admin disables WhatsApp Business groups for the environment in feature controls, the check returns 403 feature_disabled before any work, and the eligibility read keeps answering.

curl -X POST "https://api.tyxter.com/v1/groups/eligibility-checks" \
  -H "authorization: Bearer $TYXTER_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{"phone_number_id":"'"$PHONE_NUMBER_ID"'"}'

Create a group

Request body

Response

Requires groups:write and honors Idempotency-Key: a replay with the same key and body returns the first response as it was sent, with the same group id and status pending, and creates no second group; it does not show the group's current status, so read that with GET /v1/groups/{group_id}. Returns 202 with the group and status pending. The call itself never reaches Meta; a Tyxter worker sends the create afterwards (see Available today). Tyxter sets no length limit of its own on subject or description and checks only that subject is a non-blank string and description a string or null; Meta enforces its own limits, and a value Meta refuses makes the group failed with failure.code group_provider_rejected and Meta's reason, not a request error. join_approval_mode accepts only auto_approve, the default; Meta's documentation describes it as letting anyone who has the group's invite link join without approval (heard). Treat invite_link like a password: anyone who has it can join the group. approval_required returns 400 invalid_group_request because it is not offered yet.

id is the Tyxter group id, minted when the create is accepted; provider_group_id is Meta's group id and invite_link the invite link, both null until Meta confirms the group. status is one of pending, active, failed, deleting or deleted (the last two through a delete, below); a group whose Meta outcome never arrives stays pending, and Tyxter does not guess an outcome. When Tyxter cannot tell whether Meta created the group (for example the call to Meta timed out), the group also stays pending.

• 400 invalid_group_request: the body is not a JSON object, a required field is missing or blank, a field has the wrong type, or the body carries an unknown field; param names it.
• 404 phone_number_not_found: the phone number does not exist or belongs to another organization, project or environment.
• 400 sender_phone_number_unavailable: the number cannot host a group — it is not an active WhatsApp phone number linked to Meta, for example because it was released or disconnected.
• 422 group_phone_number_not_eligible: the stored eligibility answer for the number is not_eligible. Any other answer, or no check at all, admits the create and the group is accepted as pending; Meta then decides (see Available today).
• 403 feature_disabled: WhatsApp Business groups are disabled for the environment in feature controls; the group reads and the delete keep answering (the invite-link reset is refused the same way).

Retrieve a group

Requires groups:read and returns the GroupResponsefrom Tyxter's records; the call never reaches Meta. group_id is the id POST /v1/groupsreturned, never Meta's group id. A deleted group stays readable. If the group_id path segment looks like a personal WhatsApp group — an app-style id ending in @g.us, or an invite link from chat.whatsapp.com that is percent-encoded into the one segment (the SDK's groups.retrieve encodes the id) — the route returns 422 personal_whatsapp_group_not_supported, and the message links WhatsApp Business groups are not personal WhatsApp groups. An invite link pasted into the path unencoded contains slashes, matches no route and returns 404 route_not_found instead. Any other id that does not exist or belongs to another organization, project or environment returns 404 group_not_found.

List groups

Query params

Requires groups:read. Lists the groups of the key's environment, newest first, with cursor pagination and optional phone_number_id and status filters; the response is object: "list" with data, has_more and next_cursor. A phone_number_id from another environment returns an empty page. An invalid or unknown parameter returns 400 invalid_groups_query, and a malformed cursor returns 400 invalid_cursor.

curl -X POST "https://api.tyxter.com/v1/groups" \
  -H "authorization: Bearer $TYXTER_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{"phone_number_id":"'"$PHONE_NUMBER_ID"'","subject":"Support team"}'

curl "https://api.tyxter.com/v1/groups?status=pending&limit=20" \
  -H "authorization: Bearer $TYXTER_API_KEY"

Delete a group

Requires groups:write and honors Idempotency-Key: a replay with the same key returns the first response as it was sent, not the group's current status. Returns 202 with the GroupResponse; the call itself never reaches Meta. What happens depends on the group's status:

• active: the group becomes deleting, and a Tyxter worker deletes it (see Available today). A failure left by an earlier refused delete is cleared.
• failed: Meta never created the group, so it becomes deleted at once, with deleted_at set and no call to Meta; its create failure stays readable.
• deleting or deleted: the group is returned unchanged and nothing starts again.
• pending: 409 group_not_active, because Tyxter has not learned whether Meta created the group; delete it once it is active or failed.

A deleted group stays readable with GET /v1/groups/{group_id} and listed by GET /v1/groups, with status deleted and deleted_at set. The delete keeps working when an organization owner or admin disables WhatsApp Business groups in feature controls, so you can always delete the groups you created. A group_id that looks like a personal WhatsApp group returns 422 personal_whatsapp_group_not_supported, as on retrieve (an invite link pasted unencoded returns 404 route_not_found), and any other id that does not exist or belongs to another organization, project or environment returns 404 group_not_found.

curl -X DELETE "https://api.tyxter.com/v1/groups/$GROUP_ID" \
  -H "authorization: Bearer $TYXTER_API_KEY" \
  -H "idempotency-key: $(uuidgen)"

Reset the invite link

Requires groups:write and honors Idempotency-Key: a replay with the same key returns the first response as it was sent and never resets the link again. There is no request body. Returns 202 with the GroupResponse, still active and still showing the link the reset will replace; the call itself never reaches Meta, and a Tyxter worker resets the link afterwards (see Available today). Read the group with GET /v1/groups/{group_id} to see the new invite_link; there is no separate route to read the link, because it is a field of the group. After a failure, reset again.

• Only an active group can be reset: a pending, failed, deleting or deleted group returns 409 group_not_active and nothing is written.
• A newer reset can replace an earlier queued reset before a worker starts it. While a reset worker is running, a new request returns 409 group_invite_link_reset_in_progress and nothing is written; retry after it finishes. A same-key replay still returns the original accepted response.
• While the group is deleting(a delete accepted while a reset is in progress), a new link Meta returns for the reset is still stored and the reset's outcome leaves failure to the delete; in production a reset not yet sent to Meta when the delete is accepted is not sent (reset again if the delete is refused).
• Tyxter knows the link only from its own records, so a link reset outside Tyxter (for example by calling Meta's API directly with your own app) is not seen, and the stored invite_link can then be stale.
• 403 feature_disabled: WhatsApp Business groups are disabled for the environment in feature controls.

A group_id that looks like a personal WhatsApp group returns 422 personal_whatsapp_group_not_supported, as on retrieve (an invite link pasted unencoded returns 404 route_not_found), and any other id that does not exist or belongs to another organization, project or environment returns 404 group_not_found.

curl -X POST "https://api.tyxter.com/v1/groups/$GROUP_ID/invite-link/reset" \
  -H "authorization: Bearer $TYXTER_API_KEY" \
  -H "idempotency-key: $(uuidgen)"

Participants

participants lists the group's current members, each with its wa_id (the participant's WhatsApp ID, as Meta reports it) and joined_at, oldest join first; participant_countis their number. Tyxter learns membership only from the participant events Meta sends (in sandbox, from the simulation below), never by reading the group from Meta. Events are told apart by participant, action and Meta's event time, which is in whole seconds: each distinct join or removal is recorded once, even when Meta delivers it twice, but two joins (or two removals) of the same participant in the same second count as one, so a leave and rejoin within one second loses the rejoin. Meta does not promise delivery order, so the newest event about a participant decides: a removal that arrives before the join that preceded it leaves the participant out, and a join and a removal in the same second are ordered by arrival. An event Tyxter cannot match to a group, or that fails inside Tyxter, is not applied, and the list can then differ from the group at Meta. A participant who leaves is removed from the list; a group that becomes deleted lists none. While a group is deleting, Meta's joins and removals still apply, and a refused delete keeps them.

Erasing a contact (DELETE /v1/contacts/{id}) removes, from every group in the contact's environment, each participant whose wa_idis exactly the contact's phone number with or without the leading +(for most Brazilian mobile numbers, also without the ninth digit), removes that participant's events from the listen routes, and clears the payload of the stored copies of those webhook events. A wa_id written any other way is not matched: for example an identifier Meta sends that is not the phone number, or a number WhatsApp writes differently from its international form (such as the extra 1in Mexican mobile numbers). Tyxter then no longer knows which of that participant's events it already recorded, so a later event about them, a repeated one included, is recorded again and can list them again.

The erasure does not immediately remove these copies of the participant's wa_id; each leaves on its own schedule:

• the stored reply to a groups request sent with an Idempotency-Key expires 24 hours after the request, and until then a replay of that request can still return the erased participant;
• Tyxter's captured copies of Meta's webhook deliveries are removed by a scheduled cleanup once they are 30 days old;
• Tyxter's raw record of each Meta group event is removed by a scheduled cleanup no sooner than 30 days after Tyxter hands it to its processing queue, and possibly later; a record Tyxter could not hand to its processing queue is kept with no scheduled deletion;
• a webhook delivery already being sent when the erasure completes is not recalled.

Simulate a participant (sandbox)

Request body

Sandbox keys only; requires groups:write and honors Idempotency-Key. Simulates Meta reporting that a participant joined (join) or left (remove) an active group and returns 200 with the GroupResponse, participants included; the call never reaches Meta. A join of a current member or a removal of a non-member changes nothing, so a retry never records the fact twice, with or without a key; a replay with the same key returns the first response.

• 400 sandbox_group_participant_sandbox_only: the key is not a sandbox key. In production, participants change only when Meta reports them.
• 400 invalid_group_request: the body is not a JSON object, wa_id is missing, blank or longer than 64 characters, action is not join or remove, or the body carries an unknown field; param names it.
• 409 group_not_active: the group is not active.
• 409 group_participant_limit_reached: the group already has eight participants, the cap Meta documents (heard); simulate a removal first. Whether Meta also counts the business number is not known. Production applies no limit of Tyxter's own.
• 403 feature_disabled: WhatsApp Business groups are disabled for the environment in feature controls.

A group_id that looks like a personal WhatsApp group returns 422 personal_whatsapp_group_not_supported, as on retrieve, and any other id that does not exist or belongs to another organization, project or environment returns 404 group_not_found.

JavaScript SDK

const eligibility = await client.groups.retrieveEligibility({
  phone_number_id: phoneNumberId,
});
// eligibility.status: 'eligible' | 'not_eligible' | 'unknown' | 'not_checked' | 'read_failed'

const accepted = await client.groups.createEligibilityCheck(
  { phone_number_id: phoneNumberId },
  { idempotencyKey: crypto.randomUUID() },
);
// Poll retrieveEligibility until checked_at is later than accepted.check_requested_at.
// If that has not happened within your own timeout, the check did not complete:
// request a new one (new idempotency key).

const group = await client.groups.create(
  { phone_number_id: phoneNumberId, subject: 'Support team' },
  { idempotencyKey: crypto.randomUUID() },
);
// group.status === 'pending'. Sandbox: it becomes 'active' once the worker has run
// ('failed' if its number can no longer host a group by then). Production: today it
// stays 'pending' unless Meta refuses or Tyxter cannot send the create (see
// "Available today").

const same = await client.groups.retrieve(group.id);
const page = await client.groups.list({ status: 'pending', limit: 20 });

// Sandbox only: simulate a participant joining an active group.
const withMember = await client.sandbox.groups.simulateParticipant(
  group.id,
  { wa_id: '5511999990001', action: 'join' },
  { idempotencyKey: crypto.randomUUID() },
);
// withMember.participants: [{ wa_id: '5511999990001', joined_at: '...' }]

const removed = await client.groups.delete(group.id, { idempotencyKey: crypto.randomUUID() });
// removed.status: 'deleting' for an active group, 'deleted' for a failed one;
// a pending group throws a TyxterApiError with code 'group_not_active'.

const resetting = await client.groups.resetInviteLink(group.id, {
  idempotencyKey: crypto.randomUUID(),
});
// resetting.status === 'active' and still shows the old link; read the group
// with retrieve to see the new invite_link once the worker has run.