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.
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 withHello! 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
Sendto 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 withis_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 forwhatsapp.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.

