Skip to main content
WhatsApp is available by approval for an agent that already has a dedicated personal iMessage number. The approved WhatsApp channel uses that same number. Shared WhatsApp numbers are not supported. Open the Inkbox Console, select your agent, and open Phone → WhatsApp. If the agent does not have access, choose Request Access. A dedicated iMessage number establishes eligibility; it does not automatically enable WhatsApp. Creating an identity, editing its fields, or subscribing to events does not enable the channel.

Check current availability

Read fresh channel status before sending. enabled describes approved access, while status describes current availability. An enabled channel can be temporarily unavailable. Do not treat an old identity snapshot as the final answer after access changes.
Basic direct-message SDK and CLI helpers require version 0.7.26 or later. Group metadata, Companion, and message-link/QR onboarding helpers require version 0.7.29 or later. SDK status helpers return None in Python or null in TypeScript when an older API does not expose WhatsApp status.

Invite someone to message your agent

Share a WhatsApp message link or QR code for your agent’s enabled number. It opens WhatsApp with Hello! prefilled; the person must tap Send. No connect message is needed. Opening the link does not send a message or enable access.

Messages and attachments

Send to as one E.164 string for a direct message, or use an existing direct-message or group conversation_id. All arrays, including singleton arrays, and comma-separated lists are rejected for to. There is no fanout. Each message can contain text, one attachment, or both, within the current WhatsApp limits. The initial attachment fallback is 5 MiB. Transport ceilings are 4,000 Unicode code points and 20 MiB; opening-message and organization policies can be lower. In a direct conversation, before that recipient’s first WhatsApp reply, the initial policy allows three short text messages of at most 159 Unicode code points each. Do not include links, phone numbers, media, or email addresses in those opening messages. Read the current limits before sending; each content permission is independently configurable. Upload the attachment first, then send its returned media ID. Keep that ID and the logical-send key when a request times out. Do not re-upload or generate another key to retry the same intended message. Attachment URLs expire; retrieve a fresh authorized URL by media ID. A queued message is accepted, not delivered. Read its current status separately from delivery_state. A confirmed sent message with unknown delivery is not a failed send. An uncertain send is not proof that nothing was sent. Check the original message rather than automatically sending another copy.

Existing groups

Have another participant add the agent’s WhatsApp number to a group. Inkbox does not create groups or manage membership. Another participant must send a message that the agent receives before the agent can send text, attachments, quoted replies, or reactions there. Joining, a reaction, or the agent’s own message does not meet this requirement. Groups appear in authorized conversation history with is_group and group_name. Use the stable conversation_id to reply; names are display labels and can change or be duplicated. Current contact permissions still apply. SDK and CLI group support requires 0.7.29 or later. See existing group conversations.

Receive events

Create an identity-owned webhook subscription for whatsapp.received and any delivery events you need. Verify webhook signatures and deduplicate retries by the event ID. Only a received-message event represents new incoming content; delivery events should update tracking without starting another reply. You can select WhatsApp events before approval. Matching deliveries begin when the channel becomes available. Subscribing does not grant access or import earlier account history.

History and local unread state

Browse conversations and messages in the Console or API. Disabling access prevents new sends while retained history remains available to its original authorized owner. Replacing or detaching the qualifying dedicated iMessage number disables WhatsApp access; an old conversation does not transfer to a different agent. Marking a conversation read updates Inkbox’s local unread state through an exact message boundary. It does not send a remote read receipt. Request WhatsApp explicitly in contact correspondence. Existing default channel selections do not include it.

Supported scope

This version supports direct messages and replies in existing groups, including text, attachments, native quoted replies, and whole-message reactions. The Console can read attachments but does not upload files. Phone contact rules apply to the remote recipient for direct messages and to every participant for groups. Groups with unavailable participant numbers remain unusable until a later incoming message reports every participant’s number and those numbers pass the current directional contact rules; changing contact rules alone does not resolve missing numbers. Native quotes never silently fall back to an unquoted message. Read threads for chronological quoted context. Reactions return versioned receipts; a pending or uncertain receipt is not an applied reaction. The Console keeps these states distinct and lets you remove your own selected reaction version. Typing indicators, remote read receipts, and WhatsApp calls are not supported. WhatsApp groups can use Companion mode with the identity’s existing enabled preference and an eligible sponsor. Automatic contact-memory extraction is not enabled by joining a group.

Reference