API Reference

{
  "name": "Support Bot",
  "company": "Acme Inc",
  "welcomeMessage": "Hi! How can I help you today?",
  "quickReplies": ["Pricing", "How to get started", "Talk to support"],
  "theme": {
    "primaryColor": "#3737f6",
    "position": "bottom-right"
  }
}

{
  "projectSlug": "my-store",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "messages": [
    { "role": "user", "content": "What is your return policy?" }
  ]
}

curl -X POST https://app.helpyap.com/api/v1/chat-messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hy_live_your_api_key" \
  -d '{
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "content": "Your trial workspace is ready. Want help connecting Slack?",
    "email": "ada@example.com"
  }'

curl -X PATCH https://app.helpyap.com/api/v1/approvals \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hy_live_your_api_key" \
  -d '{
    "approvalRequestId": "approval_123",
    "conversationId": "conversation_123",
    "decision": "approved"
  }'

curl -X PUT https://app.helpyap.com/api/v1/workflows \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hy_live_your_api_key" \
  -d '{
    "workflows": [
      {
        "id": "sla-risk",
        "name": "SLA risk",
        "enabled": true,
        "condition": { "type": "sla_due_soon" },
        "actions": [
          { "type": "add_tag", "tag": "sla-risk" },
          { "type": "set_status", "status": "needs_followup" }
        ]
      }
    ]
  }'

curl -X POST https://app.helpyap.com/api/v1/custom-domains \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hy_live_your_api_key" \
  -d '{
    "hostname": "help.example.com",
    "surface": "all"
  }'

curl -X PUT https://app.helpyap.com/api/v1/branding \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hy_live_your_api_key" \
  -d '{
    "removeHelpYapBranding": true,
    "publicBrandName": "Acme Support",
    "logoUrl": "https://example.com/logo.png",
    "faviconUrl": "/favicon.ico",
    "supportUrl": "https://support.example.com"
  }'

curl -X PUT https://app.helpyap.com/api/v1/enterprise \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hy_live_your_api_key" \
  -d '{
    "supportTier": "enterprise",
    "prioritySupport": true,
    "invoiceBilling": true,
    "billingContactEmail": "ap@example.com",
    "billingPaymentTerms": "net_60",
    "dedicatedSlackChannel": "#acme-support",
    "csmName": "Ada Lovelace",
    "csmEmail": "ada@example.com",
    "soc2ReportUrl": "https://example.com/security/soc2.pdf",
    "securityContactEmail": "security@example.com"
  }'

curl -X POST https://app.helpyap.com/api/v1/channel-replies \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hy_live_your_api_key" \
  -d '{
    "conversationId": "conversation_123",
    "content": "Thanks for the details. I checked this and your WhatsApp integration is now connected."
  }'

curl -X PUT https://app.helpyap.com/api/v1/ai-tools \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hy_live_your_api_key" \
  -d '{
    "agentToolsEnabled": true,
    "inAppSupportEnabled": true,
    "actionSuggestionsEnabled": true,
    "conversationMemoryEnabled": true,
    "learningLoopEnabled": true,
    "allowedInAppActions": [
      "summarize_account_context",
      "check_knowledge_base_status",
      "create_bug_report"
    ],
    "customTools": [
      {
        "name": "lookup_order",
        "description": "Lookup order status by order id.",
        "endpoint": "https://api.example.com/support/orders",
        "method": "GET",
        "params_schema": { "type": "object" }
      }
    ]
  }'

curl -X POST https://app.helpyap.com/api/v1/email-campaigns \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hy_live_your_api_key" \
  -d '{
    "name": "June newsletter",
    "subject": "New support workflows are live",
    "previewText": "See what changed this month.",
    "body": "Your team can now route, summarize, and approve support workflows faster.",
    "audience": "active_customers",
    "status": "draft"
  }'

curl -X POST https://app.helpyap.com/api/v1/announcements \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hy_live_your_api_key" \
  -d '{
    "title": "New AI inbox summaries",
    "body": "Agents can now review every handoff faster.",
    "kind": "release_note",
    "status": "published",
    "ctaLabel": "Read more",
    "ctaUrl": "https://example.com/releases/ai-summaries"
  }'

curl -X POST https://app.helpyap.com/api/v1/engagement-guides \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hy_live_your_api_key" \
  -d '{
    "title": "Connect your first channel",
    "description": "Guide new admins through setup.",
    "kind": "checklist",
    "status": "published",
    "steps": [
      {
        "title": "Connect Slack",
        "body": "Route escalations into your team channel.",
        "ctaLabel": "Open integrations",
        "ctaUrl": "https://example.com/admin/integrations"
      }
    ]
  }'

curl -X POST https://app.helpyap.com/api/v1/survey-responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hy_live_your_api_key" \
  -d '{
    "question": "What stopped you from upgrading?",
    "response": "I need invoice billing.",
    "visitorEmail": "ada@example.com",
    "pageUrl": "https://example.com/pricing",
    "metadata": { "plan": "business" }
  }'

curl -X POST https://app.helpyap.com/api/widget/salespop-push \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sp_your_push_secret" \
  -d '{
    "project": "my-store",
    "type": "signed_up",
    "name": "Sarah K.",
    "location": "Austin, TX",
    "product": "Pro Plan"
  }'