Chatwoot customer portals

Use these five capabilities to list and create help-center portals, update a portal, and create categories or articles inside a portal. The reviewed surface is intentionally smaller than full portal CRUD.

Portal content can become customer-visible. Review the provider body, intended audience, and publication behavior before approving a mutation.

Family at a glance

All five capabilities are Tools. portal.list is a low-risk GET. The three POST operations and one PATCH operation are medium-risk mutations.

Every mutation requires approval and an idempotency key. None advertises connector retry support or compensation.

Operations

The provider path and operation description use help-center portal semantics. These capabilities do not manage the AIP documentation site or connector-host HTTP routes.

Supported and absent operations

Do not synthesize an absent capability ID or call an arbitrary provider route. Admission applies only to the five exact suffixes above.

The missing delete surface also limits recovery. A corrective provider operation outside this catalogue is not an AIP compensating capability and requires a separate authorized path.

Account and path inputs

The connector inserts its configured account_id into every route. It is not an Action input.

portal_id is required by:

• portal.update;
• portal.category.create;
• portal.article.create.

The value must be a non-blank string of at most 512 bytes without control characters. The connector inserts it as one encoded path segment.

portal.list and portal.create use the account collection route. Category and article identities belong to provider responses or bodies, not to an invented path placeholder.

Generic provider input

Every operation accepts the common catalogue envelope:

The connector rejects body and multipart together. It does not validate portal names, domains, locales, visibility, category structure, article content, publication state, or other provider fields.

Use the exact pinned provider schema. Retain one canonical body with the approval record; do not edit customer-visible content after approval.

List portals

This read needs no provider-specific path or body input:

aipctl action call \
  "$AIP_URL" \
  cap:chatwoot:portal.list \
  --action-id act_chatwoot_portal_list_001 \
  --input '{}'

The connector sends:

GET /api/v1/accounts/{configured_account_id}/portals

The read needs no capability-level approval and advertises safe retry. Its provider body remains restricted and PII-present under the common contract.

The list result is the only portal read in this family. Confirm that its provider shape contains the fields required for review before relying on it as an authoritative snapshot.

Review a portal mutation

The source does not state whether a created object becomes visible immediately. Treat publication behavior as provider-owned and verify it through the pinned Chatwoot surface.

Do not approve a guessed body. The generic schema proves only that the body is a bounded JSON object.

Shared mutation contract

All four mutations declare:

The connector forwards the idempotency key to Chatwoot. The contract does not prove provider deduplication or content-level rollback.

Result contract

Every successful operation returns:

{
  "http_status": 200,
  "body": {},
  "provider_request_id": null
}

body contains parsed JSON, null for an empty response, or a text wrapper for non-JSON bytes. provider_request_id reads x-request-id first and x-runtime second.

The output schema does not freeze a portal, category, or article shape. Validate required provider fields and preserve unknown fields.

Failures and recovery

All connector failures set retryable: false. Only portal.list advertises safe retry.

For an uncertain create, list portals and inspect the original provider result evidence before another Action. Duplicate portal, category, or article creation cannot be repaired through a delete capability in this catalogue.

For an uncertain update, compare the target in the list when its shape permits. A corrective update needs new approval against current provider state.

Verify an integration

Require all of the following:

• discovery admits one of the five exact portal capabilities;
• the task does not depend on an absent get, update, or delete surface;
• portal_id belongs to the configured account;
• provider body fields and publication behavior come from the pinned API;
• approval binds the exact customer-visible content and intended audience;
• each mutation retains one Action, canonical input, and idempotency key;
• available provider state confirms the completed change;
• portal content and results follow restricted-data policy;
• uncertain mutations are reconciled instead of repeated.

These checks validate application handling. They do not establish publication state, provider payload compatibility, or live qualification.

Related documentation

• Chatwoot capability index
• Automation, macros, and canned responses
• Chatwoot connector configuration
• Approvals and policy
• Error reference