Chatwoot reports, audit, and events

Use these 12 read-only capabilities to inspect Chatwoot audit records, reporting events, and metrics for the configured account. Keep each provider observation separate from AIP’s own Action, approval, routing, Event, and outbox evidence.

Every operation uses GET. None changes provider state through its frozen route, but every result remains restricted and potentially contains PII.

Family at a glance

All 12 capabilities are Tools. They execute synchronously and advertise no async, streaming, or cancellation support.

Capability-level approval is not required. The authenticated actor, tenant, admitted connector route, credential revision, and data policy still govern access.

Keep evidence sources separate

Correlate sources through retained identities and timestamps when investigating an incident. Do not replace one evidence class with another because names such as audit or event appear in both products.

Version-one audit and event operations

reporting_event.list is account-scoped. The separate conversation.reporting_event.list capability reads one conversation’s enterprise reporting events through a conversation-qualified route.

Neither operation is the connector host’s webhook ingress or AIP Event API.

Version-two report operations

The v2 segment is part of each frozen provider path. It does not indicate AIP protocol version 2, a second connector profile, or a different capability-ID namespace.

Account and query inputs

The connector inserts its configured account_id into every route. This family has no other path placeholder.

Each operation accepts the generic optional query object:

The connector does not freeze date ranges, grouping dimensions, timezone, inbox, agent, team, channel, pagination, or other provider query names. Validate the query against the exact pinned Chatwoot route.

The generic schema also exposes body and multipart, but no operation in this family publishes a provider-specific request body. Do not add a body merely because the generic envelope permits one.

Read account audit records

This call demonstrates the source-owned route without assuming provider query fields:

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

The connector sends:

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

Chatwoot can still require provider state or query values not expressed by the generic connector schema. A completed result proves only that the selected provider request succeeded.

Shared read contract

All 12 capabilities declare:

Safe retry means another governed provider read is permitted after a suitable failure. It does not promise an identical metric snapshot; Chatwoot state and the query’s time window can change.

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 rows, metric names, units, dimensions, pagination, or aggregation behavior. Validate the result shape and metric semantics required by the application.

Failures and retry

Connector failures set retryable: false, so an error never directs a blind repeat. The capability contract separately marks these reads retry-safe.

Preserve the original query and observation time when retrying. A later successful response is a new provider observation, not proof of the missing response’s contents.

Handle reporting data

Apply restricted-data controls to:

• actor or customer identifiers in audit records;
• conversation, inbox, label, agent, team, and channel dimensions;
• row-level event detail;
• query strings and retained provider responses;
• exported evidence used for incident or performance analysis.

Redaction-required does not mean the connector redacts every provider field in this generic result. The application and evidence pipeline must enforce the tenant’s field, access, retention, and disclosure policy.

Verify an integration

Require all of the following:

• discovery admits the exact report or audit capability;
• the route version and account binding match the intended provider surface;
• query names and metric semantics come from the pinned Chatwoot API;
• the completed result belongs to the submitted Action;
• provider request identity and observation time are retained;
• retry results are treated as new snapshots;
• restricted audit, event, and metric data is redacted and retained under tenant policy;
• provider observations are correlated with, not substituted for, AIP execution evidence.

These checks validate observation handling. They do not establish metric accuracy, completeness of provider history, or live qualification.

Related documentation

• Chatwoot capability index
• Conversations and messages
• Actions and sessions
• Observe and recover
• Error reference