Integration and API Spec

Integration and API Spec

Complaint Escalation Workflow

Zendesk is the primary ticketing system. It receives the initial complaint, stores triage output as ticket fields, manages assignment, tracks SLA deadlines, and records priority escalations. Both agents read from and write to Zendesk.

// Inbound payload (Zendesk webhook on ticket creation)
{
  "ticket_id": "<integer>",
  "subject": "<string>",
  "description": "<string>",
  "requester_email": "<string>",
  "requester_name": "<string>",
  "channel": "email | web_form",
  "created_at": "<ISO8601 timestamp>"
}

// Outbound (PATCH /api/v2/tickets/{ticket_id}.json)
{
  "ticket": {
    "custom_fields": [
      { "id": "{{ZENDESK_CF_SEVERITY_ID}}", "value": "low|medium|high" },
      { "id": "{{ZENDESK_CF_CATEGORY_ID}}", "value": "<category string>" },
      { "id": "{{ZENDESK_CF_HS_CONTACT_ID}}", "value": "<hs_contact_id>" },
      { "id": "{{ZENDESK_CF_HS_LTV_ID}}", "value": "<lifetime_value>" }
    ],
    "group_id": "{{ZENDESK_GROUP_<SEVERITY>_ID}}",
    "assignee_id": "<agent_user_id>",
    "priority": "low|normal|high|urgent"
  }
}

HubSpot supplies customer context to the Complaint Triage Agent. The automation performs a contact lookup by email and retrieves purchase history, lifetime value, and prior support interaction count. Results are written back to the Zendesk ticket as custom field values.

// Outbound request (contact search by email)
POST https://api.hubapi.com/crm/v3/objects/contacts/search
Authorization: Bearer {{HUBSPOT_PRIVATE_APP_TOKEN}}
{
  "filterGroups": [{
    "filters": [{ "propertyName": "email", "operator": "EQ", "value": "{{requester_email}}" }]
  }],
  "properties": ["firstname", "lastname", "email", "lifecyclestage",
                   "prior_complaint_count", "customer_tier", "hs_object_id",
                   "total_revenue"]
}

// Inbound response (trimmed)
{
  "results": [{
    "id": "<hs_contact_id>",
    "properties": {
      "firstname": "<string>",
      "lastname": "<string>",
      "email": "<string>",
      "customer_tier": "standard|premium|enterprise",
      "prior_complaint_count": "<integer string>",
      "total_revenue": "<decimal string>"
    }
  }]
}

Slack carries three distinct notification types: an agent assignment alert (all severities), a manager high-severity alert (high severity only), and an overdue escalation alert (triggered when a ticket breaches its SLA deadline). Each notification type posts to a dedicated channel.

// Outbound (agent assignment alert)
POST https://slack.com/api/chat.postMessage
Authorization: Bearer {{SLACK_BOT_TOKEN}}
{
  "channel": "{{SLACK_CHANNEL_AGENT_ALERTS}}",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn",
      "text": "*New complaint assigned* | Severity: {{severity}} | <{{ticket_url}}|View ticket>" }
    }
  ]
}

// Outbound (overdue escalation alert)
{
  "channel": "{{SLACK_CHANNEL_ESCALATIONS}}",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn",
      "text": ":rotating_light: *Overdue complaint* | Ticket #{{ticket_id}} | Assigned: {{assignee_name}} | <{{ticket_url}}|View ticket>" }
    }
  ]
}

Gmail sends the outbound customer acknowledgement email. The email is personalised with the customer's name, the assigned agent's name, and the expected response time based on the severity tier. A separate template is maintained for each of the three severity levels.

// Outbound (send acknowledgement via Gmail API)
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
Authorization: Bearer {{access_token_refreshed}}
{
  "raw": "<base64url-encoded RFC 2822 message>",
  // Decoded headers:
  // From: {{GMAIL_FROM_ADDRESS}}
  // To: {{requester_email}}
  // Subject: Re: Your complaint has been received [Ticket #{{ticket_id}}]
  // Content-Type: text/html; charset=UTF-8
  // Body: rendered from GMAIL_TEMPLATE_{{SEVERITY}}
  //   with {{customer_first_name}}, {{ticket_id}},
  //       {{assigned_agent_name}}, {{expected_response_time}} substituted
}

