Let an external board take over a WhatsApp conversation without duplicate Whats91 automation replies.
Custom Board Control
Summary
Let an external board take over a WhatsApp conversation without duplicate Whats91 automation replies.
Prerequisites
- A Whats91 account
- A generated public API token
Custom board control lets an external board coordinate with Whats91 internal automation. It never blocks webhook delivery to your board. It only suppresses Whats91 internal responders — Flow Builder, chatbots, AI Agent, and MetaBot — for matching messages or owned conversations.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v3/custom-boards/keyword-exclusions | List sender-scoped keyword exclusions. |
| POST | /api/v3/custom-boards/keyword-exclusions | Create a keyword exclusion. |
| PATCH | /api/v3/custom-boards/keyword-exclusions/{uid} | Update a keyword exclusion. |
| DELETE | /api/v3/custom-boards/keyword-exclusions/{uid} | Delete a keyword exclusion. |
| POST | /api/v3/custom-boards/sessions/acquire | Acquire a conversation session for one board. |
| POST | /api/v3/custom-boards/sessions/{sessionUid}/renew | Renew an active session lease. |
| POST | /api/v3/custom-boards/sessions/{sessionUid}/release | Release an active session lease. |
| GET | /api/v3/custom-boards/sessions/active | Check whether a conversation has an active session. |
Runtime Behaviour
- Whats91 stores the inbound message and conversation.
- Campaign opt-out and resubscribe handling runs first.
- Custom-board control is checked.
- If a custom-board session is active for the conversation, Whats91 skips Flow Builder, chatbots, AI Agent, and MetaBot.
- If a keyword exclusion matches the message, Whats91 skips the same internal responders.
- Vendor webhooks, BusyNotify forwarding, and Pub/Sub forwarding still receive the inbound message.
| Runtime skip reason | Cause |
|---|---|
| custom_board_session_active | An active session lease owns the conversation. |
| custom_board_keyword_excluded | A keyword exclusion matched the inbound message. |
| custom_board_control_lookup_failed | The lookup failed and Whats91 failed open rather than causing a silent outage. |
Recommended Flow
- Create keyword exclusions for the takeover keywords your board owns.
- Receive the inbound webhook for a matching message.
- Immediately call sessions/acquire for the same contactPhone so follow-up messages stay owned by your board.
- Renew the lease while the board conversation is active.
- Release the lease when the board flow completes so Whats91 automation can respond again.
Note
Sender selection accepts senderId or phoneNumberId. Global tokens can manage any sender owned by the customer; number-scoped tokens are restricted to their bound sender and otherwise return SENDER_NOT_ALLOWED.
Errors
| HTTP | error_code | Meaning |
|---|---|---|
| 400 | VALIDATION_FAILED | A required field is missing or invalid. |
| 400 | SENDER_REQUIRED | Neither senderId, phoneNumberId, nor a number-scoped token resolved the sender. |
| 401 | MISSING_AUTH_TOKEN | No public API token was supplied. |
| 401 | INVALID_AUTH_TOKEN | Token is invalid, expired, revoked, or not tied to an active customer. |
| 403 | SENDER_NOT_ALLOWED | A number-scoped token requested another sender. |
| 403 | INVALID_OWNER_TOKEN | The renew or release owner token does not match the active session. |
| 404 | SESSION_NOT_FOUND | The session UID does not belong to the authenticated customer. |
| 404 | KEYWORD_EXCLUSION_NOT_FOUND | The exclusion UID does not belong to the authenticated customer and sender. |
| 409 | SESSION_ALREADY_ACQUIRED | Another custom board currently owns the conversation session. |
| 409 | SESSION_NOT_ACTIVE | The session exists but has expired or was released. |
| 415 | UNSUPPORTED_CONTENT_TYPE | A JSON body endpoint was called without Content-Type: application/json. |
Related Documentation
List Keyword Exclusions
List sender-scoped keyword exclusions with status filtering.
Create Keyword Exclusion
Create a sender-scoped keyword exclusion that suppresses Whats91 internal automation.
Update Keyword Exclusion
Change the board, keyword, match mode, priority, or status of an existing exclusion.
Delete Keyword Exclusion
Remove a keyword exclusion from active matching.