Integration and API Spec

Integration and API Spec

Support Reporting and Insights

Queried by the Data Fetch Agent (Agent 1) on a scheduled basis to retrieve all tickets in the configured reporting window. No webhook is used; the agent polls the REST API on the automation schedule.

// Input
schedule_trigger: { cadence: 'daily' | 'weekly' | 'monthly', period_start: ISO8601, period_end: ISO8601 }
// Output
ticket_records: [ { ticket_id, created_at, resolved_at, first_response_at, status, assignee_id, tags, category, csat_score, sla_breached } ]

Used by both the Data Fetch Agent (Agent 1) and the Reporting Agent (Agent 2). Agent 1 writes raw ticket records to a dedicated raw_data tab. Agent 2 reads that tab and writes calculated metric outputs to a metrics_summary tab.

// Input (Agent 1 write)
ticket_records[]: array of ticket objects from Zendesk
target_tab: GSHEETS_RAW_TAB_NAME
// Output (Agent 1 write)
write_confirmation: { rows_written: integer, tab: string, timestamp: ISO8601 }
// Input (Agent 2 read)
source_tab: GSHEETS_RAW_TAB_NAME
// Output (Agent 2 write)
metrics_written: { tab: GSHEETS_METRICS_TAB_NAME, rows_updated: integer, period_label: string }

Used by the Reporting Agent (Agent 2) as the live visual dashboard layer. Looker Studio connects directly to the Google Sheets metrics_summary and raw_data tabs as its data source. The automation does not call the Looker Studio API directly; the dashboard refreshes automatically when the underlying Sheet is updated.

// Input
Google Sheets: metrics_summary tab (auto-polled by Looker Studio)
// Output
LOOKER_STUDIO_REPORT_URL: shareable link passed to Agent 3 payload

Used by the Distribution Agent (Agent 3) to send the formatted report email to the manager distribution list after the Reporting Agent confirms the summary and commentary are ready.

// Input
agent_3_payload: { period_label, summary_commentary, csat_score, ticket_volume, sla_breach_count, looker_studio_url }
// Output
gmail_send_result: { message_id: string, thread_id: string, status: 'sent' | 'error' }

Used by the Distribution Agent (Agent 3) to post a formatted headline summary to the designated support Slack channel immediately after the Gmail send step completes.

// Input
agent_3_payload: { period_label, csat_score, ticket_volume, sla_breach_count, first_response_time_avg, looker_studio_url }
// Output
slack_post_result: { ok: boolean, ts: string, channel: string } | { ok: false, error: string }

Used by the Distribution Agent (Agent 3) to append a new row to the team's persistent reporting log database in Notion. Each entry records the report date, period covered, headline metrics, and a link to the live dashboard.

// Input
agent_3_payload: { report_date: ISO8601, period_label: string, cadence: 'daily'|'weekly'|'monthly', csat_score: number, ticket_volume: integer, sla_breach_count: integer, first_response_avg: string, looker_studio_url: string }
// Output
notion_create_result: { object: 'page', id: string, url: string } | { status: 400|401|404, message: string }

// Credential store — all keys required before first run

// Zendesk (Agent 1)
ZENDESK_SUBDOMAIN            = 'yourcompany'          // no .zendesk.com suffix
ZENDESK_AGENT_EMAIL          = 'automation@yourcompany.com'
ZENDESK_API_TOKEN            = '<generated in Zendesk Admin>'

// Google Sheets (Agents 1 and 2)
GSHEETS_SERVICE_ACCOUNT_JSON = '<full JSON key object for service account>'
GSHEETS_SPREADSHEET_ID       = '<26-char Google Sheets ID from URL>'
GSHEETS_RAW_TAB_NAME         = 'raw_data'
GSHEETS_METRICS_TAB_NAME     = 'metrics_summary'

// Looker Studio (Agent 2 output, Agent 3 input)
LOOKER_STUDIO_REPORT_URL     = 'https://lookerstudio.google.com/reporting/<report-id>'

// Gmail (Agent 3)
GMAIL_CLIENT_ID              = '<OAuth 2.0 client ID from Google Cloud Console>'
GMAIL_CLIENT_SECRET          = '<OAuth 2.0 client secret>'
GMAIL_OAUTH_REFRESH_TOKEN    = '<long-lived refresh token from OAuth flow>'
GMAIL_SENDER_ADDRESS         = 'reports@yourcompany.com'
GMAIL_DISTRIBUTION_LIST      = 'manager1@yourcompany.com,manager2@yourcompany.com'
GMAIL_SUBJECT_TEMPLATE       = 'Support Report: {{period_label}}'
GMAIL_BODY_TEMPLATE_ID       = 'email_template_v1'   // references template in orchestration layer

// Slack (Agent 3)
SLACK_BOT_TOKEN              = 'xoxb-<workspace-bot-token>'
SLACK_CHANNEL_ID             = 'C0XXXXXXXXX'          // channel ID, not name

// Notion (Agent 3)
NOTION_INTEGRATION_TOKEN     = 'secret_<integration-token>'
NOTION_DATABASE_ID           = '<UUID of reporting log database>'