Chatwoot contacts and companies

Use these 31 capabilities to find and maintain contacts, notes, companies, and their relationships. Treat every result as restricted customer data, including reads that need no human approval.

The catalogue freezes capability IDs, provider methods, paths, and AIP policy contracts. It does not freeze provider-specific contact or company body fields.

Family at a glance

All 31 capabilities are Tools. The method split is 14 GET, ten POST, three PATCH, and four DELETE operations.

The 14 reads are low risk. Eleven mutations are medium risk. The contact.import and contact.export POST operations plus the four deletes are high risk.

Contact record and relationship operations

contact.filter is governed as a mutation because its provider method is POST. Use contact.list, contact.active, or contact.search when one of those read contracts satisfies the task.

contact.merge has no contact ID in its route. The provider body must identify the source and destination contacts. The AIP contract declares no rollback or compensating capability.

Contact-note operations

Notes can contain free-form customer or operational detail. The restricted, PII-present, redaction-required contract applies even when the provider does not label a field as sensitive.

Company and relationship operations

company.contact.delete removes a relationship through the frozen route. Its catalogue description does not claim that the contact record itself is deleted.

Account and path inputs

The connector inserts its configured account_id. Do not send an account ID in Action input.

Every path value must be a non-blank string of at most 512 bytes without control characters. Each value is encoded as one URL segment.

contact.merge, contact.import, contact.export, and contact.filter use account-level routes without a contact path ID. Their provider bodies own the selection or identity fields.

Generic provider input

Every operation accepts the common catalogue envelope:

The connector rejects body and multipart together. It does not validate contact names, identifiers, email addresses, phone numbers, company attributes, merge participants, import columns, or export filters.

Use the payload schema for the exact pinned provider route. Preserve one canonical body with the approval record; do not add or normalize customer data after approval.

Read one contact

Use an ID returned by the configured account route:

aipctl action call \
  "$AIP_URL" \
  cap:chatwoot:contact.get \
  --action-id act_chatwoot_contact_get_001 \
  --input '{"contact_id":"205"}'

The connector calls:

GET /api/v1/accounts/{configured_account_id}/contacts/205

This low-risk read advertises safe retry and needs no capability-level human approval. It still returns restricted PII. Limit the response to the actor and purpose authorized by tenant policy.

Govern consequential customer-data changes

The Rust catalogue does not publish a per-item transaction or partial-success model for import, export, or merge. A successful AIP response contains the provider result but does not add an atomic rollback guarantee.

Do not include a copy-ready import, export, or merge body from an unpinned API version. The generic Rust schema is not enough to establish those fields.

Shared mutation contract

All 17 mutations declare:

An idempotency key binds one canonical intent. It does not prove provider deduplication for imports, merges, creates, or relationship changes.

Result contract

Every successful catalogue call returns:

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

The connector parses JSON into body, returns null for an empty body, and wraps non-JSON bytes in a text object. It reads provider_request_id from x-request-id and then x-runtime.

The output schema does not freeze a contact, note, company, import, export, or merge result shape. Validate the fields the application requires and tolerate additional provider fields.

Failures and recovery

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

For an uncertain create, import, merge, relationship change, or note write, inspect authoritative provider state before any new Action. For an uncertain export, determine whether provider-side work or output already exists before initiating another disclosure.

For an uncertain delete, absence alone may not explain when or why the object disappeared. Correlate the original Action, provider request identity, audit evidence, and dependent objects.

Verify an integration

Require all of the following:

• discovery admits the exact capability for the configured account;
• path IDs and provider-body identities come from authoritative state;
• contact merge binds distinct reviewed source and destination identities;
• import and export approval records include bounded scope and artifact handling;
• every mutation has one retained idempotency key and exact input snapshot;
• the completed result belongs to the submitted Action;
• consequential changes are read back through the configured account;
• customer fields, notes, relationships, exports, and provider errors follow restricted-data redaction and retention policy;
• uncertain mutations are reconciled instead of repeated.

These checks validate application handling. They do not establish provider payload compatibility, live customer-data correctness, or qualification.

Related documentation

• Chatwoot capability index
• Conversations and messages
• Authentication and account isolation
• Approvals and policy
• Error reference