> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lithoblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Inspect interactions and track clicks

> Read interaction outcomes, correlate modal receipts, and measure link-button clicks.

See [availability](/guides/availability) for production and staging endpoints.

## Observe the flow

`GET /v1/interactions` accepts `template_id`, `action_id`, `since`, `limit` and `offset`.
`GET /v1/interactions/{id}` returns the selected outcome. Results expose safe component type/status
and timestamps, delivery status, timing and retry metadata. They omit arbitrary component data,
webhook request/response bodies, URLs, error text and raw idempotency keys.

`GET /v1/modal-submissions` accepts `modal_definition_id`, `since`, `limit` and `offset`. Organization
access is checked through **both** the owning modal and interaction log. It returns submitted values,
which can themselves contain sensitive customer input, but excludes private metadata. List responses
use `data` and `pagination: { total, limit, offset }`; `since` is inclusive ISO 8601 with a timezone.

## Track link-button clicks

Enable **Track clicks only** beside the URL in the button editor, or set
`action_config.tracking_only: true`. The URL still opens in the user's browser. Slack sends an
interaction for URL buttons too; LithoBlocks acknowledges it and records the click without calling
another destination, opening a modal or updating the message. See the
[Slack button contract](https://docs.slack.dev/reference/block-kit/block-elements/button-element/).

```json theme={null}
{
  "type": "button",
  "text": { "type": "plain_text", "text": "Read release notes" },
  "action_id": "read_release_notes",
  "url": "https://example.com/releases/{{release_id}}",
  "action_config": { "tracking_only": true }
}
```

Place the button in an `actions` block or section accessory. It also works without a URL as a
simple acknowledgement. Tracking only cannot be combined with a webhook destination/route,
modal, or enabled message update. The editor requires those effects to be removed first.
Use a distinct action ID for each button you want to distinguish; the editor supplies one if missing.

Save the `channel` and `message_ts` returned by send, then query:

```http theme={null}
GET /v1/interactions?slack_channel_id=C123&slack_message_ts=1788880000.123456&action_id=read_release_notes
```

The same filters work in MCP `list_interactions` and the TypeScript SDK's existing interactions
list operation. Add `slack_team_id` to disambiguate Slack workspaces. The result contains who clicked,
when, the exact action ID and message coordinates, and a `click_tracking` component with `success`.
It uses existing `interactions:read` permissions and organization isolation. `pagination.total`
counts records matching the filters; paginate to collect records and deduplicate `slack_user_id`
locally if you want unique people. New clicks by the same person count again. `since` is inclusive;
when polling, overlap the time window and deduplicate by interaction `id`.

Slack retries with the same team, channel, message, user, action ID and exact action timestamp share
one stored record. Distinct clicks count separately, even in the same millisecond. No webhook
destination, webhook idempotency key, extra credit or background delivery worker is needed.
This records receipt of a click, not a page view, successful page load, read receipt, or conversion.
URL navigation can succeed even if tracking is unavailable; failed persistence is not acknowledged
as successful, and collection is not guaranteed during outages. There is no automatic alert subscription
or aggregate analytics endpoint currently. Receipt protection lasts while interaction history
is retained; deletion removes that protection. Buttons in messages sent before tracking was enabled
keep their original configuration—publish a version and send a new message to enable it.

Read [Modal submissions](/guides/modals-submissions) before interpreting a closed modal as successful delivery.