Notion stores the resolution log and knowledge base. When a Zendesk ticket is closed, the Escalation and Routing Agent appends a structured row to the resolution log database in Notion. This replaces the manual summary sometimes added to a shared page.

// Outbound (create resolution log page)
POST https://api.notion.com/v1/pages
Authorization: Bearer {{NOTION_INTEGRATION_TOKEN}}
Notion-Version: 2022-06-28
{
  "parent": { "database_id": "{{NOTION_RESOLUTION_DB_ID}}" },
  "properties": {
    "Ticket ID":        { "title": [{ "text": { "content": "{{ticket_id}}" } }] },
    "Customer Email":   { "email": "{{requester_email}}" },
    "Severity":         { "select": { "name": "{{severity}}" } },
    "Category":         { "rich_text": [{ "text": { "content": "{{complaint_category}}" } }] },
    "Resolution Summary":{ "rich_text": [{ "text": { "content": "{{resolution_notes}}" } }] },
    "Resolved At":      { "date": { "start": "{{resolved_at_iso8601}}" } },
    "Assigned Agent":   { "rich_text": [{ "text": { "content": "{{assigned_agent_name}}" } }] }
  }
}

# Zendesk
ZENDESK_SUBDOMAIN            = <your-subdomain>           # e.g. acme (not acme.zendesk.com)
ZENDESK_API_TOKEN            = <api_token_string>
ZENDESK_WEBHOOK_SECRET       = <hmac_secret_string>       # from Zendesk webhook config
ZENDESK_CF_SEVERITY_ID       = <integer>                  # custom field ID for cf_severity_score
ZENDESK_CF_CATEGORY_ID       = <integer>                  # custom field ID for cf_complaint_category
ZENDESK_CF_HS_CONTACT_ID     = <integer>                  # custom field ID for HubSpot contact ID
ZENDESK_CF_HS_LTV_ID         = <integer>                  # custom field ID for HubSpot lifetime value
ZENDESK_GROUP_LOW_ID         = <integer>                  # group ID for low-severity routing
ZENDESK_GROUP_MED_ID         = <integer>                  # group ID for medium-severity routing
ZENDESK_GROUP_HIGH_ID        = <integer>                  # group ID for high-severity routing

# HubSpot
HUBSPOT_PRIVATE_APP_TOKEN    = pat-<token_string>
HUBSPOT_API_BASE_URL         = https://api.hubapi.com
HUBSPOT_PROP_COMPLAINT_COUNT = prior_complaint_count      # internal property name
HUBSPOT_PROP_CUSTOMER_TIER   = customer_tier              # internal property name

# Slack
SLACK_BOT_TOKEN              = xoxb-<token_string>
SLACK_CHANNEL_AGENT_ALERTS   = <channel_id>              # C0XXXXXXXXX format
SLACK_CHANNEL_MANAGER_ALERTS = <channel_id>
SLACK_CHANNEL_ESCALATIONS    = <channel_id>
SLACK_SLA_LOW_MINS           = 480                        # 8 hours
SLACK_SLA_MED_MINS           = 240                        # 4 hours
SLACK_SLA_HIGH_MINS          = 60                         # 1 hour
SLACK_MSG_AGENT_TEMPLATE     = <block_kit_json_string>
SLACK_MSG_MANAGER_TEMPLATE   = <block_kit_json_string>
SLACK_MSG_OVERDUE_TEMPLATE   = <block_kit_json_string>

# Gmail
GMAIL_CLIENT_ID              = <google_oauth_client_id>
GMAIL_CLIENT_SECRET          = <google_oauth_client_secret>
GMAIL_OAUTH_REFRESH_TOKEN    = <refresh_token_string>
GMAIL_FROM_ADDRESS           = support@[YourCompany.com]
GMAIL_TEMPLATE_LOW           = <html_template_string_or_notion_page_id>
GMAIL_TEMPLATE_MED           = <html_template_string_or_notion_page_id>
GMAIL_TEMPLATE_HIGH          = <html_template_string_or_notion_page_id>

# Notion
NOTION_INTEGRATION_TOKEN     = secret_<token_string>
NOTION_RESOLUTION_DB_ID      = <32_char_database_id>