--- name: talon-integration-engineer description: > Use this skill when a technical or integration engineer is debugging or auditing Talon.One at the API and configuration level. Triggers include: "check API access logs", "why is the integration failing", "session not showing up", "401 errors", "webhook configuration", "custom attributes", "application health", "API request failed", "debug the integration", "what roles do users have", "audit user permissions", "check webhook payload", "session was never created", "API returning errors", "integration ID mapping", "check ruleset logic", or any request involving raw HTTP logs, webhook setup, account-level configuration, roles, users, or custom attribute schemas. This persona digs into infrastructure rather than promotion outcomes. --- # Talon.One MCP Skill — Integration Engineer You are helping a **technical integration engineer** debug, audit, and understand Talon.One at the API and platform configuration level. This persona cares about HTTP-level failures, integration health, webhook configuration, custom attribute schemas, user roles, and session-level plumbing — not campaign analytics or customer-facing loyalty balances. --- ## Your Tool Palette (Integration Engineer) ### API Debugging | Tool | When to Use | |------|------------| | `get_applications` | **Always first** — resolve `applicationId` | | `get_application_health` | Is the application receiving integration traffic? Any recent errors? | | `get_access_logs` | Raw HTTP request/response log — find 4xx/5xx errors | | `list_application_events` | Find events by session, profile, coupon, effect type, or time range | | `list_application_sessions` | Find sessions by integration ID, profile, coupon, state, date | | `get_session_details` | Full session detail by session integration ID (string) | | `get_application_session` | Full session detail by internal numeric session ID | ### Configuration Audit | Tool | When to Use | |------|------------| | `list_webhooks` | List all webhooks configured for an application | | `get_webhook` | Full config of a specific webhook: URL, headers, payload template | | `list_custom_attributes` | List all custom attributes by entity type, name, data type | | `list_roles` | Audit all roles and their permission assignments | | `list_users` | Audit all account users: email, role, admin status | | `get_application` | Full application config: currency, timezone, cascading discounts, features | ### Campaign & Ruleset Inspection | Tool | When to Use | |------|------------| | `list_campaigns` | Find campaigns by name, state, tag | | `get_campaign` | Full campaign config including feature flags and budget counters | | `list_rulesets` | List all ruleset revisions for a campaign | | `get_ruleset` | Full rule definitions: conditions, effects, expression logic | | `list_application_event_types` | Discover valid custom event type names | ### Supporting | Tool | When to Use | |------|------------| | `list_loyalty_programs` | Resolve loyalty program IDs | | `get_loyalty_program` | Inspect program config: type (profile vs card), expiry rules | | `list_application_customers` | Look up customer `integrationId` / `customerId` mapping | | `get_customer_profile` | Confirm customer attributes as stored in Talon.One | **Do NOT use** (too customer-facing for this persona): - `get_loyalty_balances`, `get_loyalty_ledger`, `get_loyalty_profile_transactions`, `get_loyalty_card_transactions`, `get_customer_achievements`, `get_customer_achievement_history`, `list_coupons`, `list_referrals`, `list_giveaways`, `get_reserved_customers` --- ## Step 0 — Always Start With ID Resolution ``` 1. get_applications → applicationId (by name; never guess) 2. list_campaigns → campaignId (if debugging campaign-level issue) 3. list_loyalty_programs → loyaltyProgramId (if debugging loyalty) ``` --- ## Debugging Playbooks ### "The integration is failing — why?" **Step 1 — Check application health:** ``` get_application_health(applicationId) ``` Returns: `OK` / `WARNING` / `ERROR` / `CRITICAL` / `NONE` and timestamp of last request. `NONE` = no requests in the last 5 minutes (integration may be disconnected entirely). **Step 2 — Pull error logs:** ``` get_access_logs(applicationId, rangeStart="2026-06-01T00:00:00Z", rangeEnd="2026-06-01T23:59:59Z", status="error", → non-2xx responses only method="post", → narrow to POST requests pageSize=50 ) ``` **Step 3 — Look for patterns:** - `401 Unauthorized` → API key is wrong, missing, or using wrong auth format - `400 Bad Request` → malformed payload; read `requestBody` from the log entry - `404 Not Found` → wrong application ID in the request path - `409 Conflict` → session/profile already exists with conflicting state **Step 4 — Find the specific session:** ``` list_application_sessions(applicationId, integrationId="session-abc-123", → exact match on session integration ID createdAfter="2026-06-01T10:00:00Z", createdBefore="2026-06-01T11:00:00Z" ) ``` Then: `get_session_details(applicationId, customerSessionId="session-abc-123")` --- ### "A session is missing / never shows up" 1. `get_application_health(applicationId)` → confirm requests are reaching Talon.One at all 2. `get_access_logs(applicationId, rangeStart, rangeEnd, method="put", status="error")` → find the failed PUT 3. `list_application_sessions(applicationId, partialMatch=true, integrationId="partial-id")` → search with partial match 4. If session exists but looks wrong: `get_application_session(applicationId, sessionId)` → internal numeric ID view **Key distinction:** - `get_session_details(applicationId, customerSessionId)` → takes **string** `sessionIntegrationId` - `get_application_session(applicationId, sessionId)` → takes **numeric** internal `sessionId` - Get numeric session ID from `list_application_sessions` results --- ### "A rule isn't firing — is the expression correct?" 1. `list_campaigns(applicationId, name="Campaign Name")` → `campaignId` 2. `get_campaign(applicationId, campaignId)` → check `activeRulesetId` 3. `list_rulesets(applicationId, campaignId)` → identify the current active ruleset 4. `get_ruleset(applicationId, campaignId, rulesetId)` → read full rule definitions: - Conditions (what must be true for the effect to fire) - Effects (what happens when conditions are met) - Expression syntax (attribute references, operators) 5. Cross-check: `list_custom_attributes(entity="CustomerProfile")` → confirm the attribute name in the rule matches what's stored **Watch for:** - Custom attribute names are **case-sensitive** - Event type names must be **exact** — use `list_application_event_types(applicationId)` to verify - `filterByApplicationId` on `/v1/attributes` doesn't work as expected — filter client-side --- ### "A custom event type is wrong or missing" ``` list_application_event_types(applicationId) ``` Returns all event types registered for this application. If an expected event type is missing, the integration is sending events with a name that doesn't match what's registered in the ruleset. --- ### "Audit the webhook configuration" 1. `list_webhooks(applicationIds="5")` → all webhooks for an application - Filter `creationType="webhooks"` for manually created ones - Filter `title="Webhook Name"` to find a specific one 2. `get_webhook(webhookId)` → full config: - `url` → destination endpoint - `headers` → auth headers sent with each request - `payload` → Freemarker template defining the body --- ### "Audit user roles and permissions" 1. `list_roles` → all role definitions with their permission grants 2. `list_users` → all users with their role assignments and `isAdmin` status **Note:** Users with `isAdmin: true` have implicit full access regardless of role assignments. Cross-reference `list_users` and `list_roles` manually — no single join endpoint exists. --- ### "What custom attributes exist for profiles / sessions / campaigns?" ``` list_custom_attributes( entity="CustomerProfile", → CustomerProfile | CustomerSession | Campaign | CartItem | Coupon | Event kind="custom", → "builtin" | "custom" search="tier" → free-text search on name/description ) ``` **Important:** Custom attributes are account-level (not per-application). `applicationIds` filter does not reliably scope results — always filter client-side by attribute name pattern. --- ## Access Log Reference ``` get_access_logs( applicationId, → required rangeStart, → required, RFC3339 rangeEnd, → required, RFC3339 status="error", → "success" (2xx) | "error" (non-2xx) method="post", → get | put | post | delete | patch path="/v2/customer_sessions/.*", → regex pattern on request URI pageSize=50, skip=0 → paginate with skip + pageSize ) ``` **Pagination pattern:** ``` Page 1: skip=0, pageSize=50 Page 2: skip=50, pageSize=50 Page 3: skip=100, pageSize=50 ``` Filter aggressively before paginating — without `status` and `method` filters, logs can be thousands of entries per hour. --- ## Application Config Reference `get_application(applicationId)` → key fields for debugging: - `currency` → monetary values are in **cents** of this currency (EUR 50.00 = 5000) - `timezone` → all campaign schedules evaluate in this timezone - `cascadeActions` → whether effects chain across multiple campaigns - `key` → the Integration API key bound to this application - `features` → array of enabled feature flags (e.g., `"cartItems"`, `"achievements"`) --- ## Timestamp Format All date parameters require **RFC3339** format: ``` 2026-01-15T00:00:00Z → start of day UTC 2026-01-15T23:59:59Z → end of day UTC 2026-01-15T00:00:00+01:00 → with timezone offset ``` For `get_access_logs`, always set both `rangeStart` and `rangeEnd`. Narrow the window as much as possible before paginating — wide windows return enormous result sets.