> For the complete documentation index, see [llms.txt](https://docs.slatecx.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.slatecx.com/guides/advanced-card-context-bridge.md).

# Advanced: Card Context Bridge

Card Context Bridge is an advanced feature that allows a card withing a SlateCX desktop view to send structured results back to SlateCX, so the agent can use those results in the conversation. 

It’s designed for interactive tools that produce a summary and a small set of structured facts: graders, calculators, assessments, diagnostics, and intake forms.

The flow requires no tenant integration API key. When the feature is enabled on a card, SlateCX appends a short-lived token to the card URL at runtime, and that token is the authorization for the callback.

### How the flow works <a href="#how-the-flow-works" id="how-the-flow-works"></a>

1. A prospect opens the card. SlateCX loads the live web page and appends a short-lived `slatecx_token` to the URL.
2. The embedded application reads the token from the query string and keeps it for the callback request.
3. The application, or a backend acting on its behalf, sends a structured event payload to the callback endpoint.
4. SlateCX stores the event and exposes the submitted summary and facts to the agent as card-derived context, which the agent can reference on a subsequent turn.
5. Optionally, if the payload includes `nudge: true`, the platform may prompt the agent to proactively follow up, subject to cooldown rules.

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* The source card is a **live web page card** with Card Context Bridge enabled on its **Behavior** tab. The feature is not intended for static assets such as PDFs or images.
* The embedded page is hosted at a reachable URL.
* The web application can read the `slatecx_token` query parameter from the URL.
* The application or its backend can submit a POST request to the public callback endpoint.

### The callback endpoint <a href="#the-callback-endpoint" id="the-callback-endpoint"></a>

```
POST /v1/card-context/events
```

| Field          | Required | Description                                                                                   |
| -------------- | -------- | --------------------------------------------------------------------------------------------- |
| `slatecxToken` | Required | The token value taken from the `slatecx_token` URL parameter.                                 |
| `summary`      | Required | A plain-text summary of the result. Maximum 2,000 characters.                                 |
| `facts`        | Optional | An ordered array of up to 20 objects containing `label` and `value`.                          |
| `nudge`        | Optional | If `true`, SlateCX may prompt the agent to proactively follow up after the event is accepted. |

Example payload:

```
{
  "slatecxToken": "abc123...",
  "summary": "Website scored 34/100 for AI readability. Major issues: no structured data, missing meta descriptions, JavaScript-rendered content.",
  "facts": [
    { "label": "Overall Score", "value": "34/100" },
    { "label": "Structured Data", "value": "Missing" },
    { "label": "Meta Descriptions", "value": "2 of 12 pages" },
    { "label": "JS Rendering", "value": "Critical: content invisible to crawlers" }
  ],
  "nudge": true
}
```

### What the SlateCX agent can see <a href="#what-the-agent-can-see" id="what-the-agent-can-see"></a>

Once an event is accepted, the agent has access to the card title, the submitted summary, the submitted facts, and the timestamp of the event.

Not exposed to the agent: raw tokens, internal identifiers, admin-only settings, or hidden implementation details.

### Constraints and behavior <a href="#constraints-and-behavior" id="constraints-and-behavior"></a>

| Topic            | Behavior                                                                                                                                      |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Authentication   | No tenant integration API key is required. The callback uses the `slatecxToken` as the authorization mechanism.                               |
| Token lifetime   | Tokens expire after 24 hours by default. Runtime systems refresh before expiry where applicable.                                              |
| Payload size     | Requests larger than 16 KB are rejected.                                                                                                      |
| Duplicate events | The same summary and facts submitted again for the same card and session are treated idempotently. Changed content is treated as a new event. |
| Nudge cooldown   | Only one proactive nudge can fire per participant within a 60-second cooldown window. Events may still be stored during cooldown.             |
| Anonymous usage  | Anonymous or unsaved prospects are supported, because the token is session-scoped rather than contact-scoped.                                 |

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

| Symptom                                             | Likely cause                                                                                                                                                |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No `slatecx_token` appears in the card URL          | The card is not an eligible live web page card, or Card Context Bridge is not enabled on its Behavior tab.                                                  |
| The callback is rejected with an auth-related error | The token may be expired, invalid, mismatched to the current session, or generated before the feature was disabled.                                         |
| The agent doesn’t mention the submitted result      | The callback may not have succeeded, the payload may have been rejected, or the event may not yet have been incorporated into the next conversational turn. |
| A proactive follow-up did not occur                 | The payload may not have included `nudge: true`, or the participant is still within the 60-second nudge cooldown.                                           |
| The request fails validation                        | The summary or facts may exceed field limits, or the total payload may be larger than 16 KB.                                                                |

### Worked example <a href="#worked-example" id="worked-example"></a>

An institution embeds a website grader inside a source card. A prospect enters a school domain and receives a score. The grader posts a summary and several findings back to SlateCX using the runtime token. On the next conversational turn, the Slate agent responds with targeted guidance based on the reported score and findings. Because the grader includes `nudge: true`, the agent can proactively re-engage the prospect without waiting for another message.

The integration checklist: read `slatecx_token` from the URL, POST the result to `/v1/card-context/events` within the token’s lifetime, keep the payload under 16 KB, and include `nudge: true` only when a proactive follow-up is genuinely wanted.