Integration and API Spec

Integration and API Spec

IT Helpdesk Request Handling

Primary ticketing system. Receives new ticket creation calls from Agent 1, assignment updates from Agent 2, and SLA-breach reads and status-change webhooks from Agent 3. All ticket operations use the Freshdesk REST API v2.

// Create ticket (POST)
POST /api/v2/tickets
{ "subject": "<parsed_subject>", "description": "<parsed_body>",
  "email": "<requester_email>", "priority": <1|2|3|4>,
  "status": 2, "group_id": FRESHDESK_GROUP_ID,
  "custom_fields": { "cf_category": "<category>", "cf_auto_triaged": true } }

// Read open tickets for load-balancing (GET)
GET /api/v2/tickets?filter=open&agent_id=<AGENT_ID>&per_page=100

// Update ticket assignment (PUT)
PUT /api/v2/tickets/{ticket_id}
{ "responder_id": <technician_agent_id> }

// Inbound webhook (ticket resolved) — payload excerpt
{ "ticket_id": 1042, "status": "resolved",
  "cf_category": "software", "resolution_notes": "...",
  "priority": 2, "requester_email": "user@example.com" }

Dual role: inbound intake channel via slash command (/it-request) and outbound notification channel for requester confirmation and technician alert messages. Uses the Slack Web API with a Bot OAuth token.

// Inbound slash command payload (POST from Slack)
{ "command": "/it-request", "text": "<user-typed request text>",
  "user_id": "U012AB3CD", "user_name": "jane.doe",
  "channel_id": "C04XXXXXXX", "response_url": "https://hooks.slack.com/..." }

// Outbound: notify requester (POST chat.postMessage)
{ "channel": "<requester_slack_user_id>",
  "blocks": [ { "type": "section", "text": { "type": "mrkdwn",
    "text": ":white_check_mark: Ticket #<id> logged. Priority: <P1-P4>. Assigned to: <name>." } } ] }

// Outbound: alert technician (POST chat.postMessage)
{ "channel": "<technician_slack_user_id>",
  "blocks": [ { "type": "section", "text": { "type": "mrkdwn",
    "text": ":bell: New ticket assigned: #<id> — <subject>. <freshdesk_ticket_url>" } } ] }

Handles two intake paths: monitored shared inbox (Gmail) and a structured Google Form. The automation platform polls the shared inbox and listens for new Google Form submissions. Parsed request content is passed to Agent 1 for triage.

// Gmail poll — parsed message structure passed to Agent 1
{ "source": "gmail", "message_id": "18d4f...",
  "from_email": "requester@example.com",
  "subject": "Can't access VPN",
  "body_text": "Since this morning I cannot connect to the VPN from home.",
  "received_at": "2025-01-22T09:14:00Z" }

// Google Form row — parsed structure passed to Agent 1
{ "source": "google_form", "row_index": 47,
  "requester_email": "requester@example.com",
  "request_type": "access", "description": "Need access to SharePoint site.",
  "urgency": "medium", "submitted_at": "2025-01-22T09:22:00Z" }

Receives SLA-breach trigger calls from Agent 3 when a P1 or P2 Freshdesk ticket has not been resolved within the defined SLA window. Fires an alert to the on-call IT manager via the configured escalation policy.

// Trigger SLA breach alert (POST Events API v2)
POST https://events.pagerduty.com/v2/enqueue
{ "routing_key": "<PAGERDUTY_ROUTING_KEY>",
  "event_action": "trigger",
  "dedup_key": "freshdesk-ticket-<ticket_id>-sla-breach",
  "payload": {
    "summary": "SLA breach: Ticket #<ticket_id> — <subject>",
    "severity": "critical",
    "source": "Freshdesk",
    "custom_details": {
      "ticket_id": "<ticket_id>",
      "priority": "P1",
      "elapsed_minutes": 75,
      "freshdesk_url": "https://<subdomain>.freshdesk.com/helpdesk/tickets/<ticket_id>"
    }
  }
}

Knowledge base write target. Agent 3 appends a structured page to a designated Notion database every time a Freshdesk ticket is marked resolved. Each page captures category, resolution summary, fix steps, and ticket metadata.

// Create KB page (POST Notion pages API)
POST https://api.notion.com/v1/pages
Authorization: Bearer <NOTION_INTEGRATION_TOKEN>
Notion-Version: 2022-06-28
{
  "parent": { "database_id": "<NOTION_KB_DATABASE_ID>" },
  "properties": {
    "Title":           { "title": [{ "text": { "content": "<subject>" } }] },
    "Category":        { "select": { "name": "<category>" } },
    "Priority":        { "select": { "name": "P<1-4>" } },
    "Ticket ID":       { "number": <ticket_id> },
    "Requester Email": { "email": "<requester_email>" },
    "Resolution Date": { "date": { "start": "<ISO8601_date>" } },
    "Fix Steps":       { "rich_text": [{ "text": { "content": "<fix_steps>" } }] },
    "Resolution Summary": { "rich_text": [{ "text": { "content": "<summary>" } }] }
  }
}

// Credential store contents — all keys namespaced by tool
// Values are secret; this block documents key names only

// Freshdesk
FRESHDESK_API_KEY           = "<api_key>"                  // Admin service account API key
FRESHDESK_SUBDOMAIN         = "yourcompany"                 // e.g. yourcompany.freshdesk.com
FRESHDESK_GROUP_ID          = "<integer>"                   // Round-robin assignment group ID
FRESHDESK_AGENT_IDS         = "[<id1>, <id2>, <id3>]"       // JSON array of technician agent IDs
FRESHDESK_WEBHOOK_SECRET    = "<hmac_secret>"               // For validating resolved-ticket webhook

// Slack
SLACK_BOT_TOKEN             = "xoxb-<...>"                  // Bot OAuth token
SLACK_SIGNING_SECRET        = "<signing_secret>"            // For validating slash command requests
SLACK_IT_ALERTS_CHANNEL_ID  = "C04XXXXXXX"                  // Channel for technician alerts
SLACK_MANAGER_USER_ID       = "U04XXXXXXX"                  // IT manager Slack user ID
SLACK_INTAKE_WEBHOOK_URL    = "https://..."                  // Public URL for /it-request slash command

// Google Workspace
GOOGLE_SERVICE_ACCOUNT_JSON = "{ ... }"                     // Full service account JSON key (escaped)
GOOGLE_SHARED_INBOX         = "it-support@[YourCompany.com]" // Delegated inbox address
GOOGLE_FORM_SHEET_ID        = "<spreadsheet_id>"            // Google Sheets ID for form responses
GOOGLE_PROCESSED_LABEL_ID   = "<label_id>"                  // Gmail label ID for processed emails

// PagerDuty
PAGERDUTY_API_KEY           = "<rest_api_key>"              // Full-access REST API key
PAGERDUTY_ROUTING_KEY       = "<events_api_v2_key>"         // Events API v2 integration routing key
PAGERDUTY_SERVICE_ID        = "<service_id>"                // IT Helpdesk SLA Alerts service ID
PAGERDUTY_ESCALATION_POLICY_ID = "<policy_id>"              // Escalation policy ID

// Notion
NOTION_INTEGRATION_TOKEN    = "secret_<...>"                // Internal integration Bearer token
NOTION_KB_DATABASE_ID       = "<32_char_database_id>"       // Target knowledge base database ID

// Orchestration platform state
STATE_FORM_LAST_ROW         = <integer>                      // Last processed Google Form row index
STATE_PD_DEDUP_KEYS         = "[<dedup_key>, ...]"           // PagerDuty dedup keys sent this window