Integration and API Spec

Integration and API Spec

FAQ & First Response Automation

Primary ticket source and reply destination. Triggers the entire workflow via webhook on new ticket creation. Also receives tag writes, priority assignments, routing actions, and outbound reply sends from Agents 1 and 2.

// Inbound webhook payload (new ticket)
{ "ticket_id": "string", "subject": "string", "description": "string",
  "requester_email": "string", "created_at": "ISO8601",
  "X-Zendesk-Webhook-Signature": "string" }

// Outbound API calls from automation
PUT /api/v2/tickets/{ticket_id}
  body: { tags: [...], priority: "string", group_id: integer }

POST /api/v2/tickets/{ticket_id}/comments
  body: { body: "string", public: true }

Knowledge base queried by both the Ticket Classification Agent (to confirm FAQ coverage exists) and the First Response Drafting Agent (to retrieve article content for the reply). Integration uses an internal Notion integration token scoped to the FAQ database only.

// Query request
POST https://api.notion.com/v1/databases/{NOTION_FAQ_DB_ID}/query
Headers: { Authorization: Bearer {NOTION_API_TOKEN},
           Notion-Version: "2022-06-28" }
Body: { filter: { and: [
         { property: "Category", select: { equals: "faq" } },
         { property: "Keywords", rich_text: { contains: "{keyword}" } }
       ] } }

// Response (relevant fields)
{ results: [ { id: "page_id", properties: {
    Title: { title: [ { plain_text: "string" } ] },
    Article_Body: { rich_text: [ { plain_text: "string" } ] }
  } } ] }

Customer contact lookup and activity note creation performed by the Escalation and Logging Agent after every ticket reply or human handoff. Contact is matched by requester email. A new contact is created if no match is found.

// Contact lookup
POST https://api.hubapi.com/crm/v3/objects/contacts/search
Body: { filterGroups: [ { filters: [ {
  propertyName: "email", operator: "EQ",
  value: "{requester_email}" } ] } ],
  properties: ["hs_object_id", "firstname", "lastname", "email"] }

// Note creation
POST https://api.hubapi.com/crm/v3/objects/notes
Body: { properties: {
  hs_note_body: "string",
  hs_timestamp: "ISO8601" },
  associations: [ { to: { id: "{contact_id}" },
    types: [ { associationCategory: "HUBSPOT_DEFINED",
               associationTypeId: 202 } ] } ] }

Receives structured escalation alert messages posted by the Escalation and Logging Agent for any ticket classified as urgent or escalation. Uses a Bot Token posted to a named channel. No inbound messages are read.

// chat.postMessage call
POST https://slack.com/api/chat.postMessage
Headers: { Authorization: Bearer {SLACK_BOT_TOKEN} }
Body: { channel: "{SLACK_ESCALATION_CHANNEL_ID}",
  blocks: [
    { type: "section", text: { type: "mrkdwn",
      text: ":rotating_light: *Escalation: Ticket #{ticket_id}*" } },
    { type: "section", fields: [
      { type: "mrkdwn", text: "*Category:* {category}" },
      { type: "mrkdwn", text: "*Confidence:* {confidence_score}" },
      { type: "mrkdwn", text: "*Requester:* {requester_email}" },
      { type: "mrkdwn", text: "*Link:* {zendesk_ticket_url}" } ] },
    { type: "section", text: { type: "mrkdwn",
      text: "Assigned to <@{SLACK_ONCALL_MEMBER_ID}>" } }
  ] }

Fallback send channel used by the First Response Drafting Agent when the Zendesk reply API returns a non-recoverable error after retries. Sends the drafted reply directly from the support Gmail address to the requester email.

// Gmail send (fallback)
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
Headers: { Authorization: Bearer {access_token} }
Body: { raw: "{base64url_encoded_RFC2822_message}" }

// RFC 2822 message structure (pre-encoding)
From: {GMAIL_FROM_ADDRESS}
To: {requester_email}
Subject: Re: {original_ticket_subject}
Reply-To: {GMAIL_FROM_ADDRESS}
Content-Type: text/plain; charset=UTF-8

{drafted_reply_body}

# Zendesk
ZENDESK_SUBDOMAIN=string              # e.g. yourcompany
ZENDESK_OAUTH_CLIENT_ID=string
ZENDESK_OAUTH_CLIENT_SECRET=string
ZENDESK_OAUTH_REFRESH_TOKEN=string
ZENDESK_WEBHOOK_SECRET=string         # HMAC-SHA256 shared secret for signature validation
ZENDESK_GROUP_ID_FAQ=integer          # Zendesk group ID for FAQ auto-resolved queue
ZENDESK_GROUP_ID_HUMAN=integer        # Zendesk group ID for low-confidence human queue
ZENDESK_GROUP_ID_ESCALATION=integer   # Zendesk group ID for escalation queue

# Notion
NOTION_API_TOKEN=string               # Internal integration token
NOTION_FAQ_DB_ID=string               # 32-char Notion database ID

# HubSpot
HUBSPOT_PRIVATE_APP_TOKEN=string
HUBSPOT_PORTAL_ID=integer

# Slack
SLACK_BOT_TOKEN=string                # xoxb- prefixed Bot User OAuth Token
SLACK_ESCALATION_CHANNEL_ID=string    # C-prefixed channel ID (not channel name)
SLACK_ONCALL_MEMBER_ID=string         # U-prefixed Slack member ID for @mention
SLACK_ALERTS_CHANNEL_ID=string        # Separate channel for automation error alerts

# Gmail (fallback)
GMAIL_CLIENT_ID=string
GMAIL_CLIENT_SECRET=string
GMAIL_REFRESH_TOKEN=string
GMAIL_FROM_ADDRESS=string             # e.g. support@yourcompany.com

# Orchestration
AUTO_REPLY_THRESHOLD=0.82             # Decimal 0-1; classification confidence floor
ENVIRONMENT=production                # or sandbox