Receive before sending
- Have a participant add the agent’s WhatsApp number to the group.
- Have another participant send a message that the agent receives.
- Find the authorized conversation through conversation history or a
whatsapp.receivedevent. - Reply using its
conversation_id.
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 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 for 429 responses and retry conditions.
Names identify the display, IDs identify the conversation
Group conversation and message objects includeis_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 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 stableconversation_id. Follow the signed ordinary, initialization, and live phases described in 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.
Reply to an incoming group message
In these examples,incoming is the message object from a whatsapp.received webhook:
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 represent quote chains, not separate chat channels.
Media and reactions
Upload media, then pass its ID inmedia_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 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.