Update WhatsApp sending settings

Before you start

• Production is the default. Use development or staging only when explicitly scoped, and keep the same authorized organization throughout. Reading this guide performs no action.
• Discover the current published action and validate/plan exact input before any later execution. Confirm the actual mutation and its provider/audit effects.
• Required published permission: app_topolo_engage.workspace:write.
• Resolve an accessible canonical Engage workspace using the current credential. Retain workspace context separately from action input; a settings response contains no workspace identifier and a fixture ID grants no access.

Effects and limits

• Stores the workspace fallback connectionId and records a workspace audit entry with the actor and time. Each repeated update creates another audit entry even when the stored connectionId is unchanged.
• connectionId is required. Supply a discovered connection ID to select it, or explicit null to clear the override and use the organization default. An empty object or blank string is refused.
• This action stores an identifier only. It does not contact Nexus to prove that the connection exists, belongs to the organization, is authorized or can deliver messages.
• A seat’s own WhatsApp connection takes precedence over the workspace fallback. Sending also requires the recipient’s current phone opt-in and an approved template.
• No WhatsApp message, template submission, credential or external connection provisioning is performed by this update.
• The reference is saved before the audit append; a later audit failure can leave the new reference persisted. A failed/lost response is not proof no change happened.

Request

PUT /api/sending-settings/whatsapp

Inputs below are source-derived synthetic examples, not approval to execute. Discover resource context separately.

Input fields

Worked examples

Every request/response below is synthetic and unrun, authored from reviewed source and retained published schemas. It is not a captured local or production response. Fixture identities and timestamps authorize nothing.

Replace the complete reviewed settings

SOURCE-DERIVED SYNTHETIC UNRUN example. This is authored illustration, not a captured response, live authorization, provider result or test pass.

Request:

{
  "connectionId": "conn_whatsapp_fixture"
}

Response illustration:

{
  "whatsapp": {
    "connectionId": "conn_whatsapp_fixture",
    "updatedAt": "2026-10-20T00:00:00.000Z",
    "updatedBy": "user_example_not_live"
  }
}

Read the retained fallback reference, actor and time. Repeats append audit entries; this response does not verify a Nexus connection or send WhatsApp.

Repeat after reconciling the retained row

SOURCE-DERIVED SYNTHETIC UNRUN example. This is authored illustration, not a captured response, live authorization, provider result or test pass.

Request:

{
  "connectionId": "conn_whatsapp_fixture"
}

Response illustration:

{
  "whatsapp": {
    "connectionId": "conn_whatsapp_fixture",
    "updatedAt": "2026-10-20T00:01:00.000Z",
    "updatedBy": "user_example_not_live"
  }
}

Read the retained fallback reference, actor and time. Repeats append audit entries; this response does not verify a Nexus connection or send WhatsApp.

Clear nullable settings

SOURCE-DERIVED SYNTHETIC UNRUN example. This is authored illustration, not a captured response, live authorization, provider result or test pass.

Request:

{
  "connectionId": null
}

Response illustration:

{
  "whatsapp": {
    "connectionId": null,
    "updatedAt": "2026-10-20T00:00:00.000Z",
    "updatedBy": "user_example_not_live"
  }
}

Read the retained fallback reference, actor and time. Repeats append audit entries; this response does not verify a Nexus connection or send WhatsApp.

Restore separately reviewed previous values

SOURCE-DERIVED SYNTHETIC UNRUN example. This is authored illustration, not a captured response, live authorization, provider result or test pass.

Request:

{
  "connectionId": "conn_whatsapp_fixture"
}

Response illustration:

{
  "whatsapp": {
    "connectionId": "conn_whatsapp_fixture",
    "updatedAt": "2026-10-20T00:00:00.000Z",
    "updatedBy": "user_example_not_live"
  }
}

Read the retained fallback reference, actor and time. Repeats append audit entries; this response does not verify a Nexus connection or send WhatsApp.

Verify the result

• Read sending.whatsapp.get in the same workspace and compare connectionId, updatedBy and updatedAt.
• Verify the selected connection separately through the current authorized Nexus read contract. A successful settings response does not prove live access or delivery.

Errors and recovery

• 422 invalid_action_input: Correct the full input using the published schema. HH:MM clocks and explicit nullable fields are required where declared. Validate the corrected request before planning it.
• 403 permission_denied: Stop. The current credential lacks workspace:write for Engage. Do not switch context or broaden permission automatically.
• 403 organization_required: Stop and establish the intended authorized organization context. Never add an organization ID to the action input to bypass this refusal.
• 409 workspace_required: Discover an accessible canonical Engage workspace through the current credential. A fixture workspace ID grants no access and a body field cannot provision a workspace.

After a lost response, read sending.whatsapp.get before retrying; repeated writes add audit entries. To restore the previously retained reference, validate and plan this same action with the previous connectionId, including explicit null if it was cleared, then read back. This changes future fallback selection and does not undo external sends.

Evidence and change log

• 2026-10-20: Prepared this paired guide from source 767d2d83713809e984559eee562a2c9f7ffcfa4d and the retained production contract snapshot. The source/content review is recorded separately. These examples remain synthetic and unrun; no original response capture or current business-runtime behavior is claimed.
• 2026-10-20: First production publication verified after independent source/content review. Removed duplicate introduction and authoring-only status notes; clarified field constraints. Examples remain synthetic and unrun.