Integration and API Spec

Integration and API Spec

Warranty and Guarantee Claim Handling

Used by Agent 1 (Claim Intake Agent) to monitor the designated claims inbox for new inbound emails and by Agent 3 (Resolution Confirmation Agent) to send outbound acknowledgement emails where Zendesk email is not used as the send channel.

// Input
Gmail API: GET /gmail/v1/users/me/messages?q=is:unread+label:warranty-claims
// Returns list of message IDs
Gmail API: GET /gmail/v1/users/me/messages/{id}?format=full
// Returns full RFC 2822 message with headers and body parts
// Output
Parsed object -> { from_email, subject, body_text, received_timestamp, attachments[] }
Passed to Agent 1 claim extraction step

Used by Agent 1 (Claim Intake Agent) to create structured tickets and by Agent 3 (Resolution Confirmation Agent) to post the final resolution reply and close the ticket.

// Input (ticket creation)
POST /api/v2/tickets
{ subject, comment: { body }, requester: { email, name },
  custom_fields: [ {id: FIELD_ID, value: ...}, ... ],
  tags: ['warranty-claim', 'auto-intake'] }
// Input (resolution reply and close)
PUT /api/v2/tickets/{ticket_id}
{ status: 'solved', comment: { body: resolution_text, public: true } }
// Output
ticket_id, ticket_url -> passed to downstream agents

Used by Agent 2 (Eligibility and Routing Agent) to retrieve the original order record for a claimant, confirming product SKU, purchase date, and order total.

// Input
GET /admin/api/2024-01/orders.json
  ?email={claimant_email}&status=any&limit=50
// Fallback input
GET /admin/api/2024-01/orders/{order_number}.json
// Output
order_id, order_number, created_at (purchase_date),
line_items[0].sku (product_sku),
line_items[0].price (unit_price),
total_price (order_total)
-> passed to Google Sheets eligibility check step

Used by Agent 2 (Eligibility and Routing Agent) for two operations: read from the warranty rules reference sheet to check eligibility, and write a new or updated row to the claims tracker sheet.

// Input (rules read)
GET spreadsheets/{SHEETS_WARRANTY_RULES_ID}/values/{SHEETS_RULES_RANGE}
// Filter rows where column A matches product_sku from Shopify
// Output (rules read)
warranty_period_days, max_refund_value, escalation_threshold_usd
// Input (tracker write)
POST spreadsheets/{SHEETS_CLAIM_TRACKER_ID}/values/{SHEETS_TRACKER_RANGE}:append
  valueInputOption=USER_ENTERED
  body: { values: [[ claim_id, zendesk_ticket_id, claimant_email, ... ]] }
// Output
updatedRange confirming row appended

Used by Agent 2 (Eligibility and Routing Agent) to send structured approval request messages to the approving manager for claims flagged as high-value or out-of-scope, and to receive the manager's interactive approve or reject callback.

// Outbound message input
POST https://slack.com/api/chat.postMessage
{ channel: SLACK_APPROVAL_CHANNEL_ID,
  blocks: [ header_block, fields_block, actions_block ],
  text: 'Warranty claim approval required: {claim_id}' }
// Inbound interaction payload (from manager button click)
POST {SLACK_INTERACTION_ENDPOINT}
payload: { type: 'block_actions', actions: [{ action_id: 'approve|reject',
  value: '{claim_id}:{zendesk_ticket_id}' }],
  user: { id, name } }
// Output
manager_decision (approve | reject), decided_by, decided_at
-> passed to Resolution Confirmation Agent

// Gmail
GOOGLE_SERVICE_ACCOUNT_JSON       = { ... full service account key JSON ... }
GMAIL_CLAIM_LABEL_ID              = 'Label_XXXXXXXXXXXXXXXXX'
GMAIL_SEND_AS_ADDRESS             = 'claims@[YourCompany.com]'

// Zendesk
ZENDESK_SUBDOMAIN                 = '[yourcompany]'
ZENDESK_ADMIN_EMAIL               = 'automation@[YourCompany.com]'
ZENDESK_API_TOKEN                 = 'ZENDESK_TOKEN_XXXXXXXXXXXXXX'
ZENDESK_AGENT_USER_ID             = '000000000000'
ZENDESK_WEBHOOK_SECRET            = 'WEBHOOK_HMAC_SECRET_XXXXXXXXX'
ZENDESK_FIELD_IDS                 = '{"warranty_claim_id":360001,"order_number":360002,"product_sku":360003,"purchase_date":360004,"claim_resolution_type":360005,"escalation_required":360006}'

// Shopify
SHOPIFY_STORE_DOMAIN              = '[yourcompany].myshopify.com'
SHOPIFY_API_KEY                   = 'SHOPIFY_KEY_XXXXXXXXXXXXXXXXX'
SHOPIFY_API_PASSWORD              = 'SHOPIFY_PWD_XXXXXXXXXXXXXXXXX'
SHOPIFY_API_VERSION               = '2024-01'

// Google Sheets
SHEETS_WARRANTY_RULES_ID          = '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms'
SHEETS_CLAIM_TRACKER_ID           = '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2uXXX'
SHEETS_RULES_RANGE                = 'WarrantyRules!A2:E'
SHEETS_TRACKER_RANGE              = 'ClaimsLog!A:M'

// Slack
SLACK_BOT_TOKEN                   = 'xoxb-XXXXXXXXXXXX-XXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXX'
SLACK_SIGNING_SECRET              = 'SLACK_SIGNING_SECRET_XXXXXXXXX'
SLACK_APPROVAL_CHANNEL_ID         = 'C0XXXXXXXXXX'
SLACK_INTERACTION_ENDPOINT        = 'https://hooks.[orchestration-platform]/slack/interact'
SLACK_TIMEOUT_HOURS               = '4'

// Internal
INTERNAL_EVENT_SECRET             = 'INTERNAL_HMAC_SECRET_XXXXXXXXX'
DEDUP_CACHE_TTL_SECONDS           = '86400'