> ## Documentation Index
> Fetch the complete documentation index at: https://inkbox.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Existing groups

> Receive group messages and reply with text, media, reactions, or quoted replies

Inkbox supports conversations in WhatsApp groups that another participant has added your agent to. It does not create groups, invite members, or change group membership.

## Receive before sending

1. Have a participant add the agent’s WhatsApp number to the group.
2. Have another participant send a message that the agent receives.
3. Find the authorized conversation through [conversation history](https://inkbox.ai/docs/api/whatsapp/conversations.md) or a [`whatsapp.received` event](https://inkbox.ai/docs/api/whatsapp/webhooks).
4. Reply using its `conversation_id`.

Joining a group is not enough. A reaction, membership update, or the agent’s own message does not unlock sending. Text, attachments, quoted replies, and reactions all require an incoming message from another participant. Imported or synced old history does not unlock sending. After the WhatsApp connection is replaced, another participant must send a new message. Current contact permissions for group participants and channel availability still apply. Group metadata reflects the latest observed snapshot, not a live membership feed. Queued messages and reactions retain the participant fingerprint observed when the operation is accepted. If participants or their identity mappings change before handoff, the original operation fails; a later conversation refresh or incoming message does not revive it. Failed message sends report `whatsapp_send_rejected` and a `whatsapp.delivery_failed` event. After a confirmed failure, review the current conversation before making a new request. Replaying an accepted request with its original idempotency key returns its original result; it does not resend a failed message. Only a confirmed failure, not an uncertain outcome, permits a deliberate new send attempt with a new key.

If any participant’s number is unavailable (`unresolved_participant_count` > 0), incoming messages are blocked and sends or reactions return `403 whatsapp_contact_not_allowed`. Under ordinary permissions, contact rules apply separately by direction: an inbound-rule failure blocks the incoming message and suppresses `whatsapp.received`; an outbound-only rule failure still permits incoming events but rejects sends and reactions. After a restriction is resolved, another participant must send a new message only if this connection has no qualifying unblocked incoming message. Lifting an outbound restriction does not erase an earlier qualifying message. [Companion sponsorship](#companion-groups) can authorize otherwise default-filtered group traffic within its current scope; explicit blocks and unresolved membership remain enforced.

Changes to group admin roles or announcement permissions do not by themselves require a new incoming message when the participants are unchanged. The agent must still belong to the group and have permission to send. Text, media, and reactions are rejected if the agent loses that permission or current group information cannot be verified. Do not modify an existing attempt or retry an uncertain outcome as a new operation.

Before accepting a group send or reaction, Inkbox checks current group membership. If that check is temporarily unavailable, the request returns `503` without accepting an operation. Retry the same request with the same idempotency key after availability recovers; a previously accepted request still returns its original result.

An outbound request without the required incoming message returns `409 whatsapp_group_reply_required`. A group operation that is not yet available returns `409 whatsapp_capability_not_ready`. These rejections do not authorize a direct-message fallback or a new send under a different key.

Group sends share the daily message allowance, `whatsapp.consecutive_unanswered_messages`, and `whatsapp.conversations_per_line_per_24h` with direct sends. Another participant’s allowed incoming message in the current connection resets that group’s unanswered count. First-contact and follow-up limits apply to direct conversations only. See [limits](https://inkbox.ai/docs/api/whatsapp/limits.md) for `429` responses and retry conditions.

## Names identify the display, IDs identify the conversation

Group conversation and message objects include `is_group: true`, nullable `group_name`, and `unresolved_participant_count`. Display `group_name` when available. Names can change and multiple groups can share a name, so send with the stable conversation ID, never a name. `remote_number` is null for groups. `participants` contains known remote phone numbers; an unknown number is not a fabricated phone number.

The SDK and CLI expose these fields in version `0.7.29` or later. Parsed TypeScript SDK results use `isGroup`, `groupName`, and `unresolvedParticipantCount`. Raw webhook messages retain the snake\_case fields: `is_group`, `group_name`, and `unresolved_participant_count`.

## Companion groups

Use the identity’s existing [Companion mode](https://inkbox.ai/docs/capabilities/companion-mode.md) preference; WhatsApp does not have a separate enablement flag. A qualifying incoming message from a participant with active exact-number allow rules in both directions can sponsor this existing group. The activation belongs to this conversation and its verified participant set, not to those people in other chats.

The original sponsor must remain eligible and present. Disabling Companion, revoking a required allow, or changing group membership ends the old permission for new messages and replies. A later qualifying message can establish a new activation, but queued replies cannot transfer to it. Queued reactions and reaction removals likewise retain their original borrowed permission and cannot transfer to a later activation. Current membership must be verifiable before borrowing access. Ordinary independently permitted access remains separate.

Messages already authorized for your identity remain readable after sponsorship ends, including after Companion is disabled or group membership changes. This does not authorize new messages or replies. Identity and channel access, deletion, and retention still apply. Previously unauthorized messages do not become visible merely because they share the group.

Use the existing activation history and reply context, preserve the current activation, and send to the stable `conversation_id`. Follow the signed ordinary, initialization, and live phases described in [Companion conversation events](https://inkbox.ai/docs/webhooks.md#companion-conversation-events). Sponsorship does not create groups or remove the requirement for another participant’s incoming message.

## Mention the agent

Use WhatsApp’s normal `@` picker to select the agent in a group. The incoming message reports `agent_mentioned: true` through the existing `whatsapp.received` event; absent mention metadata defaults to `false`. Compatible agent integrations can use this flag in mention-only group reply mode, alongside literal `@agent-handle` text. See [group mentions](https://inkbox.ai/docs/api/whatsapp/webhooks.md#group-mentions).

## Reply to an incoming group message

In these examples, `incoming` is the message object from a `whatsapp.received` webhook:

```python Python theme={null}
message = identity.send_whatsapp(
    conversation_id=incoming["conversation_id"],
    reply_to_message_id=incoming["id"],
    text="Thanks, I’ll take a look.",
    idempotency_key="group-brief-reply",
)
```

```typescript TypeScript theme={null}
const message = await identity.sendWhatsApp({
  conversationId: incoming.conversation_id,
  replyToMessageId: incoming.id,
  text: "Thanks, I’ll take a look.",
  idempotencyKey: "group-brief-reply",
});
```

```bash CLI theme={null}
inkbox whatsapp send --identity my-agent \
  --conversation-id 22222222-2222-4222-8222-222222222222 \
  --reply-to-message-id 33333333-3333-4333-8333-333333333333 \
  --text "Thanks, I’ll take a look." \
  --idempotency-key group-brief-reply
```

Replace the example UUIDs with the IDs from your incoming message. If you instead use a parsed TypeScript SDK history result, read `incoming.conversationId`. Omit `reply_to_message_id` for an ordinary message in the same group. A quoted reply must target an accessible message in that conversation. [Threads](https://inkbox.ai/docs/api/whatsapp/threads.md) represent quote chains, not separate chat channels.

## Media and reactions

[Upload media](https://inkbox.ai/docs/api/whatsapp/media.md), then pass its ID in `media_ids` with the same `conversation_id`. You can send images, videos, audio, or documents. Set `gif_playback` with an MP4 attachment for animated playback. A quoted media reply can also include `reply_to_message_id`.

Reusing media from an incoming message requires continued access to that original message as well as permission to send to the destination. Companion sponsorship can provide that access within its authorized conversation; permission to send elsewhere does not grant access to an otherwise inaccessible attachment.

Use the existing [reaction API](https://inkbox.ai/docs/api/whatsapp/reactions.md) with the target message ID. Each message, reaction, and reaction removal needs its own stable idempotency key. Keep that key when a request times out; do not send another copy because delivery is uncertain.

Group delivery state describes observed delivery, not confirmation that every member has read the message. Group message `recipients` is empty rather than inventing individual delivery receipts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.