Chatwoot labels, attributes, and filters

Use these 15 capabilities to manage account-level labels, custom-attribute definitions, and saved custom filters. Choose a definition operation only when the task is to maintain the reusable metadata object itself.

Applying a label, writing an attribute value, and filtering records use other capabilities. Similar names do not make their approvals or inputs interchangeable.

Family at a glance

All 15 capabilities are Tools. The method split is six GET, three POST, three PATCH, and three DELETE operations.

The six reads are low risk. The six create and update operations are medium risk. The three deletes are high risk.

Choose definition or use

contact.filter and conversation.filter use POST and are governed mutations in the frozen catalogue. custom_filter.get is a low-risk read of a saved definition; it does not execute that definition.

Label operations

The source does not define what deleting a label does to existing assignments, filters, automation, or reports. Inspect provider dependencies before approval and verify the resulting account state.

Custom-attribute-definition operations

The generic input schema does not validate provider field type, model scope, display rules, permitted values, or migration behavior. Those fields remain owned by the pinned Chatwoot route.

Deleting or changing a definition has no AIP compensating operation. Review current values and dependent behavior before the mutation.

Saved-custom-filter operations

The catalogue does not say that a saved filter is private, shared, executable, or bound to a particular record type. Interpret those provider fields from the pinned API response rather than the capability name.

Account and path inputs

The host inserts the configured account_id. It is not an Action input.

Each ID is a non-blank string of at most 512 bytes without control characters. The connector inserts it as one encoded URL segment.

List and create operations use account-level collection routes. Create fields belong in the provider body, not in a caller-constructed path.

Generic provider input

Every operation accepts the common catalogue envelope:

The connector rejects body and multipart together. It does not validate the provider fields of any label, attribute definition, or saved filter.

Use the exact pinned provider schema and preserve one canonical body with approval evidence. A generic schema-valid empty body is not proof of a valid create or update.

Read one custom-attribute definition

Use an ID returned by the configured account:

aipctl action call \
  "$AIP_URL" \
  cap:chatwoot:custom_attribute.get \
  --action-id act_chatwoot_custom_attribute_get_001 \
  --input '{"custom_attribute_id":"12"}'

The connector sends:

GET /api/v1/accounts/{configured_account_id}/custom_attribute_definitions/12

The read needs no capability-level approval and advertises safe retry. The result is still classified as restricted and PII-present by the capability contract.

Review a metadata mutation

Before create or update:

1. Read the current definition when it exists.
2. Confirm the exact pinned provider fields and intended account.
3. Identify records, workflows, reports, or users that can depend on it.
4. Retain one canonical body with the approval record.
5. Assign one external-account-scoped idempotency key.
6. Dispatch once and read the resulting definition.

Before delete, additionally preserve the current object and review provider dependencies. The AIP contract publishes no cascade semantics, rollback, or compensating capability.

Shared mutation contract

All nine mutations declare:

The connector forwards the idempotency key to Chatwoot. The contract does not prove provider deduplication or prevent dependency changes after approval.

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 uses x-request-id first and x-runtime second.

The output schema does not freeze provider definition fields. Validate the shape the application needs and preserve unknown fields.

Failures and recovery

All connector failures set retryable: false. The six read contracts separately advertise safe retry.

For an uncertain create, update, or delete, list or read definitions before another Action. Do not recreate a definition with a new ID merely because the first response was lost.

Verify an integration

Require all of the following:

• discovery admits the exact definition capability;
• the chosen surface matches definition management rather than record use;
• each path ID belongs to the configured account;
• provider body fields match the pinned route;
• approval includes dependency and impact review;
• each mutation retains one Action, canonical input, and idempotency key;
• a read confirms the intended definition after completion;
• restricted metadata follows redaction and retention policy;
• uncertain mutations are reconciled instead of repeated.

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

Related documentation

• Chatwoot capability index
• Conversations and messages
• Contacts and companies
• Approvals and policy
• Error reference